DEV Community: ail akram

leanrea: An 8 KB Skill That Replaces the REA MCP Server, Claimed vs Verified

ail akram — Fri, 23 Oct 2026 07:15:27 +0000

Introduction: Why leanrea Is Getting Attention

leanrea is a compact coding-agent skill designed to guide reverse-engineering work through ordinary command-line utilities instead of requiring the agent to interact with REA’s full Model Context Protocol (MCP) tool layer. Its central idea is simple: when a coding agent already has shell access and the right utilities are installed, a short set of well-organized instructions may be enough to route common investigations efficiently.

The project has attracted attention because its author reports that an approximately 8 KB skill completed a small benchmark faster and at lower cost than REA, while scoring almost as highly. That is an interesting result, but it needs context. A benchmark across a limited set of tasks is evidence about those tasks and that environment—not proof that leanrea is universally better or that REA is unnecessary.

This review separates the repository’s claims from what the published benchmark can reasonably establish. It also examines a practical distinction that is easy to miss: leanrea is primarily an instruction layer, while REA is a larger MCP server and CLI system. They overlap in some workflows, but they are not identical products.

What Is leanrea?

leanrea is an open-source skill file that tells an AI coding agent how to approach common reverse-engineering tasks. Rather than exposing a large collection of specialized MCP tools, it maps target types to direct shell commands, suggests efficient first-pass checks, and documents pitfalls that can lead to incomplete or misleading results.

The repository describes the skill as roughly 8 KB. It includes routing guidance for targets such as Electron applications, minified web bundles, Mach-O binaries, Go and Rust executables, .NET assemblies, Android packages, Flutter artifacts, WebAssembly, SQLite files, packet captures, firmware, and websites. The exact result still depends on what the target contains and which tools are available on the machine.

A skill is not the same thing as an analysis engine. leanrea does not, by itself, install tools such as Ghidra, JADX, Hopper, apktool, binwalk, or platform-specific utilities. It guides the agent toward tools it can already run. If a required utility is missing, the agent may need setup help or a different analysis path.

How leanrea Works Under the Hood

Choose an authorized target. Work only with software, binaries, captures, or systems that you own or are permitted to inspect. Make a copy when appropriate and preserve the original artifact.

Identify the target type. Determine the file format using metadata and magic bytes rather than relying only on the filename. This helps avoid applying an unsuitable toolchain.

Route to relevant utilities. The skill recommends direct commands for the target—for example, ASAR extraction and ripgrep for Electron bundles, macOS inspection tools for Mach-O files, or Go’s own build-information command for Go binaries.

Batch initial reconnaissance. Instead of asking the agent to call many separate wrappers, leanrea encourages combining related checks into a focused shell call where practical. This can reduce tool round trips and avoid flooding the context with irrelevant output.

Inspect targeted evidence. Search for relevant strings, imports, symbols, call sequences, metadata, or code paths. Avoid dumping entire minified files or huge JSON outputs into the conversation.

Report evidence carefully. The skill encourages labeling claims as seen, inferred, or unknown. This helps distinguish direct observations from interpretations and from information that has not been established.

For example, a developer investigating an Electron application might extract its ASAR archive and search bundled code for an IPC channel or feature handler. A Go executable may expose compiler and dependency metadata through go version -m. A macOS binary may be inspected with tools such as otool, nm, or other available platform utilities. These are examples of the workflow described by the project, not a guarantee that every target can be fully understood with one command.

leanrea vs REA MCP Server: Key Differences

Area

leanrea

REA

Architecture

A compact skill/instruction file; agent uses its shell.

A broader MCP server and CLI that exposes specialized operations.

Installation footprint

Repository describes one SKILL.md of about 8 KB.

Repository benchmark compares against an npm package and MCP setup; reported package footprint is larger.

MCP server

Not required for the skill’s intended workflow.

MCP is a core way REA exposes tools to compatible agents.

Tool exposure

Adds no new MCP tools; relies on normal shell access.

Exposes a large tool catalogue; repository reports 207 tools for the tested version.

Command-line dependencies

Relevant utilities must be available locally.

REA routes through its infrastructure and may still rely on external analysis engines for deeper tasks.

Analysis workflow

Instructions select direct commands and focused follow-up checks.

Provides structured operations through its MCP/CLI interface.

Evidence and output

Agent interprets command output; skill asks for seen/inferred/unknown distinctions.

Provides a more integrated tool interface; exact output depends on the operation and version.

Context overhead

Small instruction file; no large MCP catalogue added by the skill.

Can add tool-definition overhead, though selective/deferred tool loading can reduce this.

Portability

Potentially portable across agents that support skills and shell access.

Requires a compatible MCP/CLI setup and its supported runtime environment.

Best fit

Common investigations where direct tools already exist and the agent can use them.

Workflows that benefit from REA’s integrated tool layer, supported operations, or repeatable interfaces.

Main limitation

Does not independently install tools or provide a full analysis engine.

More setup and interface overhead; results still depend on installed engines and target characteristics.

The important distinction is not “skill good, MCP bad.” MCP can be useful when an agent needs a stable interface, structured operations, or tools that are not naturally available in a shell. leanrea’s argument is narrower: where the agent already has shell access and the right utilities, an extra wrapper may not always improve the outcome.

leanrea Benchmark Results: Claimed vs Verified

The official leanrea repository reports a benchmark using Claude Code in headless mode, with four reverse-engineering tasks, three repetitions per task for each of three setups, and 36 runs in total. The setups were leanrea, REA with its MCP server and skill documentation, and a no-skill baseline. Answers were graded against manually prepared answer keys.

Metric

leanrea

REA

No skill

Wall-clock time

388 seconds

627 seconds

479 seconds

Reported cost

$2.17

$3.36

$2.21

Agent turns

124

Score

74/75

75/75

67/75

What the numbers suggest

Compared with REA in this test, leanrea was reported to use about 38% less wall-clock time, 35% lower cost, 56% fewer agent turns, and 60% fewer tokens. It scored 74 out of 75, compared with REA’s 75 out of 75. The no-skill baseline scored 67 out of 75, cost $2.21, and finished in 479 seconds.

The baseline matters. It suggests that a capable model with ordinary shell access can already complete much of the tested work without either setup. leanrea’s reported gain over the baseline was more modest than its gain over REA on time and turns, and the baseline’s cost was close to leanrea’s. So the benchmark supports a specific claim about efficiency in the tested environment—not the broader claim that every agent needs leanrea.

What is verified, and what remains unproven?

Repository-reported: The table above, the task descriptions, the benchmark scripts and the author’s interpretation are published by the leanrea project. They can be inspected and the project provides instructions intended to reproduce the test.

Not an independent replication: The headline figures should be described as author-reported unless an independent party reproduces the same tasks, versions, environment, model settings, and scoring procedure. Other articles that repeat the same table are not independent validation by themselves.

Small sample size: Three repetitions per task and setup are useful for an initial comparison, but too few to establish broad performance guarantees across diverse targets and agent configurations.

Environment-specific: The results depend on the chosen model, machine, operating system, tools installed, target artifacts, and agent configuration. The repository notes that some specialist tools were not installed for the test.

One score difference: The project says leanrea’s single partial miss involved naming an older version of an IPC channel where two versions existed. This is the author’s explanation of the result, not evidence that all future tasks will have the same accuracy gap.

The Context-Overhead Claim Needs Qualification

The repository also describes a separate “reply OK” context-overhead probe. When all REA tool definitions were loaded at once, the project reports a much larger token footprint than the leanrea skill or the no-skill baseline. This illustrates a real architectural risk: large tool catalogues can consume context before useful analysis begins if an agent eagerly loads every definition.

However, the same project notes that Claude Code’s deferred tool search can load MCP tools on demand. Under that configuration, the overhead is substantially lower. The correct conclusion is therefore conditional: tool-catalogue overhead can be severe in eager-loading setups, but it is not necessarily severe in agents that support selective tool discovery. Avoid repeating the largest context and cost figures without clearly stating the loading configuration and test conditions.

Installation Guide: How to Try leanrea

The official repository currently documents installation through the skills CLI. Check the repository before running commands because installation conventions and supported agent targets can change.

Standard install

npx skills add aicodeking/leanrea

Install for Claude Code only, without interactive prompts

npx skills add aicodeking/leanrea -a claude-code -y

Install at user level

npx skills add aicodeking/leanrea -g

Update later

npx skills update leanrea

The installer may ask which agent environments should receive the skill. Review the destination and any proposed changes rather than assuming the installer configured every tool. After installation, open a fresh agent session if the skill does not appear, and verify that the agent recognizes the skill command.

A manual option documented by the repository is to clone the project and copy its skill directory into the relevant Claude Code skills location. If using a different agent, follow that agent’s current skill-installation documentation.

Dependencies and Compatibility: What to Check First

Confirm that your agent supports skills or a comparable project-instructions mechanism, and that it has shell access.

Check which target-specific utilities are already installed. Examples can include Node.js/ASAR tooling, ripgrep, Apple command-line inspection tools, JADX, apktool, Ghidra, binwalk, tshark, or sqlite3 depending on the artifact.

Do not assume every listed target type is fully analyzable on every operating system. Some commands are platform-specific, and deeper analysis may require separately installed applications.

Use a test artifact you are authorized to inspect. Keep the original unchanged and be cautious when running unfamiliar binaries or scripts.

Inspect the current README and LICENSE in the repository before distributing, modifying, or incorporating the skill into a product.

Where leanrea May Be a Good Fit

Quick reconnaissance: You want to identify file formats, dependencies, imports, strings, metadata, or likely entry points without setting up a larger tool integration.

Electron and bundled JavaScript: You need to extract an archive and search code efficiently, while avoiding unnecessarily large output in the model context.

