Omniscio

OmniscioGuidesClaude Code Code Mode

Claude Code Code Mode: tool calls from JavaScript

Most of what Claude Code does is a sequence of small tool calls, each one waiting on the answer to the last. Code Mode collapses that: Claude writes one piece of JavaScript that makes the calls, keeps the intermediate results to itself, and returns the part it needs to read.

This page covers what changes in a turn, the tasks it suits, the limits to accept before you switch it on, how permissions and hooks see the code, and what each refusal message means.

Last checked against Anthropic's Claude Code documentation on November 20, 2026. By the Omniscio team. Updated .

What Code Mode changes

Without Code Mode, Claude asks for tool calls such as Bash, Read or Edit directly and reads each result before deciding what to do next. With Code Mode, Claude writes a piece of JavaScript that makes the tool calls, and Claude Code runs that code in your session.

Anthropic's example is a good picture of why that matters. Asked to raise a retry limit, Claude might write this, which finds the file, edits it, runs the tests, and returns only the 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() });

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

Sources: the introduction, "How Code Mode works" and the example under it in Run tool calls from code with Code Mode, read November 20, 2026.

When it is worth turning on

Anthropic points at tasks that take many related tool calls, and gives three shapes: 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 the same time.

A task that needs one edit and one test run gains nothing. The token usage guide covers what a long turn costs when it does not collapse.

Source: "When to use Code Mode" in Run tool calls from code with Code Mode, read November 20, 2026.

The limits to accept first

Anthropic lists six limits, and two of them change how a session can be used afterwards. Read this before switching:

  • Resuming. A Code Mode session can be resumed only in the terminal, with Code Mode on. With the variable off, Claude Code refuses to resume it.
  • Auto mode. The classifier reviews the code, not each tool call.
  • Long-running code. Unless code can run in the background, you wait for it, and it stops after ten minutes.
  • Hooks. A tool call can be refused when a PreToolUse hook does not finish, for example after a timeout.
  • Unavailable features. No Remote Control, no Claude in Chrome, no computer use.
  • Moving the session. It cannot be moved to the Desktop app or turned into a background session, and /fork cannot start a background copy.

Source: "Code Mode limitations" in Run tool calls from code with Code Mode, read November 20, 2026.

Turn it on, and off

The requirements come before the switch, because most refusals are one of them:

  • Version. Claude Code v2.1.323 or later, on either release channel. claude --version tells you, and claude update moves you.
  • Installation. The native build.
  • Account and model. A Claude subscription or Console account, using Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.2. Not through a gateway, Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Claude Models on Google Cloud (Anthropic managed) or Microsoft Foundry.
  • Organization. Your organization does not use the HIPAA configuration or zero data retention.
  • Surface. An interactive claude session in a terminal. Not the VS Code panel, the Desktop app or a cloud session.
  • Windows. Git for Windows installed.

The switch is an environment variable. For a trial, set it in your shell:

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

To have it on every session, put it in the env block of ~/.claude/settings.json. Anthropic notes that Claude Code ignores this variable in a project's settings files, so a repository you clone cannot turn Code Mode on for you. The first time, Claude Code asks you to confirm, restarts, and shows a line near the top of the session: Code Mode (experimental) is on · this session can be resumed only with Code Mode on.

To resume a session later, keep the variable set. This is the limit people discover too late: claude --continue or claude --resume with Code Mode off refuses the session. A session you started without Code Mode resumes without it, even with the variable set.

To turn it off, remove the variable from your shell and from ~/.claude/settings.json and start a new session. A 0 in either place keeps Code Mode off even if the other says 1. An organization can force it off by putting CLAUDE_CODE_EXPERIMENTAL_CODE_MODE with the value 0 in managed settings; users already in a Code Mode session stay in it until they exit or restart, and cannot resume it while the zero is in place.

Sources: "Requirements", "Try Code Mode" and "Turn off Code Mode" in Run tool calls from code with Code Mode, read November 20, 2026.

Permissions, prompts and hooks

The important reassurance: Code Mode does not bypass your rules. Each tool call in the code goes through your deny and ask rules and your PreToolUse hooks under the tool's usual name, such as Bash or an MCP tool's name.

The difference is where the review happens. In auto mode the classifier reviews each piece of code before it runs, not each tool call, and it does not see values computed at run time, such as a path taken from search output. That is why Anthropic's advice is to keep rules or hooks for the calls you must control. In the other permission modes you are prompted for each tool call that would prompt you anyway.

