A normal Claude Code session spends a lot of turns on small steps. Claude reads a file, waits, runs a command, waits again, edits a file, and reads that result too. Code Mode changes the shape of that work. Claude writes a piece of JavaScript that makes the tool calls, and Claude Code runs that code in your session.
Anthropic added Code Mode in Claude Code v2.1.323 on November 12, 2026, and the documentation calls it experimental and off by default. That label matters. The feature may change or be removed in any release, the docs give no token saving figure for it, and a session started with it can only be resumed with it still on. Try it on work you can check, not on work you cannot afford to redo.
This tutorial follows the official Claude Code documentation page for Code Mode, checked on November 16, 2026. It claims no run of its own. The order is deliberate. Check the version and the account first, turn the mode on for one session only, start with a task that only reads, and read the script before you let a script edit files for you.
What You Will Build or Learn
You will turn on Code Mode for one terminal session and use it the way Anthropic recommends. That means a task that takes many related tool calls, such as a change that repeats across many files, a search whose results need filtering before Claude reads them, or several commands that can run at the same time.
You will also learn what does not change. Each tool call that the code makes still goes through your deny and ask permission rules and your PreToolUse hooks. What changes is the unit you review. In auto mode, the classifier reviews each piece of code before it runs, not each tool call inside it, and it does not see values that the code works out while it runs.
One script can hold the calls that used to take many turns. Illustration: Dirty Static
Before You Begin
Work in a Git repository and start from a state you can measure. Commit or stash your current work, run git status, and note the result. If a script later changes a file you did not expect, that first record is how you will know.
Know the time limits before a long job starts. Code that Claude waits for stops after ten minutes, and that time includes time spent at permission prompts. Code that can run in the background can run for up to two hours. Background code needs a session started in auto mode or bypassPermissions mode, per the docs.
Remote Control, Claude in Chrome, and computer use do not work while Code Mode is on. You also cannot move a Code Mode session to the Desktop app or turn it into a background session, and the fork command cannot start a background copy of it. Plan for a session that stays in the terminal where it started. For wider context on keeping agent work bounded, see our guide to stopping Claude Code from leaking secrets to GitHub.
Step 1: Check the Version and the Surface
Action: check your version in a terminal, and confirm that you will work in an interactive terminal session on the native build.
claude --version
Expected result: the version is v2.1.323 or later. If it is older, update Claude Code first and check again. An older version starts without Code Mode, with or without a reason that says it is not open to your account yet. If you plan to use the VS Code panel, the Desktop app, a cloud session, the Agent SDK, or the print flag for this work, stop here. Code Mode will not start on those surfaces.
Step 2: Turn Code Mode On for One Session
Action: set the environment variable in your shell and start Claude Code. This form turns the mode on for this launch only, which is the right scope for a first try.
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
Expected result: Claude Code asks you to confirm before the first Code Mode session, then restarts with a line near the top that says Code Mode is on and that the session can be resumed only with Code Mode on. If you see a line that says Code Mode is not available, read the reason on that same line and use the Troubleshooting table below. The status command inside the session shows the reason too.
Step 3: Make the Setting Last, Only If the First Try Earns It
Action: if you want Code Mode in every new session, add the variable to the env block of your user settings file at ~/.claude/settings.json. Do not put the switch in a project settings file and expect it to work. The docs treat this as a user choice, and a cloned repository should not be able to turn it on for you.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
Expected result: new terminal sessions start with the same confirmation flow and the same banner. Keep one fact in mind when you debug this setting. A value of 0 in one place keeps Code Mode off even if another place sets 1. That rule also lets an organization block the mode for everyone through managed settings, and managed settings cannot turn it on for users.
Step 4: Run a First Task That Only Reads
Action: give Claude a search task whose results need filtering, and ask for a short return value. Change the word and the folder to match a search you actually need, and keep the task to reading and reporting.
Find every file under src that mentions retryPolicy. Return only the file paths and, for each path, the line that sets the retry limit. Do not edit any file.
Expected result: Claude writes JavaScript that makes the calls, runs the search, and returns the part of the output it needs to read. In the conversation you see the tool calls, such as a search result or a file read, and not the code. One piece of code can run commands in parallel, use one result in the next call, and return a filtered result instead of every raw result in full.
The gate still exists. Each call still passes your rules and hooks. Illustration: Dirty Static
Step 5: Read the Script Before You Trust an Edit
Action: press Ctrl+O to open the transcript viewer. Each piece of code appears there as a collapsed Code row, with a hint for how to expand it. Read the script in full and check three things. The files it touches match your task. The commands match the work you asked for. The last part of the script returns only what Claude needs to read next.
Expected result: you can explain what the script will do before it does more work. If you cannot, do not move to an edit task yet. Ask Claude for the error text or the script text in plain form, fix the prompt, and start the task again.
Step 6: Run a Small Edit Task on a Branch
Action: move to a branch you can discard, then give Claude the kind of task the docs use as their example. The docs show Claude raising a retry limit. In that example, the script finds the file that holds the retry policy, edits the limit in that file, runs the tests for that policy, and returns the file path and the test output.
The script in the docs example takes this shape. This is the code Claude might write for that prompt, shown so you know what to look for in the transcript viewer. It is not a command to paste and run on its own.
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() });
Give the task in your own words, with your own limit and your own test command, and watch the permission prompts as they come. In modes that ask, you are prompted for each tool call that would prompt you in that mode. In auto mode, the classifier reviews the code first, so keep deny rules or hooks for calls you must control, because the classifier does not see values worked out while the code runs.
Expected result: the conversation shows the tool calls the script made, such as the diff of the edit, and the script returns the edited path and the test output. The code itself stays in the transcript viewer, not in the main conversation.
Step 7: Turn Code Mode Off and Note the Resume Rule
Action: to turn the mode off, 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.
Expected result: new sessions start without Code Mode. A Code Mode session can be resumed only in the terminal, with Code Mode on. If you try to resume it with the mode off, start a fresh session instead and carry the task over in your prompt, with the diff and the test results from the work so far.
Verification
Check four things and record the results. The banner at the start of the session said Code Mode was on. The first task changed no files, which git status confirms against the record you took before you began. The transcript viewer held the script as a Code row, and you read it before the edit task ran. The edit task returned the path it changed and the test output it claimed, and the diff and a fresh test run agree with that return.
Finish with the diff. Run git diff and name each file it lists against the task you gave. A clean summary from Claude is not proof. The diff, the status output, and the tests are the proof you can check yourself.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Code Mode does not start and the reason says it is not open to your account yet | Version is older than v2.1.323, or the account has not been opened to the feature yet | Update Claude Code, check your network connection, and start again. If the reason stays, try again another day |
| The reason says it only works with the Anthropic API | Settings route requests through a cloud provider, a gateway, or a custom base URL | Remove those routing settings, then sign in with a Claude subscription or Console account and start again |
| The reason mentions an API key helper | An API key helper, an auth token, or a custom auth header is set | Remove the helper and the named settings, then sign in or set your API key in the way the docs name, and start again |
| The reason says it only works with supported models | The session started on a model outside the supported list | Start with a supported model, for example with the model flag set to opus. Haiku 5.5 and Fable 5.2 also work |
| The reason mentions telemetry or feature settings | Telemetry is off, OpenTelemetry export is on, or agent teams are on | Unset the variables the reason names, if you can work without those features, and start a new session |
| A tool call is refused by a hook | A PreToolUse hook failed, timed out, or gave no decision on a call from code | Ask Claude for the error text, fix the hook, or raise the hook timeout. To let calls go ahead when a hook fails, set onFailure to continue on that hook |
| Code output is blocked where you expected a result | A UserPromptSubmit hook blocked output from code that runs in the background | Change the hook so it does not block when the source in its input is poll_event |
| A prompt shows a countdown in auto mode | New code started while earlier code still ran, so the earlier code lost its classifier review | Answer before the countdown ends. With no answer, that call is refused, and later calls that would show a countdown are refused without a prompt |
| A session will not resume | You are trying to resume a Code Mode session without Code Mode, or outside a terminal | Start in a terminal with Code Mode on, or start a fresh session and carry the task over |
Next Steps
Use Code Mode where the shape fits and skip it where it does not. A change that repeats across many files, a search that needs filtering, and a set of commands that can run at the same time are the tasks Anthropic names. A task with one or two calls gains little, and a task you need to watch call by call is better run in the normal mode.
Ignore the token saving number you will see shared for this feature until Anthropic publishes one for Code Mode itself. The docs for Code Mode give no such figure. The figure in wide circulation comes from a 2025 Anthropic article about a related API feature, and a number for one surface is not a promise for another. Measure your own sessions on your own tasks, and keep the mode only if the work stays easy to read, easy to check, and easy to undo.
Sources
- Anthropic, Claude Code documentation, Run tool calls from code with Code Mode, code.claude.com/docs/en/code-mode, checked November 16, 2026. The source for how Code Mode works, the example script shape, the requirements, the turn on and turn off steps, the permission rules, the time limits, and the troubleshooting reasons.
- Anthropic, Claude Code changelog, version 2.1.323, November 12, 2026, via code.claude.com. The source for the release date and the description of Code Mode as an experimental option where Claude writes JavaScript to call its tools.
- Anthropic, Introducing advanced tool use on the Claude Developer Platform, November 24, 2025, anthropic.com. Background only, for the related API work on calling tools from code. This tutorial does not use its token figures as figures for Code Mode in Claude Code.
- Image credit: all images in this article are Dirty Static illustrations.
END OF TRANSMISSION
Stay curious. Question everything.


