Claude Code Code Mode: what it is and how to turn it on
On this page
- What Code Mode is
- When Code Mode helps
- Code Mode requirements
- How to turn on Code Mode
- Turn off Code Mode
- Resume a Code Mode session
- Code Mode limitations
- Permission checks in Code Mode
- Long-running code: ten minutes or two hours
- If you use hooks
- More pushes, more CI minutes
- Code Mode doesn't start
- Publish the pages Claude Code writes with Convika
- Frequently asked questions
- Sources (read on November 18, 2026)
Code Mode is an experimental Claude Code feature in which Claude writes JavaScript that makes several tool calls in one step, instead of asking for Bash, Read, or Edit one call at a time. Turn it on by starting claude with the environment variable CLAUDE_CODE_EXPERIMENTAL_CODE_MODE set to 1. It runs on Claude Code v2.1.323 or later, in an interactive terminal session, with Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.2.
You saw Code Mode in the docs or the release notes and you use Claude Code in a terminal every day. This guide tells you what changes when it's on, whether your setup can run it, the 5 steps to turn it on, and the fix for each reason Claude Code gives when it starts without it. It also covers what changes after that: permission checks and time limits. A long run that pushes as it goes starts CI on every push, so it covers the CI bill too, and Skipbox, the flat-price GitHub Actions runner. Every fact here is from Anthropic's page Run tool calls from code with Code Mode, read on November 18, 2026. That page calls Code Mode “experimental and off by default” and says it “may change or be removed in any release.” The steps also show what the screen said when Code Mode was turned on that day on a Mac, with Claude Code v2.1.327 and Fable 5.2.
What Code Mode is
Code Mode changes how Claude uses its tools. Without it, Claude asks for a tool call such as Bash, Read, or Edit, reads the result, and then decides what to do next. With it, Claude writes a piece of JavaScript that makes the tool calls, and Claude Code runs that code in your session.
You still describe the task in a prompt. What changes is how much one step can do. The docs name 3 things one piece of code can do:
- Run commands in parallel
- Use one result in the next call
- Return only the part of the output that Claude needs to read
The docs show the code Claude might write when you ask it to raise a retry limit:
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() });
Line by line:
- Line 1 runs
rgto list the files undersrcthat containfunction retryPolicy. - Line 2 takes the first file from that list.
- Line 3 edits that file, replacing
maxAttempts: 3withmaxAttempts: 5. - Line 4 runs the tests and returns the edited file's path and the test output to Claude.
With ordinary tool calls, Claude reads a result after the search, after the edit, and after the tests. Here line 2 hands the search result straight to line 3, and Claude reads what the last line returns.
In the conversation you see the tool calls, such as the edit's diff, and not the code. To read the code, press Ctrl+O to open the transcript viewer. Each piece of code is there as a collapsed Code row.
When Code Mode helps
The docs say to try Code Mode on tasks that take many related tool calls, and list 3 kinds:
- 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
The first is the same config value rewritten in 40 files, or one fix applied to every HTML page of a site. The second is a search that returns hundreds of lines when Claude needs a handful of them. The third is lint, typecheck, and tests, none of which waits on another.
Code Mode requirements
Your setup has to meet every row (read on November 18, 2026).
| Requirement | What you need |
|---|---|
| Version | Claude Code v2.1.323 or later, on either release channel (stable or latest) |
| Account | A Claude subscription or a Console account |
| Routes that don't work | A gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, Claude Models on Google Cloud (Anthropic managed) |
| Organization | No HIPAA configuration and no zero data retention |
| Model | Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.2 |
| Surface | An interactive claude session in a terminal. Not -p, the Agent SDK, the VS Code panel, the Desktop app, or cloud sessions |
| Agent teams | v2.1.326 or later to use Code Mode with agent teams on |
| Installation | The native build of Claude Code |
| Windows | Git for Windows installed |
With agent teams on, teammates run in Code Mode in the default in-process display mode and start without it in split panes. Claude Code and Codex subagents covers how agent teams differ from subagents.
Some settings also stop Code Mode from starting. The docs name an API key helper, OpenTelemetry export, and DISABLE_TELEMETRY. The line Claude Code prints at startup names the cause, and the table below has the fix for each.
How to turn on Code Mode
1. Check your version
Run claude --version. If the version is older than v2.1.323, run claude update. If you're on the stable channel and the update doesn't reach v2.1.323, wait for stable to catch up or switch to latest.
2. Start Claude Code with the variable set to 1
Set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to 1 in one of 3 places. To try Code Mode once, set it in your shell.
On macOS, Linux, or WSL:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
In Windows PowerShell:
$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude
To turn on Code Mode for every new session, save this env block in ~/.claude/settings.json and start claude:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
Put it in your user settings, ~/.claude/settings.json. Claude Code ignores this variable in a project's settings files, so a repository you clone can't turn on Code Mode for you.
3. Confirm at the prompt
Claude Code asks you to confirm before your first Code Mode session. On v2.1.327 the screen is titled “Code Mode (experimental)” and has 2 options, No, start without it and Yes, turn on Code Mode. No is selected first, so press Down, then Enter. Pressing Enter alone starts Claude Code without Code Mode.
Select Yes, turn on Code Mode. Claude Code restarts and shows this line near the top of the session:
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
The confirmation appears once: the second launch went straight to this line. A different line, or no line, means Code Mode didn't start: go to Code Mode doesn't start.
4. Give Claude a task with many tool calls
In a project you know, send a prompt that takes many tool calls. The docs use this one:
Read every Markdown file in this project and list the links that point to local files that don't exist.
Run in a folder of 3 Markdown files with 7 local links, 4 of them broken, the conversation showed one line while Claude worked:
Searching for 1 pattern, reading 3 files, running 7 shell commands…
It became Searched for 1 pattern, read 3 files, ran 7 shell commands when the work was done. The answer, a table of the 4 broken links, took 25 seconds on the first run and 17 on the second.
5. Read the code Claude wrote
Press Ctrl+O and expand a Code row to see the JavaScript behind the tool calls. Press Ctrl+O again to return to the conversation.
For the run in step 4, the transcript viewer opened with this Code row:
⏺ Code(const files = (await $`find . -type f \( -iname '…) · 30 lines (click to show)
One 30-line piece of code made all 11 tool calls. They sit under the row, each under its usual tool name: 1 Bash find for the Markdown files, a Read for each of the 3 files, and 7 Bash test -e checks, one per link.
Turn off Code Mode
Remove CLAUDE_CODE_EXPERIMENTAL_CODE_MODE from your shell and from ~/.claude/settings.json, then start a new session.
You can also keep the variable and change its value to 0 in either place. A 0 wins: with a 0 in one place, Code Mode stays off even if the other place says 1. When you set 1 and no Code Mode line appears, look for a leftover 0 first.
Resume a Code Mode session
Keep CLAUDE_CODE_EXPERIMENTAL_CODE_MODE set to 1 when you run claude --continue or claude --resume. With Code Mode off, Claude Code refuses to resume a Code Mode session. You resume it in the terminal only.
It holds the other way too. A session you started without Code Mode resumes without Code Mode, even with the variable set.
Code Mode limitations
The docs list the limits to accept before you turn it on:
- Resuming. You resume a Code Mode session only in the terminal, with Code Mode on.
- Auto mode. Auto mode's classifier reviews the code, not each tool call.
- Long-running code. Unless code can run in the background, you wait for it to finish, and it stops after ten minutes.
- Hooks. A tool call is refused when a
PreToolUsehook can't run or times out, and aUserPromptSubmithook can block code output. - Unavailable features. Remote Control, Claude in Chrome, and computer use don't work.
- Moving the session. You can't move the session to the Desktop app or turn it into a background session, and
/forkcan't start a background copy.
How much the auto mode, long-running code, and hooks limits affect you depends on your permission mode and your hooks. The next 3 sections take them in turn.
Permission checks in Code Mode
Your permission rules still apply. Each tool call in the code goes through your deny and ask permission rules and your PreToolUse hooks under the tool's usual name, such as Bash. Beyond that, your permission mode decides how the code is checked:
| Permission mode | How the code is checked |
|---|---|
| Auto mode | The classifier reviews each piece of code before it runs, not each tool call |
| Other permission modes | The code starts without a review, and you're prompted for each tool call that would prompt you in that mode |
Auto mode's classifier reads the code before it runs, so it doesn't see values computed at run time, such as a path taken from search output. The docs' advice: keep rules or hooks for the calls you must control. To pick a safe place for bypassPermissions, see how to run --dangerously-skip-permissions safely.
Long-running code: ten minutes or two hours
While code runs a long build or test, Claude either waits for it or lets it continue in the background.
| Waiting | Background | |
|---|---|---|
| Talking to Claude | Claude answers after the code finishes | You keep talking to Claude while the code runs |
| Time limit | The code stops after ten minutes, including time you spend at permission prompts | The code runs for up to two hours |
For background code, start your session in auto or bypassPermissions mode. If Claude still waits, the cause is one of these:
- You switched to another mode. Press
Shift+Tabuntil you're back in the mode you started in. - You started in another mode, or picked the session from the
claude --resumelist. If auto mode is available to you, exit, then runclaude --continue --permission-mode autowith Code Mode on. - You passed tool names to
--tools. Start again in auto mode without that flag.
If you use hooks
A PreToolUse hook that allows or blocks shell commands sees commands in a new shape. In Code Mode, a git push in a folder named app can reach your hook as cd 'app' && git push, so the hook has to check each part of a command. To check the code itself, write a PreToolUse hook that matches REPL, the tool that runs the code, and read the JavaScript from tool_input.code.
A hook that gives no decision now refuses the call. On a call from code, a hook that fails gets the call refused with the hook failed, and one that times out with the hook did not finish, even when onFailure is unset. When code can run in the background, UserPromptSubmit hooks also run on code output: change the hook so that it doesn't block when source in its input is poll_event.
Skipbox's guide Claude Code's Code Mode in a team: hooks, permissions, long-running code and managed settings has the hook rewrites, the permission prompt with a countdown that auto mode shows, and the managed setting that blocks Code Mode for a whole organization. For the basics of blocking a command with PreToolUse, read Claude Code hooks: how to block a command before it runs.
More pushes, more CI minutes
In the background, Code Mode's code keeps going for up to two hours. While it runs, a session that commits and pushes as it goes starts the repository's CI on every push, so your CI minutes grow with the number of pushes in that run. Code Mode itself doesn't work with -p, the non-interactive mode, or with the Agent SDK, which the Claude Code GitHub Action is built on, so it never runs inside GitHub Actions. CI runs when your terminal session pushes.
GitHub bills its hosted runners by the minute. A standard Linux runner (2-core) costs $0.006 a minute in a private repository, and each job rounds up to a whole minute. A 10-minute CI run started 30 times a day is 300 minutes, or $1.80 a day and $36 over 20 working days, billed once your plan's included usage is spent.
GitHub bills nothing for a self-hosted runner's minutes. Skipbox is that runner at a flat price: $39 a month for the 4 vCPU plan, with unlimited minutes. However many times the agent pushes, the bill stays the same. It runs jobs from public and private repositories, for organizations and personal accounts. A job moves with one line:
jobs:
test:
runs-on: skipbox
Start on the free trial. The Skipbox trial runs up to 4 jobs at once, each on its own 4 vCPU VM (how many is based on how many jobs you run at once on GitHub Actions), for 7 days or 3,000 job-minutes from your first job, whichever comes first, and takes no card. To go back, change the line back.
Start a free Skipbox trial on skipbox.dev
Code Mode doesn't start
Code Mode (experimental) isn't available near the top of the session means that Claude Code started without Code Mode. The reason follows on the same line, and /status shows it too. Find the reason in this table, make the change, and start a new session (read on November 18, 2026).
| Reason includes | What to do |
|---|---|
it isn't open to your account in this version or it isn't open to your account yet | If your version is older than v2.1.323, update. Otherwise, check your network connection and start again. If the reason stays, try again another day |
it only works directly with the Anthropic API or it only works with the Anthropic API | Remove the settings that route 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 with --model opus. Haiku 5.5 and Fable 5.2 also work |
it doesn't work in background jobs | Start in the foreground, without --remote-control. If the reason shows in a teammate's split pane, use the in-process display mode to run teammates in Code Mode |
it needs settings that Claude Code downloads from Anthropic | Unset the variable that turns off feature-flag fetching, such as DISABLE_TELEMETRY |
OpenTelemetry is on | Unset CLAUDE_CODE_ENABLE_TELEMETRY and ENABLE_BETA_TRACING_DETAILED if you can work without OpenTelemetry export |
it doesn't yet work with the plugin | In a session, run /plugin and disable each plugin that the reason names. If your organization turned one on, ask your administrator to turn it off |
it doesn't yet work with an installed mod | Turn off the mod that checks tool calls |
it can't be used together with agent teams yet | To keep agent teams on, update Claude Code to v2.1.326 or later. To stay on your version, unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS |
this launch's tool options | Start without --restricted, add REPL to --tools, and remove REPL from --disallowedTools and your deny rules |
couldn't save your answer | Make ~/.claude.json writable |
your organization's settings don't allow it | Ask your administrator about the managed setting |
For a reason that isn't in the table, check the requirements.
If you see no line about Code Mode at all, run claude --version and update if your version is older than v2.1.323. Then check that CLAUDE_CODE_EXPERIMENTAL_CODE_MODE is 1 in your shell or user settings, and remove any 0 from those and from any --settings file.
Publish the pages Claude Code writes with Convika
One more tool for the same session. A site's HTML pages are the plainest case of a change that repeats across many files: move one link in the header and every page changes. When the pages are written, Convika is where they go live. It hosts the HTML Claude Code writes, and Claude Code reaches it over MCP:
claude mcp add --transport http convika https://mcp.convika.com
Run /mcp inside Claude Code and sign in to Convika in your browser. Then tell Claude Code: “Save the HTML in this folder to Convika and give me the preview link.” Convika's create_landing_page_preview tool saves the page and returns a private preview link, which expires after 1 hour. Its create_pages tool makes several pages as drafts in one call. Say “publish” after you've looked at the preview and the page goes live at its URL. From then on you read page views and form entries in the same Claude Code conversation.
Publish a page from Claude Code walks through the connection, forms, and a custom domain. To turn the publish steps into a skill that runs the same way every time, see Claude Code and Codex skills.
Frequently asked questions
What is Code Mode in Claude Code?
Code Mode is an experimental feature in which Claude writes JavaScript that makes several tool calls in one step, and Claude Code runs that code in your session. Without it, Claude asks for each tool call and reads each result before the next. One piece of code can run commands in parallel, use one result in the next call, and return only the output Claude needs. It is off by default.
How do I enable Code Mode in Claude Code?
Set the environment variable CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to 1 and start claude. On macOS, Linux, or WSL, run CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude. To have it on in every new session, put the variable in the env block of ~/.claude/settings.json. Claude Code asks you to confirm before your first Code Mode session: select Yes, turn on Code Mode.
Which Claude Code version and models support Code Mode?
Claude Code v2.1.323 or later, with Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.2 (read on November 18, 2026). With agent teams on, you need v2.1.326 or later.
Does Code Mode work in VS Code or the Desktop app?
No. Code Mode runs in 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.
Does Code Mode work with Amazon Bedrock or a gateway?
No. Code Mode needs a Claude subscription or a Console account. It doesn't work through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Models on Google Cloud (Anthropic managed). If the startup reason includes it only works directly with the Anthropic API, remove the settings that route requests through a cloud provider, a gateway, or a custom ANTHROPIC_BASE_URL.
Why can't I resume my Code Mode session?
Code Mode is off in the shell you're resuming from. Keep CLAUDE_CODE_EXPERIMENTAL_CODE_MODE set to 1 and run claude --continue or claude --resume in a terminal.
How do I turn off Code Mode?
Remove CLAUDE_CODE_EXPERIMENTAL_CODE_MODE from your shell and from ~/.claude/settings.json, then start a new session. Setting the value to 0 in either place also turns it off, and a 0 in one place beats a 1 in the other.
Where can I see the JavaScript Claude wrote?
In the transcript viewer. Press Ctrl+O and expand a Code row. The conversation itself shows the tool calls, such as an edit's diff, and not the code.
How long can Code Mode code run?
Ten minutes while Claude waits for it, including the time you spend at permission prompts. In a session started in auto or bypassPermissions mode the code can run in the background, for up to two hours.
Does Code Mode raise my GitHub Actions bill?
Code Mode itself never runs inside GitHub Actions. Each push from a long session starts CI, though, and GitHub bills its hosted runners by the job-minute: $0.006 a minute for a standard Linux runner in a private repository. Skipbox is a flat $39 a month for the 4 vCPU plan with unlimited minutes, and its trial is free for 7 days or 3,000 job-minutes from your first job, whichever comes first, with no card.
Sources (read on November 18, 2026)
Related articles
- Claude Code pricing (November 2026): every plan and costClaude Code costs $20 a month on Pro, $100 on Max, $200 on Ultra, or API rates per token. Limits, usage credits, Team and Enterprise seats, and the CI bill agents add.
- Is agy -p in Claude Code or Codex against Antigravity terms?Google's FAQ says agy -p is for your own scripts and CI, and wrapping it in Claude Code, Codex, or an MCP server isn't supported on consumer plans. What's allowed, the 403 appeal, and agy in CI.
- AI coding agents and your CI bill: the GitHub Actions mathCoding agents open more pull requests and every push runs CI. The per-minute arithmetic at 10, 30, and 100 pull requests a day, the fixes, and a flat price.