Blog · November 14, 2026 · 9 min read · by Vilva Athiban P B

Claude Code Code Mode Explained: Claude Writes JavaScript to Call Tools — Requirements, Limits, Permissions, Hooks and What It Means for Unattended Runs

On 13 November the Code Mode docs page returned a 404 and our 2.1.323 digest had one changelog sentence to go on. On 14 November 2026 the page at code.claude.com/docs/en/code-mode exists, and 2.1.325 is out. This post reads both for people who leave Claude Code running unwatched. Quotes are the docs’ words.

1. What Code Mode is, in the docs’ words

“An experimental feature in which Claude writes JavaScript that makes several tool calls in one step.” Without it, “Claude asks for tool calls such as Bash, Read, or Edit directly and reads each result before it decides what to do next”. With it, one piece of code “can run commands in parallel, use one result in the next call, and return the part of the output that Claude needs to read”. It is “off by default” and “may change or be removed in any release”. The docs’ example, for a prompt asking Claude 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() });

Four lines find the file, edit it, run the tests and return the path and test output to Claude.

2. How it works: you see tool calls, not code

“In the conversation, you see the tool calls, such as the edit’s diff, and not the code.” To read the JavaScript, press Ctrl+O for the transcript viewer, where each piece appears “as a collapsed Code row”. The tool that runs the code is called REPL; that matters for hooks later.

3. When the docs say to try it

  • “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”

4. The limitations, point by point

  • Resuming: “only in the terminal, with Code Mode on”. With it off, “Claude Code refuses to resume the session”.
  • Auto mode: the classifier “reviews the code, not each tool call”.
  • Long-running code: unless it runs in the background, “you wait for it to finish, and it stops after ten minutes”.
  • Hooks: “tool calls refused when a PreToolUse hook can’t run or times out” and “code output blocked by a UserPromptSubmit hook”.
  • Unavailable: Remote Control, Claude in Chrome and computer use.
  • Moving the session: no move to the Desktop app, no background session, and /fork “can’t start a background copy”.

5. Requirements

  • Version: “Claude Code v2.1.323 or later, on either release channel”.
  • Account: “a Claude subscription or Console account”, not “through a gateway, Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry”, and not an organization on the HIPAA configuration or 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. Code Mode doesn’t work with -p, the Agent SDK, the VS Code panel, the Desktop app, or cloud sessions”. The native build; on Windows, Git for Windows.
  • Settings that block it: “an API key helper, agent teams, OpenTelemetry export, or DISABLE_TELEMETRY”; the troubleshooting table adds a custom ANTHROPIC_BASE_URL, a mod that checks tool calls, --restricted, REPL in --disallowedTools or a deny rule, and --remote-control.

6. How to turn it on, off, and block it

There is no slash command. Set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE to 1 in your shell, or in the env block of ~/.claude/settings.json for every new session. Claude Code “ignores this variable in a project’s settings files, so a repository you clone can’t turn on Code Mode for you”.

# Check the version first; 2.1.323 or later is required.
claude --version

# One session with Code Mode on (macOS, Linux, WSL):
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

# Or, for every new session, in ~/.claude/settings.json:
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

Before the first session Claude Code asks you to confirm; select Yes, turn on Code Mode. It restarts and shows “Code Mode (experimental) is on · this session can be resumed only with Code Mode on”. If it says “Code Mode (experimental) isn’t available” instead, the reason follows on the same line and in /status; for “it isn’t open to your account yet” on a current version, check your network, start again and, if it stays, “try again another day”. To turn it off, remove the variable or set it to 0; a 0 in one place wins over a 1 in the other. An organization blocks it with a 0 in managed settings, and “can’t turn on Code Mode for your users from managed settings”.

7. Permission checks and hooks, in plain language

Each tool call the code makes still “goes through your deny and ask permission rules and your PreToolUse hooks”, with no change to matchers. In auto mode the classifier “reviews each piece of code before it runs, not each tool call”, and “doesn’t see values computed at run time, such as a path taken from search output, so keep rules or hooks for calls you must control”. In the other modes “you’re prompted for each tool call that would prompt you in that mode”. To inspect the code itself, write a PreToolUse hook matching REPL and read tool_input.code.

Two hook behaviours are new. A PreToolUse hook that “didn’t give a decision” refuses the call “even when onFailure is unset”: the hook failed means it could not start or returned invalid output; the hook did not finish means it timed out, “on a call from Claude’s code, or on any other tool call once Claude has run code in the session”. Raise the hook’s timeout or set "onFailure": "continue". And with background code, UserPromptSubmit hooks “also run on code output”; a blocking hook should skip input whose source is poll_event.

8. Long-running code

“Waiting: Claude answers after the code finishes, and the code stops after ten minutes, including time you spend at permission prompts.” “Background: you can keep talking to Claude, and the code can run for up to two hours.” Background needs a session started in auto or bypassPermissions mode without tool names in --tools; if Claude still waits, the docs list the fixes, down to claude --continue --permission-mode auto.

9. What it means for unattended runs

Today, very little, by design. Code Mode is interactive-terminal only, so a claude -p job, an SDK host, a cloud session and a Remote Control host are unaffected. Three things change for the interactive session you start and walk away from:

  • A ten-minute wait. In the modes that prompt, Claude waits on code for up to ten minutes, “including time you spend at permission prompts”. A run that looks hung may be code running.
  • A prompt with a countdown. When new code starts in auto mode while earlier code runs, the earlier code “loses its classifier review” and you are asked about its remaining calls: “Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session”. Miss it and that call is refused, and so are later calls that would show a countdown, until you send a message.
  • Hook refusals surface differently. A slow hook that used to pass now refuses the call, as an error Claude reports. Review the timeouts in your hooks first.