A PreToolUse hook that checks shell commands needs to check each part of a command, the way Bash rules do, because a git push in a folder named app can reach it as cd 'app' && git push. To inspect the code itself, match REPL, the tool that runs it, and read the JavaScript from tool_input.code.

Three settings shape the prompts:

  • permissions.ask with Bash(git push *) still prompts for a matching command in auto or bypassPermissions mode.
  • permissions.ask with REPL prompts before any piece of code runs, so you can read it first with Ctrl+O.
  • Stopping the code at a prompt: answering No or pressing Esc stops the whole piece of code and keeps the changes already made. Answering No and typing a reason into the prompt instead of sending a bare No refuses only that one call, and the code continues with its others.

The hooks guide covers PreToolUse and PostToolUse in full, and permission modes covers auto mode.

Source: "Permissions and long-running code", including "Permission checks", in Run tool calls from code with Code Mode, read November 20, 2026.

Long-running code and stopping it

While code runs a long build or test, Claude either waits for it or lets it continue in the background. Waiting means Claude answers when the code finishes, and the code stops after ten minutes; in Manual and acceptEdits modes, time you spend at a tool's permission prompt does not count toward that. Background means you can keep talking to Claude, and the code can run for up to two hours.

Background code needs the session to have started in auto or bypassPermissions mode. If Claude still waits, check your current mode and how you started the session: switching modes with Shift+Tab takes you out of the mode the session started in, and claude --continue --permission-mode auto with Code Mode on is the way back in.

To stop code while Claude is responding or waiting for it, press Esc. To stop background code after Claude finishes responding, run /tasks, select the running task and press x. Check /tasks afterwards for subagents, shell commands and MCP calls the code started that are still running.

Your sandbox settings apply to the shell commands the code runs, but the JavaScript itself and its file, web and MCP calls run outside the sandbox. To isolate those too, Anthropic points at a container or virtual machine.

Sources: "Limit shell commands with the sandbox" and "Long-running code" in Run tool calls from code with Code Mode, read November 20, 2026.

When Code Mode will not start

A session that started without Code Mode prints Code Mode (experimental) isn't available near the top, and the reason follows on the same line. /status shows it too. Anthropic's table maps each reason to a fix; these are the ones that recur:

  • it isn't open to your account yet: update if you are below v2.1.323, otherwise check your connection and try again another day.
  • it only works directly with the Anthropic API: remove whatever routes requests through a cloud provider, a gateway, or a custom ANTHROPIC_BASE_URL.
  • it doesn't work with an API key helper: remove apiKeyHelper, ANTHROPIC_AUTH_TOKEN and any Authorization or X-Api-Key header in ANTHROPIC_CUSTOM_HEADERS, then sign in or set ANTHROPIC_API_KEY.
  • it only works with Opus 5.5, Sonnet 5.5 and later models: start with a supported model, for example --model opus. Haiku 5.5 and Fable 5.2 also work, on the versions the requirements above name.
  • OpenTelemetry is on: unset CLAUDE_CODE_ENABLE_TELEMETRY and ENABLE_BETA_TRACING_DETAILED if you can work without the export.
  • it doesn't yet work with the plugin: run /plugin and disable each plugin the reason names.

If you see no line about Code Mode at all, check claude --version, then confirm the variable is 1 in your shell or user settings and that no --settings file sets it to 0.

Source: "Code Mode doesn't start" in Run tool calls from code with Code Mode, read November 20, 2026.

Where these answers come from

No Code Mode session was run on this site's machine to check the page: the feature is experimental, and every claim is quoted from Anthropic's documentation, which says it may change or be removed in any release.

Common questions

Can I see the JavaScript Claude wrote?

Yes. Press Ctrl+O and expand a Code row in the transcript viewer.

Does Code Mode work in the VS Code panel?

No. It needs an interactive claude session in a terminal, and it does not work in the Desktop app or in cloud sessions.

Does it work with agent teams?

On v2.1.326 or later. Teammates run in Code Mode in the default in-process display mode, and start without it in split panes. With an older version the session reports it can't be used together with agent teams yet.

Is it on by default anywhere?

No. Anthropic says it is experimental and off by default, and even with the variable set an organization can turn it off through managed settings.