Skillforge Field notes on shipping with AI tools

Claude Code Code Mode: Turn It On, Off, or Block It

· Updated November 22, 2026 claude-codepermissions

Code Mode is an experimental, off-by-default way of running Claude Code. Instead of asking for one Read, Edit or Bash call at a time and reading each result, Claude writes a piece of JavaScript that makes several tool calls, and Claude Code runs that code in your session. This page covers what it changes, how to turn it on, off, or block it for a team, and the parts that affect permissions and hooks.

Verified against: the Code Mode docs page, the environment variables page, the hooks reference and the GitHub changelog (2.1.323 added Code Mode, 2.1.325 fixes), fetched on 2026-11-14 and re-fetched on 2026-11-22 (changelog through 2.1.330; Code Mode page and hooks reference re-read). This is documentation reading, not a live run: Code Mode does not work in cloud sessions or with -p, and we had no interactive terminal session, so every behavior below is as documented, not observed. Anthropic says it may change or be removed in any release.

What it does

Per the docs, one piece of code can run commands in parallel, use one result in the next call, and return only the part of the output Claude needs to read. You still see the tool calls (an edit's diff, for example) in the conversation, not the code. Press Ctrl+O to open the transcript viewer, where each piece of code shows as a collapsed Code row.

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

Requirements

All from the docs page:

  • Claude Code v2.1.323 or later, on either release channel. As of today stable on npm is 2.1.311, so a stable install does not have it yet.
  • A Claude subscription or Console account. Not through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform or Microsoft Foundry.
  • An organization not using 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, on the native build. Not -p, the Agent SDK, the VS Code panel, the Desktop app or cloud sessions.
  • On Windows, Git for Windows.

It also refuses to start with some settings on, such as an API key helper. Four older blockers have changed since our first version of this page:

  • Agent teams: from v2.1.326 you can use both. The docs say teammates run in Code Mode in the default in-process display mode and start without it in split panes.
  • OpenTelemetry: the 2.1.329 changelog says Code Mode now starts with OpenTelemetry events and metrics on (each tool call the code makes sends its events), while tracing still keeps it off. The Code Mode page's troubleshooting table still lists an OpenTelemetry is on reason that says to unset CLAUDE_CODE_ENABLE_TELEMETRY, so the docs and the changelog disagree on events and metrics. Treat the changelog as the newer source and test before relying on it.
  • Telemetry and feature flags off: the 2.1.329 changelog says Code Mode now also starts when telemetry, nonessential traffic or feature flags are turned off. The docs table still shows DISABLE_TELEMETRY under it needs settings that Claude Code downloads from Anthropic. Same disagreement, same advice.
  • Mods: the 2.1.327 changelog says an installed mod that hooks tool calls no longer stops Code Mode from starting, and a 2.1.329 entry says a mod that lists only some tools no longer silently turns it off. The docs table still has an it doesn't yet work with an installed mod row.

If it does not start, the session shows Code Mode (experimental) isn't available with the reason on the same line, and /status shows it too.

Turn it on

Set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to 1:

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

To turn it on for every session, put it in ~/.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 cannot switch it on for you. The first time, it asks you to confirm and restarts, then shows Code Mode (experimental) is on · this session can be resumed only with Code Mode on.

That last clause matters: a Code Mode session resumes only in the terminal with the variable still set to 1. With it off, Claude Code refuses to resume. Sessions you started without Code Mode resume without it even when the variable is set.

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 in either place. A 0 in one place wins over a 1 in the other.

To block it for everyone, put the same variable with 0 in your managed settings:

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

Per the docs, people already in a Code Mode session stay in it until they exit or restart, then start without it and cannot resume their Code Mode sessions while the 0 is in place. You cannot turn Code Mode on for users from managed settings, only block it.

Permissions and hooks

Each tool call the code makes still goes through your deny and ask permission rules and your PreToolUse hooks. What changes is the extra review layer:

  • Auto mode: the classifier reviews each piece of code before it runs, not each tool call. The docs say it does not see values computed at run time, such as a path taken from search output, so keep rules or hooks for calls you must control.
  • Other modes: the code starts without a review, and you are prompted for each call that would prompt you in that mode.

The docs also give two hook behaviors worth knowing before you enable it:

  • Hook failures changed in 2.1.329. Our first version of this page said a PreToolUse hook that fails refuses the call by default. That is now only true before 2.1.329. The docs and the changelog now agree: on v2.1.329 or later, a call from code runs by default after a hook failure (it could not start, was killed, exited with 126, 127 or above 128, or returned an HTTP error or invalid output), as it does outside Code Mode. A hook that times out, or an agent hook that ends without a decision, still refuses the call with the hook did not finish. If a check must refuse the call when it fails, use a command, http or mcp_tool hook and set "onFailure": "block" (the changelog names those three; the Code Mode page names command and http). This is the same fail-open default as everywhere else, which our onFailure article covers. If you wrote a security hook against the older behavior, re-read it.
  • To inspect the code itself, the Code Mode page says to match a PreToolUse hook on REPL and read tool_input.code. We could not confirm that: the string REPL does not appear in the tools reference we fetched, so treat it as a single-source claim and test it before relying on it.

Code that runs long either blocks until it finishes (stopping after ten minutes, including time at permission prompts) or continues in the background for up to two hours. The docs say to start in auto or bypassPermissions mode for background code.

Limits to accept

From the docs: no Remote Control, Claude in Chrome or computer use; you cannot move the session to the Desktop app or make it a background session; and /fork cannot start a background copy.

What changed after 2.1.325

The 2.1.326 to 2.1.330 changelogs list more Code Mode work than we can summarize here: a limit on runaway loops that filled memory, memory fixes for large file reads and woken subagents, scripts that wait up to ten minutes on an MCP call instead of getting a "moved to the background" message as data, a refusal of reads over 256 MiB, and the built-in chart tool working in Code Mode. Changelog only, none of it run by us.

What 2.1.325 fixed

The latest changelog lists Code Mode fixes for scripts ignoring a worktree entered with EnterWorktree, scripts writing ~ paths into the project, /mcp showing a server as connected after its sign-in expired, and Claude starting work by itself when you resumed a session that ended mid-script. Those are signs of an early feature. If you try it, do so on a throwaway branch.

FAQ

Is Code Mode on by default? No. It is opt-in and the docs call it experimental.

Can I use it with claude -p in a scheduled job? No. The docs list -p and the Agent SDK as unsupported.

Can my repo turn it on for teammates? No. The variable is ignored in project settings files.

How do I make sure my team never uses it? Set the variable to 0 in managed settings.

How do I see what Claude ran? Ctrl+O, then expand a Code row.