Code Mode is an experimental Claude Code switch, off by default, where Claude writes JavaScript that fires several tool calls in one step and returns only the output it needs. Turn it on with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 in a terminal session on v2.1.323 or later, then confirm "Yes, turn on Code Mode". The 37% token figure attached to it is from Anthropic's API Programmatic Tool Calling post, not a Code Mode benchmark.
Sources I used: Code Mode docs (checked 16 Nov 2026), Claude Code changelog (v2.1.323 on 12 Nov 2026, fixes in v2.1.325 on 13 Nov 2026), Anthropic, advanced tool use (24 Nov 2025). I have not measured Code Mode on my own work.
What is Code Mode in Claude Code?
Without it, Claude asks for Bash, Read, or Edit one at a time and reads each result before the next call. With it, Claude writes JavaScript and Claude Code runs that script, which calls the tools: in parallel, chained, returning only the part Claude needs. It is experimental and may be removed. v2.1.323 (12 November 2026) added it as "an experimental opt-in in which Claude writes JavaScript to call its tools."
The docs' example finds a file, edits a retry limit, starts the tests, and returns the path plus the test output:
const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });
In the chat you see the tool calls, such as the diff, not the script. Ctrl+O opens the transcript viewer, where each script is a collapsed Code row. Press Ctrl+O again to return.
It does not change how you package tools for an agent you ship. That split is MCP vs function calling. Code Mode only changes orchestration inside one terminal session.
v2.1.325 (13 November 2026) fixed first-day bugs: scripts that ignored a worktree entered with EnterWorktree, scripts that wrote ~ paths into the project, words typed with Yes at a permission dialog or plan approval that never reached Claude, and Claude starting work by itself when you resumed a session that ended mid-script. If you are still on 2.1.323, update before you judge it.
How do I enable Code Mode?
Run claude --version. Older than v2.1.323, run claude update. Either release channel works. stable can lag; if the update stops short, wait or switch to latest.
Try it once from the shell.
macOS, Linux, or WSL:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
Windows PowerShell:
$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude
For every new session, set it in user settings at ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
Claude Code ignores this variable in a project's settings files. A cloned repo cannot turn Code Mode on for you.
The first time, confirm Yes, turn on Code Mode. Claude Code restarts and shows:
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
A different line, or no line, means it did not start. /status shows the reason.
Resume only with the variable still set to 1, via claude --continue or claude --resume. Off, and Claude Code refuses that session. Sessions started without Code Mode resume without it, even if you export 1 later.
To turn it off, delete the variable from the shell and from ~/.claude/settings.json, or set it to 0, then start a new session. A 0 in either place beats a 1 in the other.
To block it for an organization, put 0 in managed settings. Anyone already in a Code Mode session stays until they exit or restart, then they cannot resume those sessions while the 0 remains. Managed settings cannot force it on.
What are the requirements and limits?
From the docs, checked 16 November 2026:
| Requirement | What you need |
|---|---|
| Version | Claude Code v2.1.323 or later. stable may lag latest. |
| Account | Claude subscription or Console account. Not a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry. |
| Organization | Not HIPAA configuration, and not zero data retention. |
| Model | Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.2. |
| Surface | Interactive claude in a terminal. Not -p, the Agent SDK, the VS Code panel, the Desktop app, or cloud sessions. |
| Install | Native build. Windows needs Git for Windows. |
| Blocks startup | API key helper, agent teams, OpenTelemetry export, or DISABLE_TELEMETRY. |
Limits, once it is on:
| Limit | What it means |
|---|---|
| Resume | Terminal only, with Code Mode on. Desktop and cloud cannot pick the thread up. |
| Auto mode | The classifier reviews the code, not each tool call, and it does not see runtime values. |
| Waiting code | Stops after 10 minutes, including time spent at permission prompts. |
| Background code | Up to 2 hours, if the session started in auto mode or bypassPermissions. |
| Unavailable | No Remote Control, Claude in Chrome, or computer use. |
| Moving the session | Cannot move to Desktop or a background session. /fork cannot start a background copy. |
Does Code Mode really cut tokens 37%?
The Code Mode docs do not say 37%. That number is from a different surface.
On 24 November 2025 Anthropic published Introducing advanced tool use. Programmatic Tool Calling is Claude writing code that calls tools and chooses what enters context, instead of one request per turn with every intermediate result kept. Their line: "Average usage dropped from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks."
Code Mode is that idea inside Claude Code: the script orchestrates, Claude reads the return value, intermediate output stays out of context. The mechanism matches. The benchmark does not. The Code Mode docs do not cite those figures, Anthropic has not published a Code Mode token study, and I have not measured one.
For your own number, run the same task twice: same prompt, same model, same starting tree, Code Mode off, then on. Compare /cost or /status. Plan price and caps are in Claude Code cost per month and keeping Claude's token bill from ruining your month.
When does Code Mode help and when not?
The docs point at work that already takes many related tool calls:
- A change that repeats across many files.
- A search whose results need filtering before Claude reads them.
- Several independent commands that can run at the same time.
The retry-policy example is that shape. Leave it off when the shape is wrong:
- A small single edit. One read and one patch does not need a script around it.
- A build or test longer than 10 minutes, unless it can run in the background (auto or
bypassPermissionsfrom the start, 2 hour cap). Waiting code stops at 10 minutes, prompts included. - Anyone outside an interactive terminal
claude:-p, the Agent SDK, the VS Code panel, the Desktop app, cloud sessions. For a team that lives in an IDE, this switch is not part of a Claude Code vs Codex call yet.
Try one noisy multi-file edit and read the Code row. Mostly diffs means it earned the session. Mostly permission prompts means you kept the noise. Recommendation, not a measurement.
Running Claude Code against a real codebase and want the tool boundaries, review rules and token caps settled before an experimental mode changes how calls get checked?
What changes for permissions and security?
You still see the diffs, so review them as any other agent edit. A script is not an exemption. See how to review AI-generated code.
Each tool call still passes deny and ask rules and PreToolUse hooks. In auto mode the classifier reviews each piece of code before it runs, not each call inside it, and it does not see runtime values (a path taken from search output, for example). Keep rules or hooks for calls you must gate. Other permission modes skip that review and prompt per call, as usual.
To read the JavaScript, match a PreToolUse hook on REPL, the tool that runs Claude's code, and read tool_input.code.
Bash rules match command text, so a denied command can slip through in another spelling, with or without Code Mode. For a limit that does not depend on spelling, use sandboxing.
Background code runs up to 2 hours if the session started in auto or bypassPermissions. If Claude still waits, Shift+Tab back to the starting mode, or exit and run claude --continue --permission-mode auto with Code Mode on. Drop --tools if you passed tool names. A pick from claude --resume needs that continue path.
Why does Claude Code say Code Mode isn't available?
Code Mode (experimental) isn't available means it did not start. The reason is on that line and in /status. Fix it and start a new session. Common cases:
| Reason includes | What to do |
|---|---|
it isn't open to your account yet |
Below v2.1.323, update. Otherwise check the network and retry. If it stays, try another day. |
it only works with the Anthropic API |
Remove a gateway, cloud provider, or custom ANTHROPIC_BASE_URL. |
it only works with Opus 5.5, Sonnet 5.5 and later models |
Start on a supported model, for example --model opus. Haiku 5.5 and Fable 5.2 also work. |
it doesn't work with an API key helper |
Remove apiKeyHelper, ANTHROPIC_AUTH_TOKEN, and Authorization or X-Api-Key headers in ANTHROPIC_CUSTOM_HEADERS. Then sign in. |
OpenTelemetry is on |
Unset CLAUDE_CODE_ENABLE_TELEMETRY and ENABLE_BETA_TRACING_DETAILED if you can work without that export. |
it needs settings that Claude Code downloads from Anthropic |
Unset the flag that stops feature-flag fetching, such as DISABLE_TELEMETRY. |
it can't be used together with agent teams yet |
Unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. |
it doesn't work in background jobs |
Start in the foreground, without --remote-control. |
your organization's settings don't allow it |
Managed settings has 0. You cannot override that locally. |
No line at all: check claude --version (update below v2.1.323), set the variable to 1, and clear any 0, including one passed with --settings.
About the author
I'm Joan Comadran, an industrial engineer turned AI engineer and full stack developer in Barcelona. I build with Claude Code daily. I have not measured Code Mode on a project; the steps above are the docs (16 November 2026), and the 37% figure is Anthropic's API result from November 2025. Tool boundaries and token caps on a real product are the work I take on.
FAQ
What is Code Mode in Claude Code?
As of the Claude Code docs checked on 16 November 2026, Code Mode is an experimental feature, off by default, in which Claude writes JavaScript that makes several tool calls in one step. One script can run commands in parallel, use one result in the next call, and return only the part of the output Claude needs. It shipped in v2.1.323 on 12 November 2026 and may change or be removed.
How do I enable Code Mode in Claude Code?
On Claude Code v2.1.323 or later, start a terminal session with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 (PowerShell: $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"), or set that env value to "1" in ~/.claude/settings.json. Confirm "Yes, turn on Code Mode". Project settings ignore the variable, so a cloned repo cannot turn it on. Resume only works if the variable is still 1. A 0 in the shell, user settings, or managed settings keeps it off, and managed settings cannot force it on.
Does Claude Code Code Mode cut tokens by 37%?
The Code Mode docs do not claim a 37% saving. That figure is from Anthropic's 24 November 2025 engineering post on Programmatic Tool Calling in the API: average usage dropped from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks. Code Mode uses the same idea (code orchestrates tool calls so intermediate results stay out of context), and Anthropic has not published a Code Mode benchmark. Measure your own task with /cost or /status before and after, on the same prompt and model.
Why does Claude Code say Code Mode isn't available?
The line "Code Mode (experimental) isn't available" means the session started without it. Common reasons in the docs (checked 16 November 2026): version older than v2.1.323, a gateway or cloud provider instead of the Anthropic API, an unsupported model, an API key helper, agent teams, OpenTelemetry or DISABLE_TELEMETRY, a background or non-terminal surface, or managed settings with the variable set to 0. /status shows the same reason. Fix it and start a new session.
Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.
Top comments (1)
A percentage like this only means something with its denominator attached: per call, per task or per session. The same change can look large on one and almost nothing on another.