Paulund
Subscribe

Claude Code's Code Mode: what it is and when to turn it on

18 November 2026, 7 min read

On this page
  1. What changes
  2. Why fewer steps matter
  3. When to use it
  4. Turning it on
  5. What you give up
  6. Permissions and hooks

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:

JavaScript
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:

  1. Search src for the file that defines retryPolicy.
  2. Take the first file from the results.
  3. Change maxAttempts: 3 to maxAttempts: 5 in that file.
  4. 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:

Text
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 claude session 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:

Terminal
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

To turn it on for every new session, put it in ~/.claude/settings.json:

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:

Text
Code Mode (experimental) is on · this session can be resumed only with Code Mode on

If 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+Tab to get back to the mode you started in;
  • you picked the session from the claude --resume list;
  • 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.

Earlier in AI

17 November 2026How I review AI-written pull requests

Tags

  • AI
  • Claude code
  • Agents
  • Workflow