DIRTY STATIC / DISPATCH Tutorials16 NOV 2026 • 13 MIN READ
A concrete terminal hall where many small tool icons merge into one script stream, with caution yellow hazard stripes on the floor
TutorialsINTELLIGENCE FOR THE MACHINE AGE

Batch Tool Calls With Claude Code Mode

Code Mode is an experimental option in Claude Code where Claude writes JavaScript that calls its tools, instead of asking for one tool at a time and reading each result before it moves on. This tutorial turns it on for one session, runs a first task that only reads and filters, reads the script before trusting an edit, and covers the limits on accounts, models, surfaces, permissions, and time.

Start reading ↓

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.

A desk in a concrete workspace with a terminal screen showing a script that fans out to many files 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.

Terminal

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.

macOS, Linux and WSL

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.

Claude Code session

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.

Robot arms waiting at a concrete permission gate while files wait behind hazard stripes 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

ProblemLikely causeFix
Code Mode does not start and the reason says it is not open to your account yetVersion is older than v2.1.323, or the account has not been opened to the feature yetUpdate 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 APISettings route requests through a cloud provider, a gateway, or a custom base URLRemove those routing settings, then sign in with a Claude subscription or Console account and start again
The reason mentions an API key helperAn API key helper, an auth token, or a custom auth header is setRemove 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 modelsThe session started on a model outside the supported listStart 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 settingsTelemetry is off, OpenTelemetry export is on, or agent teams are onUnset the variables the reason names, if you can work without those features, and start a new session
A tool call is refused by a hookA PreToolUse hook failed, timed out, or gave no decision on a call from codeAsk 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 resultA UserPromptSubmit hook blocked output from code that runs in the backgroundChange the hook so it does not block when the source in its input is poll_event
A prompt shows a countdown in auto modeNew code started while earlier code still ran, so the earlier code lost its classifier reviewAnswer 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 resumeYou are trying to resume a Code Mode session without Code Mode, or outside a terminalStart 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.

CONTINUE THE DESCENT

MORE FROM DIRTY STATIC ↘