Claude Code Code Mode: How to Turn It On, When to Use It and Limits (2.1.323)

Claude Code 2.1.323 added Code Mode, an experimental opt-in where Claude writes JavaScript to call its tools instead of asking for them one at a time. The same release lets plugin authors set a supported Claude Code version range.

Code Mode can chain searches, edits and test runs in one step. In this guide I explain how it works, how to turn it on, when it helps and the limits you must accept first.

What Code Mode Is

Normally Claude asks for one tool call, such as Bash, Read or Edit, reads the result and then decides the next step. Each round trip costs a model turn.

With Code Mode on, Claude writes a short piece of JavaScript that makes the tool calls for it. One script can run commands in parallel, feed one result into the next call, and return only the part of the output Claude needs to read.

What the code looks like

Here is the example from the official docs. You ask Claude to raise a retry limit, and it writes this to find the file, edit it and run the tests:

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

The last line returns the edited path and the test output back to Claude. In the chat you still see the tool calls, such as the edit diff, not the raw code.

Tip: press Ctrl+O to open the transcript viewer. Each script shows as a collapsed Code row you can expand.

Requirements

Code Mode has a long list of conditions. Check every row before you try it, because a missing one simply starts the session without Code Mode.

Some settings also block it. These include an API key helper, agent teams, OpenTelemetry export and DISABLE_TELEMETRY. The troubleshooting section below lists the fix for each.

Note: version 2.1.323 was published to npm on November 12, 2026. If you need a fresh install first, follow my Claude Code install guide.

How to Turn On Code Mode

Code Mode is controlled by one environment variable. Here are the steps from the official docs.

1. Check your version. Run claude --version. If it is older than 2.1.323, run claude update. On the stable channel, wait for stable to catch up or switch to latest.
2. Set the variable. Start Claude Code with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude on macOS, Linux or WSL. On Windows PowerShell, set $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1" and then run claude.
3. Confirm. On first use, Claude Code asks you to confirm. Select Yes, turn on Code Mode. It restarts and shows a line saying Code Mode (experimental) is on.
4. Give it a multi-step task. Try a prompt like “Read every Markdown file in this project and list the links that point to local files that don’t exist.”
5. Read the code. Press Ctrl+O, expand a Code row, then press Ctrl+O again to return.

Turn it on for every session

To keep it on, add an env block to your user settings file at ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

Claude Code ignores this variable in a project’s settings files. That means a repository you clone cannot switch Code Mode on behind your back.

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

When to Use It (and When Not To)

Anthropic suggests trying Code Mode on tasks that need many related tool calls. These are the three patterns the docs name:

• Repeated changes: the same edit across many files, such as renaming an option or bumping a value.
• Filtered searches: a search whose results need trimming before Claude reads them, which keeps noise out of context.
• Parallel commands: several independent commands, like lint, type check and tests, that can run together.

Skip it for small one-file fixes, sessions you plan to hand to the Desktop app, or work that needs Remote Control or Claude in Chrome. For general token-saving habits, see my guide on reducing Claude Code token usage.

Permissions, Hooks and Long-Running Code

Code Mode does not bypass your safety settings. Each tool call the script makes still goes through your deny and ask rules and your PreToolUse hooks.

How each mode checks the code

• Auto mode: a classifier reviews each script before it runs, not each tool call. It cannot see values worked out at run time, such as a path taken from search output.
• Other modes: the script starts without a review, and you are prompted for each tool call that would normally prompt you.
• Your own checks: write a PreToolUse hook that matches the REPL tool and read the JavaScript from tool_input.code.

My Claude Code hooks guide shows how to write that kind of hook, and the auto mode guide covers the classifier in more depth.

Waiting vs background code

If Claude still waits, press Shift+Tab back to the mode you started in. If you passed tool names to --tools, start again in auto mode without that flag.

Limitations

The docs ask you to accept these limits before turning it on.

• Resuming: only in the terminal, and only with Code Mode on.
• Auto mode: the classifier reviews code, not each call.
• Long code: stops after ten minutes unless it can run in the background.
• Hooks: calls can be refused when a PreToolUse hook fails or times out, and output can be blocked by a UserPromptSubmit hook.
• Unavailable: Remote Control, Claude in Chrome and computer use.
• Moving sessions: no handoff to the Desktop app, no background session, and /fork cannot start a background copy.
• Stability: it is experimental and may change or be removed in any release.

