Claude Code's Code Mode: what it is and when to turn it on
On this page
Claude Code has an experimental feature called Code Mode. Without Code Mode, Claude asks for tool calls such as Bash, Read or Edit directly, and reads each result before it decides what to do next. In Code Mode, Claude writes a short piece of JavaScript that makes the tool calls, and Claude Code runs that code in your session.
Every step Claude takes sends the whole conversation back to the model. I found that out when I audited my own sessions and saw that long Claude Code sessions pay for their whole history on every call. Code Mode can do several tool calls in one step, so it is worth knowing what it changes and what it breaks.
What changes
You still describe the task in a prompt. The difference is in how Claude carries it out. One piece of code can:
- run several commands at the same time;
- use the result of one call in the next call;
- return only the part of the output Claude needs to read.
The Code Mode docs give this example. If you ask Claude to raise a retry limit, it might write:
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() });Line by line:
- Search
srcfor the file that definesretryPolicy. - Take the first file from the results.
- Change
maxAttempts: 3tomaxAttempts: 5in that file. - Run the tests for
retryPolicy, and return the file path and the test output to Claude.
Without Code Mode, Claude would ask for each of those tool calls separately and read each result. In Code Mode, one piece of code makes the calls and returns the part of the output Claude needs to read.
In the conversation you still see the tool calls, such as the diff of the edit. You don't see the code. To read it, press Ctrl+O to open the transcript viewer, where each piece of code is a collapsed "Code" row you can expand.
Why fewer steps matter
In that audit, the cost of each step grew with the size of the conversation. Every tool result Claude reads stays in the conversation and is sent again on every later step.
Code Mode can help on both counts. It makes several tool calls in one step, so there are fewer steps. The code can also cut a large output down before Claude reads it, so less stays in the conversation. The docs don't say how much Code Mode saves. This is my reasoning from that audit.
When to use it
The docs suggest trying it on tasks that take 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 docs suggest this prompt for a first try:
Read every Markdown file in this project and list the links that point to local files that don't exist.It needs many file reads, and only a short list of broken links has to come back.
Turning it on
You need:
- Claude Code v2.1.323 or later, on the native build;
- an interactive
claudesession in a terminal; - a Claude subscription or a Console account, used directly with the Anthropic API;
- Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2;
- an organization that doesn't use the HIPAA configuration or zero data retention;
- on Windows, Git for Windows.
Check your version with claude --version and run claude update if it is older. If you're on the stable channel and the update doesn't reach v2.1.323, wait for it or switch to latest. Then set the environment variable when you start Claude Code:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claudeTo turn it on for every new session, put it in ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}Claude Code ignores this variable in a project's settings files, so a repository you clone can't turn Code Mode on for you.
The first time, Claude Code asks you to confirm. Pick "Yes, turn on Code Mode". Claude Code then restarts and shows this line near the top of the session:
Code Mode (experimental) is on · this session can be resumed only with Code Mode onIf you see Code Mode (experimental) isn't available instead, the reason follows on the same line, and /status shows it too. The docs have a troubleshooting table for each reason.
To turn it off, remove the variable from your shell and your settings, or set it to 0, and start a new session. A 0 in either place wins over a 1 in the other. An admin can block it for a whole organization by setting the variable to 0 in managed settings.
What you give up
Code Mode is experimental and off by default. The docs say it may change or be removed in any release. These are the limits to check first.
Where it runs and what it turns off
It doesn't work with claude -p, the Agent SDK, the VS Code panel, the Desktop app or cloud sessions. So it won't help the tasks I start with claude --cloud, as I described in sending a prompt to a cloud session.
You can't use Remote Control, Claude in Chrome or computer use in a Code Mode session. With agent teams on, you need v2.1.326 or later.
Resuming and moving the session
You can only resume a Code Mode session in the terminal, with the variable still set to 1. With it off, Claude Code refuses to resume the session. A session you started without Code Mode resumes without it, even with the variable set.
You can't move the session to the Desktop app or make it a background session, and /fork can't start a background copy.
Long-running code
Code stops after ten minutes, and that includes time you spend at permission prompts. If you start the session in auto mode or bypassPermissions mode, code can run in the background for up to two hours while you keep talking to Claude.
Claude goes back to waiting in three cases:
- you switch to another mode, until you press
Shift+Tabto get back to the mode you started in; - you picked the session from the
claude --resumelist; - you passed tool names to
--tools.
Settings that block it
It won't start with an API key helper, OpenTelemetry export or DISABLE_TELEMETRY. Some plugins block it, and the "isn't available" line names them. A mod that checks tool calls blocks it too.
Hooks that fail
If a PreToolUse hook fails or times out on a call from code, the call is refused, even if you never set onFailure. Once Claude has run code in the session, a hook that times out refuses any tool call. To let calls go ahead, set "onFailure": "continue" on a command or http hook. A UserPromptSubmit hook can also block the output of background code.
Permissions and hooks
Your deny and ask permission rules still apply to every tool call inside the code. Your PreToolUse hooks still run too, under each tool's usual name, such as Bash.
In auto mode there is one more check. The classifier reviews each piece of code before it runs, not each tool call. It can't see values the code works out while it runs, such as a path taken from search output. The docs advise keeping rules or hooks for any call you must control. If Claude starts new code while older code is still running, you may get a prompt with a countdown. If you don't answer in time, the call is refused.
In the other permission modes, the code starts without a review, and you're asked about each tool call that would normally ask you.
Hooks that check shell commands may need a change. In Code Mode, a git push in a folder named app can reach your hook as cd 'app' && git push, so a hook should check each part of a command. If you want to check the code itself, write a PreToolUse hook that matches REPL, the tool that runs the code, and read the JavaScript from tool_input.code.