Part of the AI Coding Harness Guide — environment design for coding agents in production.

Claude Code Code Mode: How to Turn It On, and Why It Won't Start#

Published by

Code Mode is an experimental Claude Code mode in which Claude writes JavaScript that makes several tool calls in one step, then returns only the part of the output it needs. Turn it on with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 in v2.1.323 or later. It is off by default and needs a Claude subscription or Console account, the native build, and a 5.5 model or Fable 5.2.[1][2]

What Code Mode changes#

Without Code Mode, Claude asks for one tool call at a time (Bash, Read, Edit) and reads each full result before it picks the next call. With Code Mode, Claude writes a script that makes the calls, and Claude Code runs it in your session through a tool named REPL.[2] One script can:

  • run independent commands in parallel
  • feed one result into the next call
  • filter a search or a JSON response, and return only what Claude needs to read

The context saving comes from the last point. Intermediate output, such as a file list or a raw API response, stays inside the script; only the value the script returns enters the conversation. Anthropic publishes no token figure for it, and the saving depends on how much output a task throws away.

This is the example from the Code Mode docs. The script finds a file, edits it and runs the tests, and the last line returns the path and the test output:[2]

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

You see the tool calls in the conversation, such as the edit's diff, and not the script. Press Ctrl+O to open the transcript viewer, where each script is a collapsed Code row.

How to turn on Code Mode#

  1. Run claude --version. If it is older than 2.1.323, run claude update. The stable channel can lag; switch to latest or wait.
  2. Start Claude Code with the variable set:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

In PowerShell, run $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1", then claude. To keep it on for every session, put it in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}
  1. Select Yes, turn on Code Mode at the first prompt. Claude Code restarts and shows Code Mode (experimental) is on · this session can be resumed only with Code Mode on.[2]

A project's .claude/settings.json cannot set this variable, so a cloned repository cannot turn Code Mode on for you.[2]

How to turn it off, or block it for an organization#

Remove the variable from your shell and from ~/.claude/settings.json, or set it to 0, and start a new session. A 0 in one place wins over a 1 in the other.[2]

To block it for everyone, put "0" in managed settings:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

Running Code Mode sessions continue until they exit. After that, nobody can start or resume one while the 0 is in place. Managed settings cannot turn Code Mode on for users.[2]

Requirements#