Version 2.1.325 already fixed several early bugs. Scripts now respect a worktree entered with EnterWorktree, and resumed sessions no longer start work by themselves.

Turn It Off or Block It for Your Organisation

To turn it off for yourself, remove the variable from your shell and from ~/.claude/settings.json, or set it to 0. A 0 in either place wins over a 1 in the other.

Admins can block it for everyone by adding the same variable with the value 0 to managed settings:

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

Users already in a Code Mode session stay in it until they exit or restart. Admins cannot force Code Mode on from managed settings.

Plugin Version-Range Controls

The second headline change in 2.1.323 is for plugin authors. You can now add engines["claude-code"] to plugin.json to state which Claude Code versions your plugin supports.

• Outside the range: the plugin is not installed, updated or loaded.
• Install and update: Claude Code picks the newest plugin version that fits your Claude Code version.
• Validation: claude plugin validate now also type-checks a plugin’s TypeScript hooks module and treats findings as warnings.

The changelog does not print the exact range syntax yet. A semver-style range, like the ranges used for plugin dependencies, is the natural fit:

{
  "name": "my-plugin",
  "version": "1.4.0",
  "engines": {
    "claude-code": ">=2.1.323"
  }
}

Run claude plugin validate after adding it to confirm your syntax.

My Take

Code Mode is a smart idea. Letting the model write a small script instead of making ten round trips should make repetitive, multi-file work feel faster and keep noisy output out of context.

But it is clearly early. The surface is terminal only, it does not work on Bedrock or Foundry, and auto mode reviews code rather than each call. Teams with strict audit needs may want to block it for now.

For solo developers on a Claude subscription, it is worth a try on a throwaway branch. Keep your deny rules and hooks in place, and read the code with Ctrl+O until you trust it.

Troubleshooting

If the session shows “Code Mode (experimental) isn’t available”, the reason follows on the same line and in /status.

• “it isn’t open to your account yet”: update to 2.1.323 or later, check your network, or try again another day.
• “it only works with the Anthropic API”: remove cloud provider settings, gateways or a custom ANTHROPIC_BASE_URL.
• “it doesn’t work with an API key helper”: remove apiKeyHelper and ANTHROPIC_AUTH_TOKEN, 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 claude --model opus.
• “OpenTelemetry is on”: unset CLAUDE_CODE_ENABLE_TELEMETRY and ENABLE_BETA_TRACING_DETAILED if you can work without them.
• “it can’t be used together with agent teams yet”: unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.
• “couldn’t save your answer”: make ~/.claude.json writable.
• Tool call refused with “the hook did not finish”: raise that hook’s timeout, or set "onFailure": "continue" on it.
• No Code Mode line at all: check the version, make sure the variable is 1, and remove any 0 from your settings files.

Frequently Asked Questions

Is Code Mode free?

There is no separate charge. It is part of Claude Code, and usage counts against your normal Claude subscription or Console API billing. See my Claude Code pricing guide for plan details.

Does Code Mode work in VS Code?

Not in the VS Code panel. It needs an interactive claude session in a terminal, though that terminal can be the one built into VS Code.

Can I use Code Mode with Amazon Bedrock or Microsoft Foundry?

No. The docs say it only works with the Anthropic API through a Claude subscription or Console account, not gateways or cloud providers.

Which models support Code Mode?

Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.2. Older models start the session without Code Mode.

Does Code Mode skip my permission rules?

No. Every tool call from the script still passes through your deny and ask rules and PreToolUse hooks. In auto mode, the classifier reviews the script as a whole.

Can a cloned repo turn on Code Mode?

No. Claude Code ignores the Code Mode variable in project settings files, so only your shell, user settings or managed settings count.

What does engines[“claude-code”] do in plugin.json?

It states the Claude Code versions a plugin supports. Outside that range, the plugin is not installed, updated or loaded.

Sources

• Claude Code CHANGELOG on GitHub (2.1.323 and 2.1.325)
• Claude Code Docs: Run tool calls from code with Code Mode
• Claude Code Docs: Plugin dependencies
• Claude Code Docs: Managed settings
• npm: @anthropic-ai/claude-code release history