On notifications: the docs confirm tool calls still pass through permission rules and PreToolUse hooks, and that prompting modes still prompt, but say nothing about the Notification or Stop events. How a “done” or “needs permission” alert behaves in Code Mode is not documented yet; test it. See our waiting-for-input post and the auto mode guide.

10. Also new in 2.1.325

The 2.1.325 changelog fixes three Code Mode bugs, including “Claude starting work by itself when you resumed a session that ended during a Code Mode script; it now waits for your next prompt”. Beyond Code Mode, the lines that matter unattended:

  • “Changed scheduled tasks and /loop to ask before running a skill that declares allowed-tools or hooks; add Skill(name) to permissions.allow to run it unattended”.
  • “Fixed sessions on many third-party gateways and Foundry stopping with a context length error on every turn instead of compacting”.
  • “Fixed recent turns sometimes going missing from a resumed session after Claude Code stopped without a clean exit”.
  • “Added a line under the error shown when your organization’s policy blocks a request, saying how to continue: run /rewind and change the message, or run /clear”.

FAQ

Is Code Mode on by default?

No. It is “experimental and off by default”; you set CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 and confirm once.

Does Code Mode work with claude -p?

No. The docs require an interactive terminal session and name -p, the Agent SDK and cloud sessions as unsupported.

Can I use Code Mode in the Desktop app?

No, and you cannot move a Code Mode session to the Desktop app either.

Which models support it?

“Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, or Fable 5.2”, through a Claude subscription or Console account.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read

How to Audit MCP Tool Calls Made by Claude Code: A Five-Minute Hook Audit Log, OpenTelemetry Tool Events, and the Transcript for Investigations

9 min read

Exercise Snacks: What the Research Actually Says About One-Minute Vigorous Breaks, What It Does Not, and How NotchFit's Agent-Run Sets Compare

8 min read

How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

8 min read

Sitting Too Long as a Developer: The Posture Problems Coding Agents Made Worse, What the Research Says About Breaking Up Sitting, and How NotchFit Turns an Agent Run Into the Break

8 min read

Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

8 min read

Standing Desk Exercises for Developers: Why Standing Still Is Not the Goal, Eight Movements That Fit a Thirty-Second Agent Run, and How NotchFit Cues Them From the Notch

8 min read

The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

9 min read

Your First Week With NotchFit: Install and Simulate, Run Real Tasks, Write a Smaller Plan Than You Want, Tune the Alerts, Survive the First Skipped Day, and Decide What Stays

8 min read

How to Stop a Running Claude Code Task: Esc vs Ctrl+C, Background Tasks, Subagents, and Disconnecting Remote Control

8 min read

Pomodoro vs Agent-Driven Breaks: Timing Movement to Claude Code and Codex Runs Instead of a Timer

7 min read

Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

9 min read

The 20-20-20 Rule for Developers: Eye Strain, the Evidence, and Agent Runs as the Cue

8 min read

Claude Agent SDK + MCP Servers: mcpServers, allowedTools, Status Checks and Auth

9 min read

Discreet Desk Exercises for an Open-Plan Office While Claude Code Runs

7 min read

claude remote-control Server Mode: Run Claude Code as a Session Server

9 min read

Wrist and Forearm Stretches for Developers: A 60-Second Routine for Every Claude Code Run

7 min read

Claude Remote Control vs Claude Code on the Web: Which to Use and How They Differ

9 min read

Neck and Shoulder Stretches for Developers: A 90-Second Routine Between Agent Runs

7 min read

What Happens When You Step Away From a Claude Code Session: Prompt Cache Expiry, Idle Compaction, and When to Come Back

8 min read

Hip Flexor and Lower Back Stretches for Developers: A Two-Minute Standing Routine Between Agent Runs

7 min read

Claude Code's Monitor Tool: Watch Logs, CI Runs and PRs (Even a WebSocket) and Let Claude React While You Keep Working

7 min read

Hunched Over the Keyboard? Upper-Back (Thoracic) Stretches for Developers: A Two-Minute Seated Routine Between Agent Runs

6 min read

Claude Code Ultrareview: The 15–25 Minute Cloud Review, What to Do While It Runs, and How the Findings Come Back

8 min read

Why Your Legs Go Dead After a Long Claude Code Session: A Two-Minute Standing Calf, Glute and Hamstring Routine Between Agent Runs

7 min read

claude --teleport: Pull a Cloud Session Into Your Terminal, Start One With --cloud, Send Follow-Ups From the CLI, and the Requirements That Trip People Up

8 min read

Rounded Shoulders From Typing? A Two-Minute Chest Opener, Chair Twist and Wall Press Desk Routine for Developers Between Agent Runs

7 min read

Claude Code ultrathink Explained: It Now Runs the Turn at xhigh Effort, How It Differs From /effort, What It Costs in Time, and What to Do While It Runs

7 min read

Best Break Reminder Apps for Mac in 2026: Time Out, Stretchly, BreakTimer, LookAway and NotchFit Compared

7 min read

Claude Code 2.1.319: denyInsteadOfPrompting, MCP Background Tasks and What Changes for Unattended Runs and Notifications

8 min read

Drink Water and Stand Up Cues for Developers: Use Claude Code Agent Runs as Hydration and Standing Reminders

7 min read

Claude Code 2.1.323: Code Mode, Progress Heartbeat, Auto-Mode Fallback and 1M Context — What Changed for Unattended Runs

9 min read

Notch Media Controls on a Mac: What the MacBook Notch Can and Cannot Do, Dynamic Island-Style Apps vs NotchFit

7 min read

NotchFit's Hide Workout Toggle: Using the Notch as a Pure Claude Code / Codex Status Panel (and When to Turn the Exercises Back On)

7 min read