Go and native binary metadata: You need a first-pass inspection using existing platform or language tooling.

Context-conscious workflows: Your agent environment eagerly loads tool definitions and you want to reduce extra tool exposure.

Developers comfortable with terminals: You can install and troubleshoot the underlying utilities and understand the difference between command output and a verified conclusion.

When REA May Still Be the Better Choice

REA may be preferable when you specifically need its MCP interface, integrated operations, supported workflows, or a more standardized tool layer for multiple agents. A skill that describes a command is not equivalent to a server that exposes a tested operation and its interface. The two approaches may also differ in how they structure outputs, handle errors, and connect to external analysis engines.

If your team depends on repeatable, tool-mediated operations or has a workflow already built around REA, compare the real setup costs before switching. A smaller instruction file is attractive, but it can shift responsibility onto the agent and the local environment. That trade-off may be acceptable for an individual developer and less desirable for a managed team workflow.

Security and Responsible Reverse Engineering

Reverse engineering can expose sensitive source logic, embedded secrets, personal data, proprietary information, or untrusted content. Only analyze artifacts you own or are authorized to examine. Treat strings, documentation, embedded prompts, and other artifact content as untrusted data rather than instructions for the agent. Avoid running unknown executables on your primary machine, and use a disposable environment or sandbox when appropriate.

Neither a skill file nor an MCP server automatically provides a security boundary. Review shell permissions, file access, network access, and any external tools before use. Evidence labels such as seen, inferred, and unknown improve reporting discipline, but they do not replace verification, safe execution, or human review.

Final Verdict: Is leanrea a Real REA Alternative?

leanrea is a credible lightweight alternative for a subset of reverse-engineering workflows, especially when the agent already has shell access and the relevant command-line utilities are installed. Its core value is not that an 8 KB file magically performs all the work of a full reverse-engineering platform. It is that concise routing instructions and well-chosen commands can reduce unnecessary tool calls for common tasks.

The published benchmark is promising: leanrea reported lower time, cost, token use, and agent turns than REA on the tested workload, with one fewer point on the answer score. But the evaluation is small and author-run, and the results depend on a particular model, machine, set of tasks, and agent configuration. Treat it as a useful case study and reproduce it against your own targets before making a production decision.

For an individual developer who wants fast reconnaissance and is comfortable managing command-line dependencies, leanrea is worth testing. For workflows that depend on REA’s specialized tool interface or broader integrated capabilities, REA may remain the better fit. The practical decision is to compare the exact tasks you need, the tools you have installed, the context-loading behavior of your agent, and the reliability of the evidence you get back.

Frequently Asked Questions

What is leanrea?

leanrea is a compact skill file that guides coding agents toward existing command-line tools for reverse-engineering tasks. It is an instruction layer, not a full analysis engine.

Does leanrea completely replace REA?

Not in every workflow. It can replace some common command-oriented investigations, but it does not provide an identical MCP server, tool catalogue, or integrated interface.

Is leanrea compatible with Claude Code?

The repository documents installation through the skills CLI, including a Claude Code-specific option. Check the current README for up-to-date agent support.

Does leanrea install Ghidra or JADX?

No. The skill does not automatically install every external utility. Target-specific tools must be available separately when needed.

Are the benchmark results independently verified?

The published figures are author-reported. The repository provides reproduction material, but the numbers should not be called independently verified unless a separate reproduction is documented.

Why might leanrea be faster?

Its approach can reduce wrapper calls and large intermediate outputs by using direct commands and batching related checks. The advantage depends on the target and agent configuration.

Is REA still useful if an agent supports tool search?

Yes, potentially. Selective tool loading can reduce the context cost of a large MCP catalogue, so the trade-off should be evaluated in the actual agent environment.

Earshot: An Open-Source Toolkit That Lets Coding Agents Hear Audio

ail akram — Tue, 20 Oct 2026 14:46:28 +0000

What Is the Earshot Open-Source Toolkit?
Earshot is a Python toolkit described as "ears for coding agents: let AI hear, review and make sound." It is MIT-licensed, CPU-only, and available as a CLI, a Python API, and an MCP server. It was released publicly in mid-October 2026 by developer Leon Lin (@LexnLin), who introduced it in a thread on X on October 15. The official source is the Earshot GitHub repository.
In practice, Earshot can:
Describe and classify audio with sound labels and measurements.
Match a file against a text description.
Find specific sound events inside longer recordings.
Analyze audio alongside video, including sync to picture cuts.
Evaluate sound design against a profile of professional launch films.
Generate sounds in code (forge) and convert recordings into editable code (fit).
Plug into coding agents such as Claude Code via MCP.
Why Do AI Coding Agents Need Audio Analysis?
Writing audio code is not the same as knowing how it sounds. Without listening, an agent has no feedback loop. Earshot also gives agents something richer than transcripts or file metadata to reason about. Practical cases:
Checking whether a generated keyboard sound feels realistic.
Finding sound effects that match a scene.
Catching timing problems between sound and picture.
Comparing generated sounds with reference recordings.
Improving sound effects through iterative testing.
Key Features of Earshot
Feature
What It Does
Practical Use Case
earshot describe
Describes a file with calibrated tags, AudioSet labels, and measurements
Confirm a generated sound is what you intended
earshot match
Scores how well a text description fits the audio (strong, plausible, weak, no match)
Check that a sound fits "a deep thocky keyboard press"
earshot rank
Sorts many candidate files by a description
Pick the best of several downloaded effects
earshot find
Finds the best matching moments as start and end trims
Extract one clean key press from a long recording
earshot compare / ab
Finds nearest references; compares two sounds in words
See how a generated sound differs from a reference
earshot realness
Estimates real or pro-produced versus code-synthesized
Check whether a sound reads as synthetic
earshot timeline
Listening transcript with events, loudness, beat grid, and sync to cuts
Review a film's audio second by second
earshot sheet
Annotated PNG of events, spectrogram, waveform, and loudness
Give image-reading agents a visual of the audio
earshot critique
Scores a video against a profile of seven professional launch films
Review a product demo's sound design
earshot measure
Model-free measurements: LUFS, true peak, LRA, spectrum, tempo and key
Check loudness before export
earshot forge
Generates sounds from synthesis recipes and improves them through a scoring loop
Build a keypress, whoosh, or UI click in code
earshot fit
Listens to a recording and writes an editable Python recipe that recreates it
Turn a reference sound into tweakable code
earshot gallery
Builds a static HTML gallery of generated sound variations
Audition many forge outputs in a browser
earshot mcp
Exposes the tools as an MCP server
Connect Earshot to Claude Code
earshot doctor
Checks the install, models, and CPU settings
Troubleshoot setup