RequirementCode Mode works withCode Mode does not work with
Version2.1.323 or later, either channel2.1.318 to 2.1.322 (the variable exists, the mode reports it isn't open to your account yet)
AccountClaude subscription, Console account, ANTHROPIC_API_KEYBedrock, Vertex (Agent Platform), Foundry, Claude Platform on AWS, LLM gateways, a custom ANTHROPIC_BASE_URL, apiKeyHelper
ModelOpus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.2older models
Surfaceinteractive claude in a terminal, native build-p, Agent SDK, VS Code panel, Desktop app, cloud sessions, --remote-control
OrganizationstandardHIPAA configuration, zero data retention
SettingsdefaultsDISABLE_TELEMETRY (or any variable that stops feature-flag fetching), OpenTelemetry export, agent teams, --restricted, REPL denied
WindowsGit for Windows installedwithout Git for Windows

Source: the Code Mode requirements and troubleshooting table.[2]

Why Code Mode won't start#

Code Mode (experimental) isn't available at the top of the session means it started without Code Mode, and the reason follows on the same line and in /status.[2]

Reason includesFix
it isn't open to your account yetUpdate to 2.1.323+. If already there, check the network and retry; the docs say to try another day if it stays
it only works with the Anthropic APIRemove Bedrock, Vertex, Foundry, gateway or custom ANTHROPIC_BASE_URL settings
it doesn't work with an API key helperRemove apiKeyHelper, ANTHROPIC_AUTH_TOKEN and auth headers in ANTHROPIC_CUSTOM_HEADERS; sign in or set ANTHROPIC_API_KEY
it only works with Opus 5.5, Sonnet 5.5 and later modelsStart with --model opus or another supported model
it needs settings that Claude Code downloads from AnthropicUnset DISABLE_TELEMETRY and similar variables. The same cause hides Fable 5.2 from /model
OpenTelemetry is onUnset CLAUDE_CODE_ENABLE_TELEMETRY and ENABLE_BETA_TRACING_DETAILED
it can't be used together with agent teams yetUnset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
this launch's tool optionsDrop --restricted; add REPL to --tools; remove REPL from --disallowedTools and deny rules
couldn't save your answerMake ~/.claude.json writable
your organization's settings don't allow itManaged settings set the variable to 0

No Code Mode line at all means the variable is not 1, a 0 is set somewhere (including a --settings file), or the version is older than 2.1.323.

Permissions and hooks in Code Mode#

Every tool call a script makes still goes through your deny and ask rules and your PreToolUse hooks, with no rule changes needed. Two things differ:[2]

  • Auto mode reviews the script, not each call. The classifier sees the code before it runs, not values computed at run time, such as a path taken from search output. Keep deny rules or hooks for calls you must control.
  • A hook that fails refuses the call. On a call from a script, a PreToolUse hook that cannot start, crashes or returns invalid output refuses the call (the hook failed), and one that times out refuses it too (the hook did not finish), even without onFailure. Set "onFailure": "continue" to let calls through.

To inspect scripts, write a PreToolUse hook that matches REPL and reads the JavaScript from tool_input.code.

When Claude starts a second script in auto mode while the first still runs, the first loses its classifier review, and you get a prompt with a two-minute countdown: Claude Code will automatically block this request in 1:59. An unanswered prompt refuses the call.[2]

Limits#

  • A script you wait on stops after ten minutes, permission prompts included. A script in the background (session started in auto or bypassPermissions mode) runs up to two hours.
  • A Code Mode session resumes only in the terminal, with the variable still 1. Without it, claude --resume refuses the session.
  • No Remote Control, Claude in Chrome or computer use, no move to the Desktop app or a background session, and /fork cannot start a background copy.[2]

Timeline#

VersionPublished (npm)Change
2.1.3182026-11-03CLAUDE_CODE_EXPERIMENTAL_CODE_MODE and the opt-in prompt appear, not yet open to accounts (v2.1.318 post)
2.1.3232026-11-12Changelog announces Code Mode as an experimental opt-in; minimum version in the docs[1]
2.1.3252026-11-13Fixes scripts ignoring a worktree from EnterWorktree, ~ paths written into the project, /mcp showing an expired server as connected, typed words lost at a permission or plan prompt, and Claude starting work by itself after resuming a session that ended mid-script[3]

Should you turn on Code Mode?#

Try it on tasks with many related tool calls: one change across many files, a search whose results need filtering, or independent commands that can run at once. Leave it off if you depend on Bedrock, Vertex, a gateway, apiKeyHelper, OpenTelemetry, DISABLE_TELEMETRY or the VS Code panel, since none of them work with it. In auto mode, check that your deny rules cover what the classifier can no longer see per call. It is experimental, and the docs say it can change or be removed in any release.

FAQ#

Q: What is Code Mode in Claude Code?

A: An experimental mode in which Claude writes JavaScript that makes several tool calls in one step and returns only the output it needs, instead of calling Bash, Read and Edit one at a time.

Q: How do I turn on Code Mode?

A: Run Claude Code 2.1.323 or later with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1, in your shell or in the env block of ~/.claude/settings.json, and confirm the prompt.

Q: Does Code Mode save tokens?

A: It can. Output that a script filters out never enters the conversation. Anthropic publishes no figure, and the saving depends on the task.

Q: Does Code Mode work on Bedrock or Vertex?

A: No. It needs a Claude subscription or Console account on the Anthropic API, not Bedrock, Vertex, Foundry or a gateway.

Q: How do I disable Code Mode for my organization?

A: Set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to "0" in the env block of managed settings.

Q: Why does Code Mode say "it isn't open to your account yet"?

A: The version is older than 2.1.323, or the account check failed. Update, check the network and start again.


Sources: [1] Claude Code changelog, v2.1.323 | [2] Run tool calls from code with Code Mode (Claude Code docs) | [3] Claude Code changelog, v2.1.325 | r/ClaudeCode: "Claude Code 2.1.323: experimental Code Mode (Claude writes JS to call tools)"

Related: Claude Code v2.1.318: an experimental Code Mode | Fable 5.2 missing when DISABLE_TELEMETRY is set | Context Window Management Guide | CLAUDE_CODE_EXPERIMENTAL_CODE_MODE in the env-var glossary | Claude Code Version Tracker

Get the weekly digest

New Claude Code, Codex, Gemini CLI and OpenCode guides and release analyses, once a week, plus occasional notes.

One email a week plus occasional notes. Confirm by email; unsubscribe from any issue. Privacy