Claude Code Code Mode: How to Turn It On and What It Changes

Last updated: November 13, 2026

Code Mode is an experimental Claude Code feature, added in v2.1.323, in which Claude writes JavaScript that makes several tool calls in one step instead of asking for each Bash, Read or Edit call and reading every result. To try it, start Claude Code v2.1.323 or later with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 and confirm the prompt. It is off by default, only works in an interactive terminal session on the Anthropic API, and the docs warn that it "may change or be removed in any release."

Everything below is from the Code Mode docs and the v2.1.323 changelog, read on November 13, 2026, plus one check against the v2.1.325 binary. Code Mode needs an interactive terminal, so I did not run a Code Mode session; I checked what the binary does when you ask for it in -p.

What changes#

Without Code Mode, Claude requests one tool call, reads the result, and decides the next step. With it, Claude writes a piece of JavaScript that makes the calls, and Claude Code runs it in your session. The docs' example for "raise a retry limit":

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() });

One piece of code can run commands in parallel, feed one result into the next call, and return only the part of the output Claude needs to read. In the conversation you still see the tool calls, such as the edit's diff, not the code. Press Ctrl+O to open the transcript viewer, where each piece of code is a collapsed Code row.

The docs suggest it for "tasks that take many related tool calls": a change that repeats across many files, a search whose results need filtering before Claude reads them, and several independent commands that can run at once.

%% title: One tool call per step versus Code Mode
flowchart LR
  subgraph Default[Without Code Mode]
    A1[Claude asks for Bash] --> A2[Reads result] --> A3[Asks for Edit] --> A4[Reads result] --> A5[Asks for Bash]
  end
  subgraph CM[With Code Mode]
    B1[Claude writes JavaScript] --> B2[REPL tool runs it: rg, edit, npm test] --> B3[Returns only what Claude needs]
  end

Requirements#

Code Mode has a long list of conditions. Per the docs:

• Version: Claude Code v2.1.323 or later, on either release channel.
• Account: a Claude subscription or Console account. Not through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry.
• Organization: not using the HIPAA configuration or zero data retention.
• Model: Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2.
• Surface: an interactive claude session in a terminal. It "doesn't work with -p, the Agent SDK, the VS Code panel, the Desktop app, or cloud sessions."
• Installation: the native build. On Windows, Git for Windows.

It also won't start with an API key helper, agent teams, OpenTelemetry export or DISABLE_TELEMETRY on.

I checked the -p rule on the v2.1.325 binary: CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude -p "say ok" printed "Warning: Code Mode (experimental) isn't available: for now it only works in the interactive terminal. Starting with the ordinary tools." and then answered normally. So scripts and CI that pick up the variable keep working, without Code Mode.

How to turn it on#

1. Run claude --version and update if it is older than v2.1.323. On the stable channel you may need to wait or switch to latest.

2. Start with the variable set:

   Terminal

   Copy

   CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
   

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

   JSON

   Copy

   {
     "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 on Code Mode for you."

3. Select Yes, turn on Code Mode at the confirmation. Claude Code restarts and shows Code Mode (experimental) is on · this session can be resumed only with Code Mode on.

4. Give it a task with many tool calls, then press Ctrl+O to read the code.

Two things to remember. A Code Mode session can only be resumed in the terminal with the variable still set to 1; "With Code Mode off, Claude Code refuses to resume the session." And to turn it off, remove the variable or set it to 0: "With a 0 in one place, Code Mode stays off even if you set 1 in the other."

For administrators: set "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0" in the env block of managed settings to block it. Users already in a Code Mode session stay in it until they exit or restart, and then cannot resume those sessions. You cannot turn Code Mode on for users from managed settings.

Permissions: what to check before you try it#

This is the section to read twice. Each tool call Claude's code makes still goes through your deny and ask rules and your PreToolUse hooks, so existing rules for Bash keep working. What changes is review:

• In auto mode, "the classifier reviews each piece of code before it runs, not each tool call. It doesn't see values computed at run time, such as a path taken from search output, so keep rules or hooks for calls you must control." If you rely on auto mode as your main guardrail, that is a real change in what gets checked.
• In other permission modes, the code starts without a review, and you are prompted for each tool call that would prompt you in that mode.
• To inspect the code itself, write a PreToolUse hook that matches REPL, the tool that runs Claude's code, and read the JavaScript from tool_input.code. Our hooks guide covers the hook basics.
• Hook failures now refuse calls. On a call from Claude's code, a PreToolUse hook that fails or times out refuses the call "even when onFailure is unset". Set "onFailure": "continue" on a hook if you want calls to go ahead when it fails.

The docs repeat a general warning that applies with or without Code Mode: Bash rules match command text, so a denied command can run in a form the rule does not match. Use sandboxing for limits that do not depend on text. If unattended sessions are the concern, permissions.denyInsteadOfPrompting is the other recent setting to know.

Long-running code and limits#

• Waiting: by default Claude waits for the code to finish, and the code "stops after ten minutes, including time you spend at permission prompts."
• Background: started in auto or bypassPermissions mode, code can keep running for up to two hours while you keep talking to Claude.
• Countdown prompts: in auto mode, if Claude starts new code while earlier code still runs, the earlier code loses its classifier review, and you get a prompt with a countdown such as "Claude Code will automatically block this request in 1:59". Miss it and the call is refused.
• Not available in Code Mode: Remote Control, Claude in Chrome and computer use. You also cannot move the session to the Desktop app, turn it into a background session, or start a background copy with /fork.

Troubleshooting the start line#

If the session starts with Code Mode (experimental) isn't available, the reason follows on the same line and in /status. The common ones from the docs' table:

Should you turn it on?#

For repetitive multi-file edits and searches that need filtering, Code Mode is worth an afternoon on a project you know well, which is what the docs suggest. Keep it off for now if you depend on Remote Control, agent teams, OpenTelemetry export, a gateway or a cloud provider, or if your safety model relies on the auto mode classifier seeing each individual call. It is experimental and the docs say so plainly.

FAQ#

How do I turn on Code Mode in Claude Code?#

On Claude Code v2.1.323 or later, start claude with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 in your shell, or put it in the env block of ~/.claude/settings.json, then confirm with "Yes, turn on Code Mode". Project settings files cannot turn it on.

Does Code Mode work with claude -p or the Agent SDK?#

No. Code Mode only works in an interactive claude session in a terminal. In claude -p, v2.1.325 prints a warning that Code Mode is not available and starts with the ordinary tools.

Can I use Code Mode on Bedrock, Vertex or through a gateway?#

No. It needs a Claude subscription or Console account on the Anthropic API, and one of Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2. It does not work through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud or Microsoft Foundry.

How do permissions work in Code Mode?#

Each tool call the code makes still goes through your deny and ask rules and your PreToolUse hooks. In auto mode the classifier reviews each piece of code before it runs, not each tool call, so it does not see values computed at run time.

How do I block Code Mode for my organization?#

Set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to "0" in the env block of your managed settings. Users already in a Code Mode session keep it until they exit or restart, and cannot resume Code Mode sessions afterwards.

Sources#

• Run tool calls from code with Code Mode - Claude Code Docs
• Claude Code CHANGELOG, v2.1.323 - "Added Code Mode, an experimental opt-in"
• Claude Code permission modes
• Claude Code hooks reference

Continue Reading#

• Claude Code Auto Mode Explained - the classifier that now reviews code instead of calls
• Claude Code Hooks Explained - write the PreToolUse hook that reads tool_input.code
• Claude Code denyInsteadOfPrompting - the other recent permissions setting for unattended work