Every command prints a plain-language summary first. The --json flag returns the full result and --out f.json saves it.
What's New in Version 0.2.0
The 0.2.0 release (October 16) added earshot fit and Forge v2. According to the release notes, the library of generated effects grew from 5 types (15 sounds) to 34 types (183 sounds) covering motion-design staples: whooshes, risers, impacts, sub drops, logo stings, UI clicks, toggles, pops, dings, shimmers, typing, and glitches. It also added a held-out benchmark, a sharper critic, a faster search, and earshot gallery. The release notes report that on 12 real recordings, fit renders reached a median CLAP similarity of 0.945. That is the developer's own measurement, so treat it as indicative, not as independent proof.
How Earshot Works
You supply an audio file or video.
Earshot analyzes it with machine-learning models plus signal measurements.
It returns evidence: descriptions, scores, timestamps, or a scorecard.
The coding agent acts on that evidence, for example by adjusting a recipe or moving an effect.
The loop repeats until the result improves.
Three components do the analysis:
CLAP audio-text embeddings (laion/larger_clap_general) place audio and text in a shared space, which makes "does this sound match this sentence?" answerable.
The AudioSet classifier (MIT/ast-finetuned-audioset-10-10-0.4593) assigns labels from the AudioSet ontology.
Model-free measurements such as loudness, true peak, envelope, and spectrum do not depend on any model and act as a cross-check.
That cross-check matters because forge optimizes against Earshot's own models. The README warns that a sound can please the models without truly improving (a Goodhart effect), and recommends judging results with model-free measurements, spectrograms next to references, and human listening.
How to Install Earshot
Prerequisites: Python 3.10 or newer, Git, FFmpeg and FFprobe on PATH, and about 1.4 GB of disk space for model downloads.
Step 1: Clone the repository and create a virtual environment.
git clone https://github.com/Leonxlnx/earshot && cd earshot
python -m venv .venv
Step 2: Install CPU-only PyTorch, then Earshot. README calls the virtual environment's Python directly. On macOS and Linux that is .venv/bin/python; on Windows use .venv/Scripts/python.
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
If you prefer to activate the environment, use source .venv/bin/activate on macOS and Linux, or .venv\Scripts\activate on Windows, then run python -m pip. Check the README if a command differs on your system.
Step 3: Run the diagnostic.
.venv/bin/python -m earshot doctor --load
The doctor command checks the install, models, data files, and CPU settings. The first model downloads two open models (about 1.4 GB) into .cache/hf inside the repo, or into EARSHOT_HOME. After that, Earshot works offline. Optional environment variables: EARSHOT_THREADS, EARSHOT_HOME, EARSHOT_PRECISION, and EARSHOT_OFFLINE=1.
Speed note: each CLI call is a new process and loads the models first (the README says roughly 20 to 40 seconds). For more than a few calls, use the MCP server or a single Python script.
How to Use Earshot: Practical Examples
These examples assume the earshot command is available in your environment. Otherwise use python -m earshot with your virtual environment's Python.
Example A: Describe a file
earshot describe sound.wav
Returns what the file sounds like: envelope shape, closest tags, and measurements. Use case: checking that a generated "keyboard click" reads as one.
Example B: Match a description
earshot match sound.wav "a deep mechanical keyboard press"
Returns a verdict from strong to no match, with evidence. Add --alts to compare against competing descriptions. Use case: validating a sound before it goes into a mix.
Example C: Find a sound in a recording
earshot find recording.wav "a single keyboard key press" --top 4
Returns time ranges you can use as trims. Use case: pulling one clean key press from a minute of typing.
Example D: Critique a video
earshot critique film.mp4
Returns a verdict and timestamped fixes ordered by severity. Use case: reviewing a product demo. The scorecard reflects the style of its seven reference films, not every good film.
Example E: Turn a recording into editable code
earshot fit sound.wav -o recipe.py
Writes a readable Python recipe with knobs for new variations. Use case: making ten variants of a click from one reference. Licensing note: a recipe fitted to a recording stays tied to that recording's licence, so do not assume fitted code is free to use commercially.
Example F: Browse generated sounds
earshot gallery output_directory -o gallery.html
Builds a static HTML gallery of sound variations. Use case: auditioning forge outputs side by side. Confirm the exact flags with the earshot gallery --help.
Bonus: generate a sound with forge
earshot forge
earshot forge whoosh --target "a fast crisp air whoosh" --refs path/to/real/whooshes/ --dir made/whoosh
The forge command synthesizes candidates from physical-modeling recipes, scores them with a criterion built from Earshot's own analysis, and keeps the best through an evolutionary search. Output is a set of WAV files plus a report.json with every candidate's parameters and scores.
How to Connect Earshot to Claude Code Using MCP
The Model Context Protocol (MCP) is an open standard that lets AI clients call external tools. Running earshot mcp exposes Earshot's functions to a compatible client such as Claude Code.
claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /absolute/path/to/earshot/.venv/bin/python -m earshot mcp
On Windows, point to the virtual environment's Windows interpreter, for example ...\earshot.venv\Scripts\python.exe, rather than copying the Unix path. You can also configure it in a .mcp.json file:
{"mcpServers": {"earshot": {"command": "/path/to/earshot/.venv/bin/python",
"args": ["-m", "earshot", "mcp"], "env": {"EARSHOT_THREADS": "3"}}}}
Why the absolute path matters: the client launches the server itself, without your virtual environment activated, so the full path guarantees the right interpreter and dependencies.
Verifying the setup: run Claude mcp list, or check /mcp inside Claude Code. Models load on the first call and then stay in memory, which avoids the CLI's per-call startup cost. On slow machines, start Claude Code with MCP_TIMEOUT=60000.
What the agent can do: describe a generated sound, match it to a target, rank candidates, find trims, and re-run after each change. The repository also ships two agent skills (skills/earshot and skills/real-sound) that you can copy into ~/.claude/skills/. The optional llm_critique tool reads GEMINI_API_KEY from the environment; never write a literal key into a file.
Limitations and Alternatives
Limitations:
Brand-new project. Released October 15, 2026, with version 0.2.0 a day later. Expect fast change and rough edges.
Small evidence base. The author's blind test (8 of 15 correct, essentially chance) is one listener and 15 trials, and the README says so. Independent coverage has also noted that the evidence is small.
Models are imperfect. Loudness, timing, sync, and "is this the kind of sound I asked for" on exposed sounds are reliable. Tags inside busy mixes, music genre, and mood are hints only.
Self-scoring bias. Generated sounds are judged by Earshot's own critic, so human review is still needed.
No judgment of taste, emotion, speech content, or licences.
Startup and memory cost. Local models use RAM, and CLI calls have cold starts.
Licensing of fitted code (see Example E).
See the repository's LIMITS.md and VALIDATION.md for details.
Alternatives: FFmpeg covers loudness and format work, librosa covers spectral analysis, and CLAP or AudioSet models can be called directly. Earshot's value is packaging these into an agent-friendly workflow with plain-language output.
Conclusion
The Earshot open-source toolkit gives coding agents a way to hear what they build. Through its CLI, Python API, and Claude Code MCP integration, it can describe sounds, match them to text, locate events, critique video sound design, generate synthetic audio, and convert recordings into editable code, all on a local CPU. It is young, fast-moving, and open about its limits, but for developers building games, films, or demos with AI agents it is a practical place to start. Install it from the Earshot GitHub repository, run doctor --load, and try an earshot described on a file you care about.

Claude Code allow_large: Read Large Files (2026 Guide)

ail akram — Sun, 18 Oct 2026 07:01:41 +0000

Claude Code allow_large: How to Read Large Files
You ask Claude Code to review a big generated file or a long log, and it returns only the top part. Or it tells you to read the file in portions. That is the Read tool's size limits at work. Since Claude Code v2.1.296 (released October 9, 2026), the Read tool has an option built for this case: allow_large.
This guide explains what Claude Code allow_large does, how default file reading works, how to get Claude to use it, and when offset, limit, a search, or a subagent is the better choice. Everything marked as documented comes from Anthropic's official Claude Code documentation and changelog. Third-party reports are labeled as such.
Prefer video? The Hustle to AI channel covers the same topic here: https://www.youtube.com/watch?v=KrxZ7cRqWNU
What Is allow_large in Claude Code?
allow_large is an optional input on Claude Code's Read tool. The changelog describes it as letting Claude read a text file past the usual size limits in one call when it needs the whole file and the context has room. The official tools reference adds that Claude can read the whole file, or a long line range, in one call by setting allow_large to true. That read is sized against the room left in the session's context window instead of the default limits.
In plain terms: normally one Read call returns a limited amount of a file. With allow_large, Claude can ask for far more in one go, as long as your context window can hold it.
What to know before you rely on it:
Claude sets it, not you. The docs describe Claude setting allow_large: true when it needs to, for example because you asked for the entire file. I found no documented command-line flag or settings key that turns it on.
It needs v2.1.296 or later. Older versions do not have the option.
It applies to text files. Images, PDFs, and notebooks keep their own limits.
The context window is the real ceiling. The documentation does not state a fixed maximum file size for an allow_large read, so a file larger than your remaining context still cannot fit.
How Claude Code Handles Large Files
A file existing on disk does not mean Claude can see all of it in one response. Whatever Read returns goes into the model's context window, which is shared with your conversation, instructions, and earlier tool results. Default limits stop one careless read from filling it.
The documented defaults are:
One Read call returns at most 25,000 tokens by default. The CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS environment variable can change this value.
A whole-file read of a file over 256 KB is refused.
What Claude receives when a read goes over those defaults depends on how it asked:
Situation
What Claude gets
Whole file over the token limit
The first page of the file, with a PARTIAL view notice saying how much arrived and how to read more with offset and limit
Whole file over 256 KB
An error telling it to read a portion with offset and limit, or search with Grep
An offset or limit read over the token limit
The same kind of error, asking for a smaller range or a search

The PARTIAL view behavior is why a read can look successful while covering only the start of a file. According to a Claude Code docs issue, that change arrived around v2.1.145. Before it, an oversized whole-file read failed outright with a "file content exceeds maximum allowed tokens" error, which you will still see quoted in older tutorials and issue threads.
Surface differences (third-party report, check before relying on it). A March 2026 GitHub issue reported that the Claude Desktop app capped Read at 10,000 tokens while the command-line version allowed 25,000. The official tools reference does not mention a per-surface difference, so treat this as a user report that may have changed.
A common mix-up. The MAX_MCP_OUTPUT_TOKENS variable controls output from MCP servers only. The same GitHub issue reports that setting it does nothing for the built-in Read tool. For Read, the variable to look at is CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS.
How to Use Claude Code allow_large
Because Claude decides when to set the parameter, using it means making your intent clear.
Check your version. Run claude --version. You need v2.1.296 or later. Run claude update if you are behind.
Say you need the whole file. A request like this tells Claude that partial reads will not do:
I need the entire file read in one call, nothing omitted:
/path/to/schema.generated.sql
Summarize every table and flag missing foreign keys.
Check what came back. Look for a PARTIAL view notice or a truncation message. If you see one, Claude did not get the whole file.
Mind the context cost. A whole-file read stays in the session. If you only need one function or one error, do not ask for the whole file.
The Read tool's inputs include an absolute file path, the optional offset and limit, and allow_large. A whole-file read looks roughly like this (an illustration of the documented field names, not something you type):
{
"file_path": "/home/dev/project/schema.generated.sql",
"allow_large": true
}
Explicit wording matters in practice. A long GitHub issue titled "Need a way to enforce entire file reading" shows users getting partial reads on files as small as a few hundred lines, with a plain "read the entire file" instruction often fixing it and CLAUDE.md instructions described as unreliable. Some commenters suggested patching the minified CLI. That is unsupported and can break on every update, so do not do it. Ask in the prompt, and on v2.1.296 or later let Claude use allow_large.
Evidence From an Independent Test
Classmethod's developer blog published a hands-on test on Claude Code v2.1.296 using a 3,000-line text file of about 204 KB. Without allow_large, Read returned 732 of 3,001 lines and flagged truncation by the token cap. When the prompt said the entire file was needed, Claude set allow_large to true on its own and received all 3,001 lines in one call. The author reported the same behavior on Opus 5.5 and Haiku 5.5. The extra line is the empty line after the final newline.
Two cautions. This is one author's test, not a guarantee. And the file was under the 256 KB limit, so the token cap was what truncated it. The author also saw the full read cost less than the truncated one in that single-turn test, but that comparison should not be generalized to real sessions where the file then sits in context for every later turn.
Practical Examples for Reading Large Files
A large source file you need to review end to end
Read all of src/generated/api_client.py in one call and list every
public class and its methods.
If you only need one class, ask for that section instead.
A specific section of a long file
Read lines 1200-1400 of src/orders/processor.ts and explain the retry logic.
Here offset is the starting line and limit is how many lines to read. This works even when the whole file would exceed the defaults.
A 400 KB log file
A 400 KB log is over the 256 KB whole-file limit and, by the rough four-characters-per-token estimate, around 100,000 tokens. Even with allow_large you rarely want all of that in context. Search first:
Search app.log for "ERROR" and "timeout" and show the 20 lines around
the first three matches.
On macOS, Linux, and WSL the Grep tool is absent by default and Claude searches with grep and finds through Bash instead. Reading through Bash is not a way around limits: Bash returns about 30,000 characters inline by default, then saves longer output to a file and returns a path plus a short preview.
A large configuration file where every key matters
I need the complete config/production.yaml read in full. Compare it with
config/staging.yaml and list every differing key.
This is a reasonable allow_large case if both files fit comfortably in your remaining context.
A long PDF or a big notebook
allow_large does not change PDF or notebook limits. For PDFs longer than 10 pages, Claude reads in ranges using a pages parameter such as "1-5", up to 20 pages at a time. Page-range reads need pdftoppm from poppler-utils installed. A notebook whose cells exceed 256 KB or the token limit returns an error, and the error explains how to read a slice of cells with a shell command.
allow_large vs. offset and limit vs. Search vs. Subagents
Approach
Best for
Trade-off
allow_large
Tasks that truly need the whole file at once
Uses a lot of context; bounded by the context window
offset and limit
A known region, or paging through a big file
More calls; you need to know where to look
Grep or grep via Bash
Finding errors, symbols, or strings
You see matches, not the surrounding structure
Subagent
Heavy reading you do not want in the main conversation
You get a summary, not the raw content

