Skip to content
Claude Code Mods

Code Mode: Claude writes JavaScript that calls its tools

Code Mode lets Claude write JavaScript that makes many tool calls in one step. How to turn it on, what it needs, its limits and how permissions and hooks apply.

Published . Checked against Claude Code v2.1.329. This site is unofficial; the sources under each section are Anthropic's own pages.

What Code Mode is

Note

Code Mode is experimental and off by default. Anthropic's docs say it may change or be removed in any release. It arrived in Claude Code v2.1.323, released on November 12, 2026.

Without Code Mode, Claude asks for one tool call at a time, such as Bash, Read or Edit, and reads each result before it decides what to do next. With Code Mode on, Claude writes a piece of JavaScript that makes the tool calls, and Claude Code runs that code in your session. 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.

This is the example from the docs. Asked to raise a retry limit, Claude finds the file, edits it and runs the tests in one step, and the last line returns the file's path and 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 conversation you see the tool calls, such as the edit's diff, and not the code. Press Ctrl+O to open the transcript viewer, where each piece of code is a collapsed Code row you can expand.

Source: Run tool calls from code with Code Mode (opens in a new tab), Claude Code changelog (opens in a new tab)

When it helps, and what you give up

The docs suggest Code Mode 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
  • Several independent commands that can run at the same time

Check these limits before you turn it on:

  • You can resume a Code Mode session only in the terminal, with Code Mode on.
  • In auto mode, the classifier reviews each piece of code, not each tool call inside it.
  • Unless code runs in the background, you wait for it, and it stops after ten minutes.
  • Remote Control, Claude in Chrome and computer use are not available.
  • You can't move the session to the Desktop app or turn it into a background session, and /fork can't start a background copy.

Source: Run tool calls from code with Code Mode (opens in a new tab)

What it needs

  • Claude Code v2.1.323 or later, on the native build. On Windows, Git for Windows must be installed.
  • A Claude subscription or Console account. It does not work through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry.
  • An organization that doesn't use the HIPAA configuration or zero data retention.
  • Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2.
  • 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.
  • For agent teams, v2.1.326 or later. Teammates run in Code Mode in the in-process display mode and start without it in split panes.

Some settings also keep it off, such as an API key helper or DISABLE_TELEMETRY. When Code Mode can't start, the session shows Code Mode (experimental) isn't available with the reason, and /status shows the same reason. Since v2.1.329 it can run with OpenTelemetry events and metrics on, and each tool call the code makes sends its own events. Tracing still keeps it off.

Source: Run tool calls from code with Code Mode (opens in a new tab), Claude Code changelog (opens in a new tab)

Turn it on, and off

Run claude --version and update with claude update if you are below v2.1.323. Then set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to 1, either for one session from your shell:

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

or for every new session, in your user settings:

~/.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. Before your first Code Mode session it asks you to confirm. After you pick Yes, it restarts and shows Code Mode (experimental) is on near the top of the session.

Warning

Keep the variable set to 1 when you run claude --continue or claude --resume on a Code Mode session. With Code Mode off, Claude Code refuses to resume it.

To turn it off, remove the variable or set it to 0. A 0 in either your shell or your settings wins over a 1 in the other. An administrator can set it to 0 in managed settings so nobody in the organization can use Code Mode. Managed settings can't turn it on for users.

Source: Run tool calls from code with Code Mode (opens in a new tab)

How permissions and hooks see the code

Each tool call in the code still goes through your deny and ask permission rules and your PreToolUse hooks, under the tool's usual name such as Bash. In the modes that ask, you are prompted for each call that would prompt you anyway. In auto mode, the classifier reviews the code before it runs. 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.

The tool that runs the code is called REPL. Add an ask rule for REPL to approve each piece of code before it starts, match REPL in a PreToolUse hook to read the JavaScript from tool_input.code, or match it in a PostToolUse hook to check or redact what the code returns with updatedToolOutput.

~/.claude/settings.json
{
  "permissions": {
    "ask": ["REPL"]
  }
}

Two hook details change. A shell command can reach your hook in another form, for example a git push in a folder named app as cd 'app' && git push, so check each part of a command. And a PreToolUse hook that can't start, is killed or times out refuses the call even without onFailure. Since v2.1.328, UserPromptSubmit hooks no longer receive code output, so move any check of code output to a PostToolUse hook. Hooks that block Claude's actions covers the rules outside Code Mode.

Source: Run tool calls from code with Code Mode (opens in a new tab), Claude Code changelog (opens in a new tab)

Long-running code

Claude either waits for code to finish, in which case the code stops after ten minutes, or lets it run in the background for up to two hours while you keep talking. Background code needs a session started in auto or bypassPermissions mode. Press Esc to stop code while Claude is responding. To stop background code later, open /tasks, select the task and press x, then check /tasks for subagents, shell commands and MCP calls the code started.

Since v2.1.328, time you spend at a permission prompt in Manual and acceptEdits modes no longer counts toward the ten minutes.

Source: Run tool calls from code with Code Mode (opens in a new tab), Claude Code changelog (opens in a new tab)