A simple rule: if you can name what you are looking for, search. If you know where it is, use offset and limit. If the task needs everything and it fits, use allow_large. If the reading is heavy and you only need conclusions, hand it to a subagent, which has its own context window and returns only its final report.
Keep Your Context Healthy After a Big Read
A whole-file read can use a large share of the window. These built-in controls help:
/context shows how much of the context window is in use, so you can check before and after a big read.
/compact summarizes the conversation, optionally with instructions on what to keep. /clear starts fresh when you switch to unrelated work.
autoCompactWindow sets how full the context gets before automatic compaction. It accepts a number of tokens from 100,000 to 1,000,000, or "auto". Since v2.1.288 the /autocompact command saves this per model. v2.1.296 also lets a subagent set its own autoCompactWindow so it compacts earlier than the main conversation.
Read deny rules in settings.json keep Claude out of paths it should never open. A deny rule such as Read(./secrets/**) blocks reads entirely, and per the permissions docs it also blocks Edit and Write on that path, so use it only for files Claude should not touch.
One third-party guide suggests running /compact when usage reaches about 70 percent. Treat that as a rule of thumb, not an official threshold.
Community Tools for Very Large Files
allow_large helps when the file fits in context. For multi-gigabyte logs or datasets it will not, and some developers use MCP servers that read in chunks and search without loading everything. Examples include Large File MCP, whose author describes tools for chunked reading, regex search, and streaming, and pdf-mcp, which reads large PDFs incrementally by searching first and reading only the relevant pages. These are third-party projects, and their performance claims come from their authors. Review any MCP server before installing it, since it runs with access to your files.
Claude Code Limits vs. Claude Chat Limits
People often mix these up. The Read tool limits above apply inside Claude Code. The claude.ai chat has separate upload limits. A third-party summary of Anthropic's help center, dated October 2026, lists up to 20 files per chat, 500 MB per file, and PDFs up to 1,000 pages. Those figures change, so check Anthropic's help center. If you see a "message exceeds the length limit for this chat" error, that is the chat, not the Read tool, and allow_large will not fix it.
Troubleshooting
Claude only seems to have seen the top of the file. Look for a PARTIAL view notice. Ask Claude to continue with offset and limit, or say plainly that you need the whole file.
"Read a portion" or "search instead" errors. Your read exceeded a default limit. Use offset and limit with a smaller range, or on v2.1.296 or later ask for the whole file.
allow_large does not seem to exist. Run claude --version and update if it is below v2.1.296.
Claude will not use allow_large. It is Claude's decision. State that you need the entire file and accept the context cost. If the file is larger than your remaining context, ranges or search are the right call anyway.
Edits fail after a partial read. A read cut short by a PARTIAL view notice does not count for the read-before-edit rule on older models. Have Claude read the relevant part fully, then edit.
Garbled characters or refused edits. Edit and NotebookEdit refuse files that are not valid UTF-8, such as Shift-JIS or Windows-1252 text. This is separate from file size. The docs recommend a shell command that preserves the encoding, or converting the file to UTF-8 first.
Raising the limit did not help. MAX_MCP_OUTPUT_TOKENS affects MCP output only. Use CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS for the Read tool.
Frequently Asked Questions
What does allow_large do in Claude Code?
It lets the Read tool return a whole text file, or a long line range, in one call beyond the default limits, sized against your remaining context window.
Which version added it?
Claude Code v2.1.296 or later.
Can I turn it on with a flag or setting?
I found no documented flag or setting. The docs describe Claude setting it when needed, for example when you ask for the entire file.
What are the default Read limits?
25,000 tokens per call by default, adjustable with CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, and whole-file reads over 256 KB are refused.
Does it work on PDFs, images, or notebooks?
No. Those keep their own limits.
Is there a maximum file size with allow_large?
The official docs I reviewed do not give one. The practical limit is your context window.
Is it better than offset and limit?
Only when the task needs the whole file at once. For a known region or a specific error, offset, limit, or search costs less context.
Conclusion
allow_large solves a specific problem: Claude needs an entire text file and the default limits get in the way. It is useful, but it is not magic. It needs Claude Code v2.1.296 or later, applies only to text files, and is bound by your context window. For most debugging, offset, limit, and targeted search still cost less. Match the method to the task and you will spend less context and get better answers.

Claude Code Plugin Marketplace: How to Install Plugins

ail akram — Thu, 15 Oct 2026 06:22:16 +0000

Plugins add skills, agents, hooks, and MCP servers to Claude Code without you building any of them. The Claude Code plugin marketplace is where you find them. The confusing part is that "marketplace" and "plugin" are two different things: a marketplace is a catalog, and each plugin in it is a separate item. Install commands also behave differently inside a session than in your terminal, and they change depending on where the plugin comes from.
This guide shows how to find plugins, install them with the right scope, add a custom marketplace, use the --marketplace option, verify the result, manage plugins afterwards, and fix the errors people hit most.
What Is the Claude Code Plugin Marketplace?
A plugin is a package that extends Claude Code. It can contain skills, agents, hooks, and MCP servers. A marketplace is a catalog that lists plugins and tells Claude Code where to fetch them. Claude Code has to know about a marketplace before you can install anything from it.
You will meet three kinds of marketplace:
The official marketplace, named claude-plugins-official. Anthropic maintains it, and Claude Code registers it automatically the first time you start an interactive terminal session.
Anthropic's community marketplace, which you add yourself. Its registered name is claude-community, even though its repository is called claude-plugins-community.
Custom marketplaces, which anyone can publish in a Git repository, at a URL, or in a local folder.
A marketplace name only tells you who publishes the catalog. It does not tell you what each plugin does, so review plugins from every marketplace before installing.
Before You Install a Claude Code Plugin
Claude Code installed and launched. Follow Anthropic's official setup instructions for your platform, then run claude in your project folder.
Your version number. Some flags depend on the version. Check yours from your terminal:
claude --version
Terminal commands versus session commands. This is the most common source of confusion.
/plugin ... is a slash command you type inside a running Claude Code session. Typed at a normal shell prompt, it fails with an error such as zsh: no such file or directory: /plugin.
claude plugin ... is a shell command you run in your terminal, with no session needed. claude plugins works as an alias.
In non-interactive runs such as claude -p, /plugin is not available, so use the claude plugin shell commands there.
A trust check. A plugin you install can execute code on your machine with your user privileges. Read its details before you confirm (more in the security section).
How to Find Plugins in the Official Marketplace
Start Claude Code with Claude.
Type /plugin. The panel opens on the Discover tab, which lists plugins from all your marketplaces.
Type to search, then press Enter on a plugin to open its details.
The details pane is where you decide whether a plugin fits your workflow. It shows the description and can also show:
Will install: the commands, agents, skills, hooks, and MCP and LSP servers the plugin adds.
Last updated: shown for plugins in the official marketplace.
Context cost: for official-marketplace plugins, estimates of the tokens the plugin adds to every turn and when its skills or agents are invoked. This appears when you open the plugin by naming its marketplace or from the Marketplaces tab, but not from the Discover list.
Plugins from custom marketplaces may show "Components will be discovered at installation" instead, so you cannot always preview their contents.
If Discover is empty, or you see "No marketplaces configured," the official marketplace is not registered yet. Add it with:
/plugin marketplace add anthropics/claude-plugins-official
Other places to look: plugins you turn on in your claude.ai account can sync into Claude Code and appear with the @synced suffix.
How to Install a Claude Code Plugin
The command follows one pattern:
/plugin install @
/plugin install is the session command.
is the plugin's name in the catalog.
@ says which catalog it comes from. This is the marketplace's registered name, not its repository or URL.
Here is an example from the official marketplace. It installs commit-commands, which adds commands for committing, pushing, and opening pull requests. Run it inside a Claude Code session:
/plugin install commit-commands@claude-plugins-official
In a session this does not install immediately. It opens the plugin's details so you can review it and choose a scope. After you pick one, Claude Code installs the plugin and any dependencies it declares, then prints a summary.
Choosing an Installation Scope
Scope
Menu option
Who gets it
Recorded in
User
Install for you
You, in every project on this machine
~/.claude/settings.json
Project
Install for all collaborators on this repository
Everyone who works in this repository
.claude/settings.json (you commit it)
Local
Install for you, in this repo only
You, in this repository only
.claude/settings.local.json

If the same plugin is set at several scopes, local overrides project, and project overrides user.
Project scope has a catch. Committing the settings entry enables the plugin for collaborators but does not download it to their machines. Each collaborator runs this once:
claude plugin install @ --scope project
Installing from Your Terminal Instead
claude plugin install commit-commands@claude-plugins-official --scope project
Without --scope, the shell command installs at user scope. Valid values are user, project, and local. On success it prints Successfully installed plugin: commit-commands@claude-plugins-official (scope: project).
One caveat: on a machine where nobody has opened an interactive session yet, the official marketplace is not registered, because shell commands never register it. Run claude plugin marketplace add anthropics/claude-plugins-official first.
How to Install a Plugin from a Custom Marketplace
Many plugins are not in the official marketplace. A coworker's plugin or an open-source project's plugin lives in its own catalog. Claude Code has no global index to look marketplace names up in, so an install line like name@some-marketplace will not work until you have added that marketplace.
The values below are placeholders (your-org/plugins, deploy-helper). They do not refer to a real marketplace or plugin, so replace them with your own.
Add the marketplace (in a session):
/plugin marketplace add your-org/pluginsThe source can be a GitHub owner/repo (add #ref to pin a branch or tag), a full git URL, a local path starting with ./ or ../, or an https:// link to a hosted marketplace.json. Include the https:// prefix on URLs: a bare gitlab.example.com/group/repo is read as GitHub shorthand and fails.
Identify the marketplace name. The success message reads Successfully added marketplace: . That name comes from the marketplace's own manifest and may differ from the repository name. You can also list names:
/plugin marketplace list
Install the plugin using that registered name:
/plugin install deploy-helper@
Confirm the scope in the details pane.
Verify that the plugin is available (see the verification section).
The new marketplace appears on the Discover tab the next time you open /plugin, with no reload needed. Auto-update is off by default for community and third-party marketplaces, so refresh them yourself with /plugin marketplace update .
How to Use the Claude Code --marketplace Option
The --marketplace option combines two steps: it registers a marketplace you have not added yet and starts the plugin install. You pass the marketplace source, and you give the plugin name by itself, with no @marketplace suffix.
In a session (requires Claude Code v2.1.275 or later):
/plugin install deploy-helper --marketplace your-org/plugins
Claude Code shows the source it resolved and asks you to confirm before adding the marketplace. Then the plugin's details open and you choose a scope. If the source matches a marketplace you have already added, it skips the confirmation. In a session, the source cannot contain spaces.
From your shell (requires Claude Code v2.1.292 or later):
claude plugin install deploy-helper --marketplace your-org/plugins
The shell version adds the marketplace without a confirmation step, so be sure of the source before you run it. A new marketplace added this way is declared in your user settings even if you pass --scope project. A marketplace you already added from the same source is reused.
The two forms have different minimum versions, so do not assume one number covers both. Run claude plugin install --help to confirm your build supports the flag.
Source versus name. In --marketplace your-org/plugins, the value is a source: where to fetch the catalog. In deploy-helper@marketplace-name, the part after the @ is the registered name: what the catalog calls itself. They often differ.
Two limitations to know about:
/plugin install your-org/plugins (a source with no plugin name and no --marketplace) installs nothing and reports a "marketplace not found" error.
If the catalog at your source has the same name as a marketplace you already added from a different source, Claude Code keeps the existing one and installs nothing. Remove the old marketplace first if you want the new source.
Claude Code Plugin Installation Examples
Replace the placeholders in angle brackets with your own values.
Goal
Command
Where to run it
Browse plugins
/plugin
Claude Code session
Install from a registered marketplace
/plugin install @
Claude Code session
Install at project scope from the terminal
claude plugin install @ --scope project
System shell
Add a marketplace
/plugin marketplace add
Claude Code session
Add a marketplace from the terminal
claude plugin marketplace add
System shell
Add a marketplace and install in one step
/plugin install --marketplace (v2.1.275+)
Claude Code session
Same, from the terminal
claude plugin install --marketplace (v2.1.292+)
System shell
List registered marketplaces
/plugin marketplace list
Claude Code session
Refresh a marketplace listing
/plugin marketplace update
Claude Code session
List installed plugins
/plugin list (v2.1.163+)
Claude Code session
List installed plugins with status
claude plugin list
System shell
Apply pending plugin changes
/reload-plugins
Claude Code session

How to Verify That a Plugin Is Installed
Start with the install summary. Its last sentence tells you the plugin's state:
"Plugin is now active." No reload is needed.
"Run /reload-plugins to apply." Claude Code runs the reload for you when the panel closes. If the reload would invalidate the prompt cache, it warns and leaves the plugin pending. Run /reload-plugins --force to activate it anyway, which costs one uncached request.
"The plugin couldn't be loaded." Open the Errors tab in /plugin for the reason.
Active, but a bundled MCP server needs configuration. Open the plugin on the Installed tab and choose Configure.
So not every plugin needs a reload. The summary tells you. Plugins installed from your shell load the next time you start Claude Code, or when you run /reload-plugins in an open session.
Then confirm the plugin in any of these ways:
Type / and look for the plugin's skills in the form /:. For commit-commands, that is /commit-commands:commit. The namespace prevents two plugins from colliding on similar command names.
Open the Installed tab in /plugin, which lists each plugin with its scope.
Run claude plugin list in your shell. It prints Version, Scope, and Status for each plugin.
How to Manage Plugins After Installing
Disable or enable: On the Installed tab, press Space on a plugin. From your shell, use claude plugin disable @ or claude plugin enable @.
Uninstall: Use /plugin uninstall in a session, or claude plugin uninstall @ --scope project in your shell. If the project's shared settings enable the plugin, Claude Code asks whether to disable it only for you or uninstall it for everyone.
Update: Run claude plugin update @. No single command updates every plugin. To update everything from one marketplace, open the Marketplaces tab in /plugin, select it, and choose Update marketplace. A running session keeps the versions it already loaded, so run /reload-plugins or start a new session.
Remove a marketplace: This also uninstalls every plugin you installed from it. To refresh a marketplace without losing its plugins, use update instead of remove.
Check the cost: Run claude plugin details in your shell. The Always-on line shows how many tokens the plugin adds to every session.
Common Claude Code Plugin Marketplace Errors and Fixes
These come from Anthropic's troubleshooting guidance. Exact messages vary by version, so treat the fixes as starting points rather than guarantees.
Problem: Marketplace "claude-plugins-official" not found, or the same message for another marketplace name.
Likely cause: The marketplace is not registered on this machine. For the official one, that happens if you have only used the VS Code extension, or if a policy or environment setting blocks auto-registration. For other names, the install line you received does not say where the marketplace is hosted.
Fix: Run /plugin marketplace add anthropics/claude-plugins-official for the official marketplace. For any other, ask whoever sent the line for the marketplace's source, add it with /plugin marketplace add , and rerun the install. If you already added it, compare the spelling against /plugin marketplace list.
Problem: Plugin "" not found in marketplace "".
Likely cause: A misspelled plugin name, or a local copy of the catalog that is out of date.
Fix: Copy the name from the Discover tab. If the message includes a refresh hint, run /plugin marketplace update and install again.
Problem: Invalid marketplace source format.
Likely cause: The source is not in an accepted form. A bare name such as claude-plugins-official or a bare hostname does not qualify.
Fix: Use owner/repo, a full https:// URL, user@host:path, or a path beginning with ./, ../, /, or ~.
Problem: SSH authentication failed or HTTPS authentication failed when adding or updating a marketplace.
Likely cause: Claude Code runs git with interactive prompts disabled, so only credentials that already work non-interactively succeed. A misspelled repository or one you cannot see can produce the same message.
Fix: Run git ls-remote in your terminal to confirm the repository exists and you have access. For SSH, ssh -T git@ must succeed without a passphrase prompt. For GitHub over HTTPS, run gh auth login and gh auth setup-git. Retry once git ls-remote works without prompting.
Problem: The plugin appears installed but does not work.
Likely cause: It may need a reload, may have load errors, may be disabled, or may not contain what you expected.
Fix: Open /plugin, check Installed for enabled status, and read the Errors tab. Run /reload-plugins if you installed during this session. Check the plugin's details pane to see what it actually adds.
Problem: A code intelligence (language server) plugin is installed, but the Errors tab shows Executable not found in $PATH.
Likely cause: These plugins connect to a language server binary that you install separately. The plugin alone is not enough.
Fix: Install the language server binary, confirm it is on the PATH of the terminal you start claude from (for example with which typescript-language-server), then start a new session.
Problem: error: unknown command 'add', unknown option '--project', or Unknown command: /install.
Likely cause: Those spellings do not exist. Some older tutorials still use them.
Fix: Use claude plugin marketplace add to add a marketplace, claude plugin install @ to install, --scope project instead of --project, and /plugin install ... instead of /install. A rejected --marketplace flag usually means your Claude Code version is older than the minimum above, so update Claude Code.
Problem: A plugin is "enabled in project settings but isn't installed here," or you are unsure which scope applies.
Likely cause: A repository's settings can enable a plugin for everyone, but they do not download it. Separately, when a plugin is set at several scopes, the most specific one wins.
Fix: Run claude plugin install @ --scope project, then /reload-plugins. Run claude plugin list to see each plugin's scope.
Plugin Security and Best Practices
Anthropic's documentation states that an installed plugin can execute arbitrary code on your machine with your user privileges. That is a reason for a quick review habit, not for alarm.
Check source and maintainer. A marketplace name tells you who publishes the catalog, not what every plugin in it does. Prefer plugins from maintainers you recognize.
Read "Will install" before you confirm. Hooks and MCP servers deserve the closest look. Hooks run commands in response to events, and MCP servers give Claude access to external tools and data. Their processes are separate from Claude's own tool calls, so a plugin's description is not a substitute for reading its hook and MCP configuration.
Be careful with unfamiliar repositories. This applies to --marketplace especially, because the shell form adds the marketplace without asking.
Remember that updates can change what you reviewed. When auto-update is on for a marketplace, Claude Code updates its plugins in the background. It is on by default for the official marketplace and off by default for third-party ones. For a third-party plugin you audited carefully, leave auto-update off and update by hand.
Agree on project-level plugins as a team. Project scope puts the plugin in a committed settings file, so everyone gets the same setup. Decide together what goes there, and keep personal experiments at user or local scope.
To remove a plugin you no longer trust, uninstall it. If you do not trust the marketplace either, remove the marketplace too.
Frequently Asked Questions
What is the Claude Code plugin marketplace?
A catalog of plugins that Claude Code can install from. The official one is claude-plugins-official, and you can add others from Git repositories, URLs, or local paths.
How do I install a Claude Code plugin?
Run /plugin install @ in a session, choose a scope, and read the install summary. From your shell, use claude plugin install @.
How do I install a plugin from a custom marketplace?
Add the marketplace with /plugin marketplace add , then install with the registered marketplace name. Or use --marketplace to do both at once.
What does the Claude Code --marketplace option do?
It registers a marketplace you have not added and starts the plugin install in one command. It requires v2.1.275 or later in a session and v2.1.292 or later from the shell.
Do I need to add the official marketplace manually?
Usually not. Claude Code registers it on your first interactive terminal session. You may need to add it yourself if you have only used the VS Code extension, if a policy blocks auto-registration, or on a fresh machine where you install from the shell.
How do I list installed Claude Code plugins?
Use /plugin list in a session (v2.1.163 or later), open the Installed tab in /plugin, or run claude plugin list in your shell.
Why is my plugin not appearing after installation?
Check the Installed and Errors tabs in /plugin, and run /reload-plugins if you installed during this session. Open the plugin's details to confirm what it provides.
Can I share a plugin installation with my team?
Yes, with project scope. It records the plugin in .claude/settings.json, which you commit. Collaborators still run claude plugin install @ --scope project once to download it.
How do I update Claude Code plugins?
Run claude plugin update @, or use Update marketplace on the Marketplaces tab. No single command updates every plugin.
How do I uninstall a plugin?
Use /plugin uninstall in a session, or claude plugin uninstall @ in your shell. Add --scope to target one scope.
Conclusion
The simplest workflow is short. Open Claude Code, run /plugin to browse the Claude Code plugin marketplace, review the plugin's details, and install it with /plugin install @. If the plugin lives in another marketplace, add that marketplace first, or use --marketplace to combine both steps. Before you confirm any install, check who published the plugin and choose the scope that matches who should have it.
Want more practical Claude Code walkthroughs? Keep exploring the guides on HustleToAI.

Claude Code Read Large Files: Limits & allow_large

ail akram — Wed, 14 Oct 2026 09:40:03 +0000

Claude Code Dynamic Workflows: Practical Guide

Most AI coding sessions follow one pattern: you ask, the assistant works, you review, you ask again. That pattern is fine for a bug fix. It breaks down on a migration that touches hundreds of files or an audit of an entire service. The context window fills up, the original instructions get compressed away, and you end up acting as the project manager.

Claude Code dynamic workflows are Anthropic's answer to that problem. This guide explains what they are, how they work, how they differ from subagents, skills, hooks and agent teams, and how to use them on large coding tasks without wasting usage. Every feature, command and limit below was checked against Anthropic's official documentation and announcement. Claims from community articles are labeled as community sources.

Dune: Part Three: Full HD
We have 117 new singles for you
Hey Honey! Wanna Date?
Find a girl! 100% Free website!
Why static coding workflows struggle with complex tasks
A single chat session is one fixed loop: Claude reads, decides, acts, and keeps every intermediate result in one context window. Community analyses of Claude Code workflows describe three recurring failure modes when that single window carries a big job:

Agentic laziness. On a long, multi-part task, Claude reviews part of the list and then reports that the job is done. A security review that covers 35 of 50 files is the usual example.

Self-preferential bias. When Claude grades its own output inside the same conversation, it tends to rate it generously.

Goal drift. Over many turns, and especially after context compaction, details such as "do not touch the auth module" can fade.

Anthropic's own best-practices guide points at the same root cause: the context window fills quickly, and performance degrades as it fills. Dynamic workflows attack the problem structurally, by moving the plan out of the conversation and into a script.

What are Claude Code dynamic workflows?
Dynamic workflows are an official, named Claude Code feature, not just a design idea. According to the official documentation, a dynamic workflow is a JavaScript script that orchestrates many subagents at once. Claude writes the script for the task you describe, and a runtime executes it in the background while your session stays responsive.

Key facts, all from Anthropic's announcement and docs:

Announced May 28, 2026. The announcement now carries an update saying dynamic workflows are generally available, so older articles that call them a research preview are out of date.

Available in the Claude Code CLI, Desktop app and VS Code extension, and on the Claude API, Amazon Bedrock, Vertex AI and Microsoft Foundry. The docs say they are available on all paid plans. They are on by default for Max, Team and Enterprise, and Pro users turn them on from the Dynamic workflows row in /config.

Anthropic says they consume meaningfully more usage than a typical session, so it recommends starting with a scoped task. The first time a workflow triggers, Claude Code shows what is about to run and asks you to confirm. Organization admins can disable workflows through managed settings.

Community sources report that the feature arrived in v2.1.154 and that the original trigger keyword workflow was renamed ultracode in v2.1.160. Check claude --version and the changelog if you are on an older build.

The word "dynamic" has two meanings here. Claude writes the orchestration fresh for each task, instead of you wiring a fixed pipeline. And the script itself can adapt at runtime: it can branch on results, retry, or loop until a condition is met.

How Claude Code dynamic workflows work
The central idea is who holds the plan. In a normal session, Claude is the orchestrator and decides turn by turn what to do next, and every result lands in its context window. In a workflow, the script holds the loop, the branching and the intermediate results in variables, so Claude's context holds only the final answer.

The lifecycle of a run:

Trigger. You ask for a workflow in plain words, include the keyword ultracode in your prompt, or turn on ultracode for the session.

Script generation. Claude writes a JavaScript orchestration script for the task.

Approval. Claude Code shows the planned phases. You can read the raw script before approving.

Background execution. Agents run while you keep working. Run /workflows to watch progress.

Verification and iteration. Depending on how the script is written, agents cross-check each other, retry, or loop.

Report. You receive one consolidated result.

Three practical consequences follow. First, every run writes its script to a file under ~/.claude/projects/, so you can read, diff or edit the orchestration. Second, progress is saved as the run goes, so an interrupted run can pick up where it stopped. Third, community sources point out that the script itself costs no model tokens, since it is ordinary code; all token cost comes from the agents it spawns. A product manager who measured a run on 100 synthetic interview transcripts reported 113 agents, about 1.95 million tokens and 12.5 minutes. Treat that as one data point from a non-coding task, not a benchmark.

Core Claude Code features that enable adaptive workflows
Dynamic workflows sit alongside several other features. They are not interchangeable. The official documentation compares subagents, skills, agent teams and workflows by who decides what runs next:

Feature

What it is

Who decides what runs next

Scale

CLAUDE.md

Persistent project instructions read every session

Not applicable (context, not control flow)

Not applicable

Skills

Instructions Claude follows, loaded when relevant

Claude, following the prompt

Same as subagents

Hooks

Shell commands that fire at lifecycle events

The event, deterministically

Per tool call

Subagents

A worker Claude spawns

Claude, turn by turn

A few delegated tasks per turn

Agent teams (experimental)

A lead agent supervising peer sessions

The lead agent, turn by turn

A handful of long-running peers

Dynamic workflows

A script the runtime executes

The script

Dozens to hundreds of agents per run

The CLAUDE.md and hooks rows are my summary; the other rows follow the official comparison table.

CLAUDE.md and project instructions
CLAUDE.md is read at the start of every conversation and holds build commands, code style and workflow rules. Anthropic advises keeping it short: for each line, ask whether removing it would cause mistakes, and cut it if not. A bloated file makes Claude ignore half of it. Knowledge that only matters sometimes belongs in a skill, which loads on demand. Run /init to generate a starter file.

Skills and reusable workflows
A skill is a folder with a SKILL.md file. The frontmatter tells Claude when to use it, and the body holds the instructions. Skills live in .claude/skills//SKILL.md for a project or ~/.claude/skills/ for personal use. Setting disable-model-invocation: true keeps Claude from triggering a skill on its own, which suits anything with side effects. A skill is prompt-driven, so it does not guarantee ordering, retries or resume. A community guide suggests a simple boundary: keep interpretation and trade-off judgment in prompts and skills, and put required ordering, retries and stop rules in code.

Hooks and automated actions
Hooks are deterministic. A CLAUDE.md rule is advice, while a hook makes an action happen every time. They are configured in settings.json files at user, project or local level. Exit code 2 from a hook signals a blocking error. A PreToolUse hook can actually stop an action. A PostToolUse hook runs after the action, so it can only report back to Claude. A Stop hook can run your check script and keep the turn from ending until it passes.

Subagents and specialized tasks
Subagents are Markdown files with YAML frontmatter in .claude/agents/ or ~/.claude/agents/. Each runs in its own context with its own tool allowlist. They are the workers that a dynamic workflow orchestrates. Claude Code also ships built-in ones such as Explore, Plan and general-purpose.

Agent teams and parallel sessions
Agent teams are a separate mechanism and are still experimental. They are disabled by default, are enabled with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS setting, and have known limitations around session resumption, task coordination and shutdown. Each teammate is a full Claude Code session, and teammates coordinate through a shared task list. Use them when peers need to share findings and challenge each other. A workflow agent, by contrast, only executes the step the script hands it. One customer quote in Anthropic's announcement describes workflows as filling the gap between firing off one subagent and building a full agent team.

Plan mode, /goal and task decomposition
Anthropic recommends exploring, then planning, then coding. Press Shift+Tab until plan mode is on, or start with claude --permission-mode plan. Claude reads and answers without changing files, and you can edit the plan with Ctrl+G. Anthropic's rule of thumb: if you could describe the diff in one sentence, skip the plan. Plan mode is not the same as a workflow's planning stage, which is Claude writing a script. For unattended work, /goal sets a completion condition that a separate evaluator re-checks after every turn.

Claude Code dynamic workflow architecture, step by step

Think of three layers:

Instruction layer: CLAUDE.md and skills describe how your project works.

Guardrail layer: hooks, permission rules and sandboxing enforce what must always or never happen.

Orchestration layer: subagents, a workflow script or an agent team decide who does what.

A typical adaptive run follows Understand, Plan, Implement, Test, Review, Fix, Verify. The path is not fixed. A failing test sends the run back to Fix. A missing dependency sends it back to Plan. In a workflow script, that branching is real code, such as a loop with an exit condition, instead of a hope that Claude remembers to retry.

Inside the script, the documented building blocks are small:

agent() spawns one subagent. With a schema option it returns validated JSON, and Claude Code retries until the output matches (up to five attempts by default).

pipeline() runs one agent per item in a list, streaming items through stages.

parallel() runs a set of tasks at once and waits for all of them.

phase() groups agents under a title in the progress view, log() prints a message, and args carries input to a saved workflow.

A failed or stopped agent() returns null inside pipeline() or parallel(), so scripts filter those out.

Six patterns worth knowing
Community guides name six recurring shapes. Learning the names helps you ask for the right structure in a prompt:

Classify-and-act: one agent decides what kind of task it is, and the script routes accordingly. Good for triage.

Fan-out-and-synthesize: one agent per piece, then one agent merges the results. Good for codebase audits.

Adversarial verification: a separate agent tries to refute each finding, so the producer never grades its own work.

Generate-and-filter: produce many candidates, then filter and deduplicate to the survivors.

Tournament: several agents attempt the same task differently, and a judge compares them pairwise. Pairwise comparison is more reliable than asking an agent to score its own result.

Loop-until-done: keep going until a stop condition is met, such as two rounds with no new findings.

Anthropic's announcement describes the same ideas: agents attack the problem from independent angles, other agents try to refute what they found, and the run iterates until answers converge.

Practical example 1: debugging an unknown error
Problem. A production stack trace points somewhere that makes no sense.

Honest note. Most debugging does not need a workflow. Start in a normal session and escalate only when the search space is wide.

Initial prompt. "Here is the stack trace. Do not change code yet. Find the root cause and list your evidence."

Breakdown. A subagent searches the codebase in its own context so your main window stays clean. Claude forms hypotheses, reproduces the failure with a narrow test, and edits only after the cause is confirmed. This run is sequential and adaptive.

Features used. Plan mode or an Explore-style subagent, and a failing test written before the fix, as Anthropic's best-practices guide recommends.

Verify. The reproduction fails before the fix and passes after, and the wider suite stays green.

If it fails. Discard the hypothesis, tell Claude it was wrong, and ask for the next one. If you have corrected Claude twice on the same issue, Anthropic suggests running /clear and starting over with a better prompt. If the cause could be anywhere in a service, escalate:

use a workflow to hunt for the cause of this error across src/services/,
one agent per module, with hypotheses from different evidence (logs, source,
data), and adversarially verify each suspected cause before reporting it
Practical example 2: implementing a feature across multiple files
Problem. Add per-user rate limiting touching middleware, config, tests and docs.

Initial prompt. "Plan first. List the files you will touch and the order. Wait for my approval."

Features used. Plan mode for the proposal, CLAUDE.md for conventions, and a formatting hook so style never costs a review round. For a larger feature, Anthropic suggests letting Claude interview you with the AskUserQuestion tool and write a spec file, then executing the spec in a fresh session.

Sequence. Plan, your approval, middleware, config, tests, docs, then the full test run. This is sequential with one human checkpoint.

Verify. Run the new tests and the existing suite, then read the diff yourself.

If it fails. Reject the plan before any code is written, which is cheap. A workflow is the wrong tool here because each step depends on the last.

Practical example 3: running tests and reviewing changes

Problem. The type check fails with dozens of errors after a dependency upgrade.

This is a natural workflow case because it is a loop. The official docs give this prompt shape:

use a workflow to run npx tsc --noEmit and keep fixing the reported errors

until the type check passes or two rounds in a row make no progress

The "two rounds with no progress" clause is a stop condition that prevents an endless fix loop. For review, a second workflow can run a reviewer per file and pass all findings to one agent that ranks and deduplicates them.

Verify. Run the type check and the test suite yourself afterwards. Anthropic stresses give Claude a check it can run, such as tests, a build exit code or a linter, because without one "looks done" is the only signal.

Review caveat. A reviewer told to find gaps will usually report some, even on sound work. Anthropic advises telling the reviewer to flag only gaps that affect correctness or stated requirements, otherwise you invite over-engineering. The bundled /code-review skill reviews the current diff in a fresh subagent.

If it fails. Open /workflows to see which agents stalled or failed, then ask Claude to relaunch. Completed agents return their saved results.

Practical example 4: a large task with multiple agents
Problem. Convert 300 JavaScript components to TypeScript.

use a workflow to migrate every component under src/components/ from

JavaScript to TypeScript, working on each file in its own isolated copy,
then review each result and run the type check
Breakdown. Discover the files, migrate each in parallel, run an independent review of each, then run a fix loop against the build and tests.

This mirrors a large real use. Anthropic reports that Jarred Sumner used workflows to port Bun from Zig to Rust, reaching 99.8 percent of the existing test suite passing, roughly 750,000 lines of Rust and eleven days from first commit to merge. One workflow mapped lifetimes, another ported each file with two reviewers per file, and a fix loop drove the build and tests until they ran clean. Anthropic notes that the result was not yet in production. Treat it as an upper bound, not a typical outcome.

If it fails. Shrink the scope. The docs recommend running a workflow on a small slice first, such as one directory, to gauge cost. Anthropic's announcement also suggests turning on auto mode for workflows so a long run does not stop on every permission prompt.

How to build your first dynamic workflow
Update Claude Code and confirm workflows are on (Pro users enable them in /config).

Try the built-in workflow. Run /deep-research with a question. It fans out searches, cross-checks sources, votes on claims and returns a cited report. It needs the WebSearch tool.

Watch it. Run /workflows. Press Enter to drill into phases and agents, p to pause or resume, x to stop, r to restart an agent and s to save the script.

Ask for your own. Say "use a workflow to..." or include ultracode in the prompt.

Read the script before approving, using "View raw script" or Ctrl+G.

Save what worked. Saved workflows become slash commands. Project workflows live in .claude/workflows/ (shared with the repo) and personal ones in ~/.claude/workflows/. A project workflow wins a name clash. Plugins can ship workflows too, namespaced by plugin name.

Ultracode, explained
The keyword and the session setting differ. The keyword ultracode in a prompt opts in a single task. The setting /effort ultracode makes Claude plan a workflow for every substantive task in the session, so each request costs more tokens and takes longer. Launching with claude --effort ultracode also sets effort to xhigh and needs v2.1.203 or later. Turn it off with /effort ultracode off for routine work. While ultracode is on, the Large workflow warning and the first-launch approval in auto mode are skipped.

Approval prompts by permission mode
Mode

When you are prompted

Auto

First launch only; consent is recorded. Skipped when ultracode is on

Manual, accept edits

Every run, unless you choose "don't ask again" for that workflow in that project

Bypass permissions

No prompt; the run starts immediately

claude -p, Agent SDK

No prompt; permission rules decide, for example a Workflow allow rule

Example commands, configuration and code
Verified configuration comes first, followed by a script sketch that I have not executed.

Hook: format every edited file
Add to .claude/settings.json. It needs jq and Prettier installed. The trailing ; true stops a formatter error from being reported as a blocking error.

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$(jq -r '.tool_input.file_path')\" ; true"
}
]
}
]
}
}
Hook: block edits to protected paths
A PreToolUse hook can stop the action. Exit code 2 blocks it and returns the message to Claude.

{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in .env|/migrations/*) echo 'Protected path' >&2; exit 2;; esac"
}
]
}
]
}
}
Subagent: read-only reviewer
Save as .claude/agents/code-reviewer.md.

name: code-reviewer
description: "Reviews code for correctness and security. Use proactively after code changes."
tools: Read, Grep, Glob, Bash

model: inherit

You are a senior code reviewer. Report concrete defects with file and line.

Flag only gaps that affect correctness or the stated requirements.

Do not edit files.

Skill: manual-only task
Save as .claude/skills/fix-issue/SKILL.md and run it with /fix-issue 1234. The $ARGUMENTS placeholder takes the number.

name: fix-issue
description: Fix a GitHub issue

disable-model-invocation: true

Analyze and fix the GitHub issue: $ARGUMENTS.

Use gh issue view to read the issue.
Find the relevant files and implement the fix.
Write and run tests, then run the linter and type check.
Commit with a descriptive message and open a PR.

Settings and commands that control workflows

Start a session with ultracode on (v2.1.203 or later)

claude --effort ultracode

Limit how many agents Claude aims for: small, medium, large or unrestricted

/config workflowSizeGuideline=small

Allow every workflow, or one saved workflow, in permission rules

Workflow
Workflow(audit-routes)

Turn workflows off

"disableWorkflows": true (in ~/.claude/settings.json)
CLAUDE_CODE_DISABLE_WORKFLOWS=1 (environment variable)

Raise the concurrent agent cap, 1 to 256 (v2.1.269 or later)

CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=32
The size guideline is advice to Claude, not a hard cap. The default is medium, or small on a Pro plan with v2.1.271 or later.

Script sketch: loop until a round finds nothing new
You normally do not write scripts by hand, because Claude generates them. Recognizing the shape helps you review one. This sketch uses only constructs the official docs describe (meta, agent() with a schema, phase(), log(), top-level await and return). I have not run it, so treat it as a teaching example.

export const meta = {
name: 'find-untested-files',
description: 'Find source files without tests, in rounds, until two rounds add nothing',
}
const seen = new Set()
let dry = 0
let round = 0
phase('Discover')
while (dry < 2 && round < 6) {
round += 1
const batch = await agent(
List up to 10 files under src/ that have no test file. Already reported: ${JSON.stringify([...seen])}. Return an empty list if none remain.,
{
label: round ${round},
schema: {
type: 'object',
required: ['files'],
properties: { files: { type: 'array', items: { type: 'string' } } },
},
},
)
const fresh = batch.files.filter(f => !seen.has(f))
if (fresh.length === 0) { dry += 1; continue }
dry = 0
fresh.forEach(f => seen.add(f))
log(Round ${round}: ${fresh.length} new files)
}

return [...seen]
Rules to remember when editing a script: keep export const meta as the first statement with literal values only, do not use import(), and do not call Date.now(), Math.random() or a no-argument new Date(), because they throw so that relaunched runs repeat the same agent calls. Pass timestamps through args. To load the script-writing reference before editing, run the bundled /workflow-authoring skill (v2.1.248 or later). Community guides show extra features such as an isolation: 'worktree' option, a budget global and nested workflow() calls. I could not confirm those on the official workflows page, so check the /workflow-authoring reference before relying on them.

Related automation outside workflows
Anthropic's best-practices guide documents two other fan-out routes. The /batch command splits a change across 5 to 30 subagents, each in its own worktree. You can also loop over non-interactive runs yourself:

for file in $(cat files.txt); do
claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)" \
--permission-mode dontAsk
done
Test on two or three files first, then run the full set. The dontAsk mode denies anything not pre-approved, which matters for unattended runs. Note that the ultracode keyword does not start a workflow from a -p prompt, so use permission rules if you need a workflow in that setting.

Sequential vs parallel vs adaptive workflows
Pattern

Use when

Example

Sequential

Each step depends on the last

Feature implementation (example 2)

Parallel

The same operation runs across many independent items

Per-file audit or migration

Conditional or adaptive

The next step depends on results

Fix until the type check passes (example 3)

Peer multi-agent

Agents must share findings and debate

Agent teams (experimental)

Inside a script, parallel() is a barrier that waits for every agent, while pipeline() streams each item through its stages without waiting for the others. Community guidance is to default to pipeline() for multi-stage per-item work and add a barrier only when a stage truly needs all earlier results, such as deduplicating across all findings or deciding to exit early. One community writeup shows a mis-designed pipeline costing roughly twice the tokens of an equivalent barrier design, so the choice affects cost as well as speed. A useful test from the same sources: if you cannot sketch a non-trivial flowchart with parallel branches, loops and data handoffs, you probably do not need a workflow.

Common mistakes and troubleshooting
Using a workflow for a small task. One agent in a normal session is cheaper and often better.

Confusing the primitives. A hook cannot make decisions, a skill cannot enforce ordering, and a subagent is not a workflow.

No stop condition. Always say when to stop, for example "two rounds in a row with no progress".

Trusting the final report. Re-run the tests and read the diff. Ask Claude to show evidence, such as test output, instead of asserting success.

Permission prompts stalling a long run. Add the tools the agents need to your allow rules before starting.

An agent that stalls. The runtime restarts it automatically, up to five times, and the progress view shows a retry label. For genuinely slow work, pass stallMs on that agent() call.

A run that hits your usage limit. In interactive sessions signed in with a subscription, the run pauses and resumes after the reset (v2.1.271 or later), with conditions listed in the docs. Other modes fail the affected agent instead.

Workflow commands missing. Check for disableWorkflows, the CLAUDE_CODE_DISABLE_WORKFLOWS variable, or an organization policy. On Pro, check the /config toggle.

Resume surprises. If you edit a script, the first agent whose prompt changed and every agent after it run again. A failure mid-fan-out reruns agents that started after it, even finished ones.

Limitations, security considerations and best practices
Documented limits
Constraint

Value

Concurrent agents

16 by default, fewer when Claude Code has fewer CPUs; adjustable from 1 to 256

Items in one parallel() or pipeline() call

4,096

Agents per run

1,000

Mid-run user input

None. For sign-off between stages, run each stage as its own workflow

Script access

No direct filesystem or shell access; agents do the reading, writing and commands

Modules

A script containing import() fails before the run starts

Cost
This is the biggest practical risk. A run can use far more tokens than the same task in conversation, and runs count toward your plan's limits. Claude Code shows a Large workflow warning when a run schedules more than 25 agents or its projected total passes 1.5 million tokens, but the warning is advisory and does not pause anything. To control spend:

Pilot on a small slice, such as one directory.

Watch per-agent token usage in /workflows and stop the run if it grows.

Check /model before a large run, and ask for a smaller model on stages that do not need the strongest one.

Choose a smaller size guideline if you want fewer agents.

Remember that the 5 minute prompt cache for workflow agents can be extended to one hour with subagentPromptCacheTtl, at a higher cache-write rate.

Security
The ultracode keyword only starts a workflow from a prompt a human types. Since v2.1.210 it does not fire from webhook payloads or relayed pull request comments, which closes a route for untrusted text to launch large runs.

Workflow agents get the same permission checks and sandboxing as other tool calls. A broad allow list of a hundred agents is a large blast radius, so scope your rules and prefer auto mode over bypass.

Community guidance for triage workflows is to quarantine agents that read untrusted content (issues, emails, scraped pages) so they cannot take high-privilege actions; separate acting agents do that.

Run migrations on a branch and review pull requests before merging.

Best practices
Start in one directory, then scale.

Put verification in the prompt: a type check, tests, or an adversarial review step.

Keep durable rules in CLAUDE.md, enforce must-happen actions with hooks, and keep prompts specific about files, constraints and what "done" means.

Save workflows that worked and commit them under .claude/workflows/.

Use /clear between unrelated tasks, and rewind with checkpoints (Esc twice or /rewind) instead of piling corrections into one session. Checkpoints do not track changes made through Bash, so they do not replace git.

Workflows compared with the Agent SDK
You could already script multi-agent flows with the Agent SDK or claude -p. A community comparison draws this line: the SDK is for agents you ship inside your own product, while dynamic workflows coordinate the agents doing your own work inside Claude Code. A hand-built harness has to cover every edge case in advance, while a workflow is written for the single task in front of it. Open-source projects that make workflow scripts portable to other agents exist, but they are unofficial, so verify them before use.

Frequently asked questions
Are Claude Code dynamic workflows the same as subagents?

No. Subagents are workers. A workflow is a script that orchestrates many of them, and the script, not Claude, decides what runs next.

Do I need agent teams enabled?

No. Workflows are independent of the experimental agent teams setting.

Which plans include dynamic workflows?

The official docs say all paid plans, plus API access and the major cloud platforms. They are on by default for Max, Team and Enterprise, and Pro users enable them in /config. Plan details change, so confirm in the docs.

Can I reuse a workflow?

Yes. Save it from /workflows and it becomes a slash command. Saved workflows take structured input through the args global.

Can I resume a run after closing Claude Code?

Within the same session, yes. If you exit and later resume the session with Claude --resume, you can ask Claude to relaunch the workflow and complete agents' replay from saved results. A fresh session starts the workflow over.

Can I turn workflows off?

Yes, through /config, "disableWorkflows": true or the environment variable. Admins can disable them organization-wide.

Will workflows make my coding faster?

For wide, parallelizable work, often yes. For narrow, sequential work, usually not, and they will cost more.

**Conclusion
**Claude Code dynamic workflows give you orchestration that lives in a script you can read, rerun, save and share, instead of in a chat transcript. They suit codebase-wide audits, large migrations and any work that needs independent verification. They are the wrong tool for ordinary feature work, where plan mode, a lean CLAUDE.md, a few hooks and one focused subagent cost far less.

Start small. Run /deep-research once to see the shape, try a workflow on a single directory, read the script before approving, and verify the result yourself. This area changes quickly, so confirm version requirements against the official Claude Code documentation before you build on them.

Claude Code Dynamic Workflows: Practical Guide

ail akram — Wed, 14 Oct 2026 09:36:29 +0000

*Claude Code Dynamic Workflows: Practical Guide
*

I am AdZilla. Buy my meme coin now!
One roulette spin. $4k. Try luck
Thunder vs Spurs — HD stream now!
Beverly Hills Cop: Axel Foley
Why static coding workflows struggle with complex tasks
A single chat session is one fixed loop: Claude reads, decides, acts, and keeps every intermediate result in one context window. Community analyses of Claude Code workflows describe three recurring failure modes when that single window carries a big job: