Claude Code CLI Reference

Source: Anthropic official docs — CLI reference; Claude Code release stubs raw/anthropic-watch-claude-code-tag-v2-1-196.md, raw/anthropic-watch-claude-code-tag-v2-1-197.md, raw/anthropic-watch-claude-code-tag-v2-1-198.md (GitHub release feed; changelog bodies truncated at source); raw/x-account-claudecodelog-2072425697629343845.md (unofficial @ClaudeCodeLog changelog-thread cluster, cross-verified against ai-research/claude-code-docs-changelog-2026-07-06.md and ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-07-06.md, both live-official-docs fetches); Claude Code release stubs raw/anthropic-watch-claude-code-tag-v2-1-202.md, raw/anthropic-watch-claude-code-tag-v2-1-203.md, raw/anthropic-watch-claude-code-tag-v2-1-205.md (GitHub release feed, v2.1.202–205); raw/x-account-bcherny-2074997570317779038.md (Boris Cherny’s /checkup announcement, 2026-07-08); raw/anthropic-watch-claude-code-tag-v2-1-206.md (GitHub release feed, v2.1.206, 2026-07-10); raw/reddit-1usx952.md (first-party r/ClaudeAI announcement by u/ClaudeOfficial, in-app browser); raw/These_Hidden_Settings_Will_10x_Your_Claude_Code.md (YouTube creator walkthrough, community-sourced settings.json tips — flagged inline where cited); raw/anthropic-watch-claude-code-tag-v2-1-207.md (GitHub release feed, v2.1.207, 2026-07-11); raw/anthropic-watch-claude-code-tag-v2-1-208.md + raw/anthropic-watch-claude-code-tag-v2-1-209.md (GitHub release feed, v2.1.208–209, 2026-07-14 — the v2.1.208 stub truncated at ~11 items, reconciled against the official CHANGELOG.md; full digest in whats-new-2026-w29); raw/anthropic-watch-claude-code-tag-v2-1-210.md + raw/anthropic-watch-claude-code-tag-v2-1-211.md (GitHub release feed, v2.1.210–211, 2026-07-14/15 — both stubs truncated mid-item; reconciled against ai-research/claude-code-docs-changelog-2026-07-17.md); ai-research/claude-code-docs-whats-new-w29-2026-07-17.md (official W29 digest page, fetched 2026-07-17); ai-research/claude-code-docs-changelog-2026-07-17.md (full changelog snapshot for v2.1.210–v2.1.212, fetched 2026-07-17); raw/anthropic-watch-claude-code-tag-v2-1-212.md (GitHub release feed, v2.1.212 — consolidated into the v2.1.212 section below); raw/anthropic-watch-claude-code-tag-v2-1-214.md, raw/anthropic-watch-claude-code-tag-v2-1-215.md, raw/anthropic-watch-claude-code-tag-v2-1-216.md (GitHub release feed, v2.1.214–216, 2026-07-18/20 — consolidated into the v2.1.214–216 section below); raw/anthropic-watch-claude-code-tag-v2-1-217.md, raw/anthropic-watch-claude-code-tag-v2-1-218.md (GitHub release feed, v2.1.217–218, 2026-07-21/22 — both stubs truncated mid-item; consolidated into the v2.1.217–218 section below) Type: Product Reference Product: Claude Code

The complete surface for the claude binary — every subcommand and every flag. This page is the canonical “how do I invoke X from the shell?” lookup. The official claude --help is intentionally short and does not list every flag, so a flag’s absence from --help does not mean it is unavailable.

Quick command map

claude is one binary with several subcommands. Group them by purpose:

Purpose	Commands
Start / continue session	claude, claude "query", claude -c, claude -r
Programmatic / piped	claude -p, cat file | claude -p "query"
Install / update	claude install [version], claude update
Auth	claude auth login, claude auth logout, claude auth status, claude setup-token
Inspect config	claude agents [--cwd <path>] [--json] [--permission-mode <mode>] [--model <alias>] [--effort <level>] ([[claude-ai/whats-new-2026-w21
Background sessions	claude attach <id>, claude logs <id>, claude stop <id> (alias: kill), claude rm <id>, claude respawn <id> [--all], claude daemon status, claude daemon stop --any [--keep-workers] — manage sessions spawned from the Agents view (W20, v2.1.144)
Gateway	claude gateway --config gateway.yaml — self-hosted SSO/policy gateway for Bedrock/Vertex/Foundry (v2.1.195)
MCP / plugins	claude mcp, claude plugin (alias claude plugins), claude plugin init <name> (scaffold a new plugin), claude plugin list [--enabled|--disabled] (W24, v2.1.163 — list installed plugins with optional filter), claude plugin tag, claude plugin prune
Code review	claude ultrareview [target] ([[claude-ai/whats-new-2026-w16
Project management	claude project purge [path] (deletes all state: transcripts, tasks, file history, config entry; --dry-run, -y, -i, --all)
Remote control	claude remote-control

Mistyped subcommands surface a “Did you mean…?” suggestion and exit without starting a session.

Sessions

Form	What happens
claude	Interactive session in the current directory.
claude "query"	Interactive session, with the first user message pre-filled.
claude -c / --continue	Load the most recent conversation in this directory (includes sessions added via /add-dir).
claude -r <id-or-name>	Resume a specific session by ID, by name, or via picker. --fork-session mints a new ID. v2.1.144+: the picker also surfaces background sessions (marked [bg]). v2.1.223+: ID search covers every project on the machine — before v2.1.223 it covered only the current project directory and its git worktrees.
claude -p "query" / --print	Single-shot SDK query, no interactive UI. Programmatic / scripted entry point.
cat file | claude -p "query"	Piped content goes into the same SDK call. Standard non-interactive workflow.
claude --session-id <uuid>	Pin a specific UUID for the conversation (must be valid UUID).
claude -n "name" / --name	Set a session display name (shown in /resume and the terminal title). /rename swaps it mid-session.
claude --from-pr <pr>	Resume sessions linked to a PR (number, GitHub/GHE URL, GitLab MR URL, Bitbucket PR URL). Auto-linked when Claude creates the PR.

Web sessions, remote control, and teleport

The CLI is one of three Claude Code surfaces — local terminal, claude.ai web sessions, and the Claude app. Three flags bridge them:

• --remote "task description" — create a new web session on claude.ai for the task. Runs in Anthropic’s cloud.
• --teleport — pick a running web session and resume it in the local terminal.
• --remote-control / --rc (interactive) or claude remote-control (server-only) — start a local session you can also drive from claude.ai or the Claude app. --remote-control-session-name-prefix (or CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX) sets the auto-generated name prefix.

Auth and install

Command	Purpose
claude auth login	Sign in. --email pre-fills email, --sso forces SSO, --console signs into Anthropic Console for API-key billing instead of a Claude subscription.
claude auth logout	Sign out.
claude auth status	JSON status by default; --text for human-readable. Exit code 0 = logged in, 1 = not.
claude setup-token	Generate a long-lived OAuth token for CI / scripts. Prints to terminal without saving. Requires a Claude subscription.
claude install [version]	Install or reinstall the native binary. Accepts 2.1.118, stable, or latest.
claude update	Update to the latest version.

CLI flags by intent

There are roughly fifty flags; grouping them by what they configure makes the reference scannable.

Permissions and tool surface

Flag	Effect
--permission-mode <mode>	Start in manual (formerly default), acceptEdits, plan, auto, dontAsk, or bypassPermissions. Overrides settings. The value default is still accepted as a backwards-compatible alias for manual (v2.1.200).
--dangerously-skip-permissions	Equivalent to --permission-mode bypassPermissions.
--allow-dangerously-skip-permissions	Add bypassPermissions to the Shift+Tab cycle without starting in it (so you can switch in mid-session).
--allowedTools	Tools that execute without prompting. Pattern syntax (e.g., "Bash(git log *)" "Read").
--disallowedTools	Tools removed from the model’s context entirely.
--tools	Restrict the built-in toolset. "" disables all, "default" enables all, or list ("Bash,Edit,Read").
--disable-slash-commands	Disable all skills and slash commands for this session.
--permission-prompt-tool <mcp-tool>	Route permission prompts through an MCP tool (non-interactive flow only).
--add-dir <path...>	Grant additional working directories for read/edit. .claude/ config is not discovered from these paths.

Model, effort, and budget

Flag	Effect
--model <alias-or-id>	Set model. Aliases sonnet/opus resolve to the latest, or pass full IDs like claude-sonnet-4-6.
--effort <level>	Session-scoped effort: low, medium, high, xhigh, max (availability depends on model). Doesn’t persist to settings. UI labels renamed in v2.1.154: “Speed” → “Faster”, “Intelligence” → “Smarter”. Opus 4.8 defaults to xhigh.
--fallback-model	Auto-fall back to a model when the default is overloaded (print mode only).
--max-turns <N>	Cap agentic turns (print mode only). Exits with error at the limit.
--max-budget-usd <N>	Hard dollar cap on API spend (print mode only).
--betas <header>	Beta headers in API requests (API-key users only).

System prompt

Four flags, two pairs. All work in interactive and non-interactive modes.

Flag	Behavior
--system-prompt <text>	Replace the entire default prompt.
--system-prompt-file <path>	Replace with file contents.
--append-system-prompt <text>	Append to the default prompt.
--append-system-prompt-file <path>	Append from a file.

--system-prompt and --system-prompt-file are mutually exclusive. Append flags can combine with either replace flag. Default to appending — it preserves Claude Code’s built-in capabilities and only adds your requirements. Replace only when you need full control.

Print / non-interactive (-p)

-p / --print flips Claude Code into SDK mode — no interactive UI, prompt → response → exit. The print-only flags below depend on it:

Flag	Effect
--output-format <text|json|stream-json>	Output shape. JSON is one blob; stream-json emits incrementally.
--input-format <text|stream-json>	Input shape (paired with --output-format for full streaming).
--include-hook-events	Include all hook lifecycle events in the output stream. Requires --output-format stream-json.
--include-partial-messages	Include partial streaming events. Requires --print and --output-format stream-json.
--replay-user-messages	Re-emit user messages from stdin on stdout for acknowledgment. Requires --input-format stream-json and --output-format stream-json.
--json-schema <schema>	Validate output against a JSON Schema after the agent completes its workflow. As of v2.1.205, an invalid schema now errors (previously it silently produced unstructured output) and the format keyword is now accepted (previously rejected).
--no-session-persistence	Don’t save the session to disk; not resumable.
--exclude-dynamic-system-prompt-sections	Move per-machine sections (cwd, env info, memory paths, git status) into the first user message. Improves prompt-cache reuse across users/machines running the same task. Ignored when a custom system prompt is set.

Bare mode and init lifecycle

Flag	Effect
--bare	Skip auto-discovery of [[claude-ai/hooks
--init	Run [[claude-ai/hooks
--init-only	Run Setup and SessionStart hooks, then exit without starting a conversation. Useful for CI one-time setup.
--maintenance	Run [[claude-ai/hooks

Subagents and agent teams

Flag	Effect
--agent <name>	Pin one [[claude-ai/subagents
--agents '<json>'	Define custom subagents inline. Same field names as subagent frontmatter, plus prompt for instructions.
--teammate-mode <mode>	How [[claude-ai/agent-teams

Worktrees and Chrome

Flag	Effect
--worktree <name> / -w	Start in an isolated git worktree at <repo>/.claude/worktrees/<name> (auto-generated name if omitted).
--tmux (or --tmux=classic)	Wrap the worktree in a tmux session. Requires --worktree. Uses iTerm2 native panes when available.
--ide	Auto-connect to IDE on startup if exactly one is available.
--chrome	Enable Chrome browser integration for web automation/testing.
--no-chrome	Disable Chrome integration for this session.

MCP, plugins, channels

Flag	Effect
--mcp-config <files-or-json>	Load MCP servers from JSON files or inline strings (space-separated). See [[claude-ai/essential-mcp-servers
--strict-mcp-config	Use only what --mcp-config declares — ignore other MCP configurations.
--plugin-dir <path>	Load plugins from a directory for this session only. Repeat the flag for multiple directories.
--channels <plugins>	(Research preview) MCP servers whose [[claude-ai/channels
--dangerously-load-development-channels	Enable channels not on the approved allowlist (local dev). Accepts plugin:<name>@<marketplace> and server:<name>. Confirmation prompt.

Settings, debug, version

Flag	Effect
--settings <path-or-json>	Path to a settings JSON file or inline JSON string for additional settings.
--setting-sources <list>	Comma list of which sources to load: user, project, local.
--ax-screen-reader	(v2.1.181) Render screen-reader friendly output: flat text without decorative borders or animations.
--debug "<categories>"	Debug mode with category filtering, e.g. "api,hooks" or negated "!statsig,!file".
--debug-file <path>	Write debug logs to a path. Implicitly enables debug mode. Takes precedence over CLAUDE_CODE_DEBUG_LOGS_DIR.
--verbose	Full turn-by-turn logging.
--version / -v	Print version.

Environment variables

The CLI reads several environment variables that aren’t exposed as flags. Most ship via What's New digests; gathered here for lookup:

Variable	Effect
CLAUDE_CODE_SIMPLE	Set automatically by --bare. Skips auto-discovery of hooks, skills, plugins, MCP, auto memory, CLAUDE.md.
CLAUDE_CODE_DEBUG_LOGS_DIR	Default location for debug logs (overridden by --debug-file).
CLAUDE_CODE_DISABLE_CRON	Disables /loop and CronCreate/List/Delete. Already-scheduled tasks stop firing.
CLAUDE_CODE_NO_FLICKER	([[claude-ai/whats-new-2026-w14
CLAUDE_CODE_USE_POWERSHELL_TOOL	([[claude-ai/whats-new-2026-w13
CLAUDE_CODE_PERFORCE_MODE	([[claude-ai/whats-new-2026-w15
CLAUDE_CODE_CERT_STORE	([[claude-ai/whats-new-2026-w15
CLAUDE_CODE_USE_MANTLE	([[claude-ai/whats-new-2026-w15
ENABLE_PROMPT_CACHING_1H	([[claude-ai/whats-new-2026-w16
CLAUDE_CODE_FORK_SUBAGENT	([[claude-ai/whats-new-2026-w17
ANTHROPIC_BEDROCK_SERVICE_TIER	(v2.1.122) Select a Bedrock service tier.
CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX	Same effect as --remote-control-session-name-prefix.
CLAUDE_CODE_STOP_HOOK_BLOCK_CAP	([[claude-ai/whats-new-2026-w21
CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY	(v2.1.143) Set to 1 to opt out of the default -ExecutionPolicy Bypass flag that Claude Code now passes to PowerShell on Windows.
ANTHROPIC_WORKSPACE_ID	([[claude-ai/whats-new-2026-w21
CLAUDE_CODE_PLUGIN_PREFER_HTTPS	([[claude-ai/whats-new-2026-w21
CLAUDE_CLIENT_PRESENCE_FILE	(v2.1.181) Point at a marker file on disk; while the file exists, mobile push notifications for that session are suppressed. Useful when you’re at the machine and don’t want phone notifications for every agent turn.
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT	(v2.1.187) Override the default 5-minute timeout for remote MCP tool calls that hang with no response. Value in milliseconds. Default: 300000 (5 min).
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP	(v2.1.193) Set to 1 to disable automatic memory-pressure reaping for idle background shell commands.

New settings keys (W19–W21)

Settings keys added to settings.json since the W17 reference:

Key	Added	Effect
worktree.baseRef	W19, v2.1.128	fresh (default) branches --worktree, EnterWorktree, and agent-isolation worktrees from the remote default branch. Set to head to branch from local HEAD (keeps unpushed commits in new worktrees).
settings.autoMode.hard_deny	W19, v2.1.136	Block matching actions unconditionally in auto mode regardless of allow exceptions. For actions that should never run automatically even when broader allow rules apply.
parentSettingsBehavior	W19, v2.1.128	Admin key: opt SDK managedSettings into the policy merge. Allows admins to control how managed settings interact with parent policy layers.
worktree.bgIsolation	W21, v2.1.143	"none" lets background sessions edit the working copy directly without EnterWorktree, for repos where worktrees are impractical (very large repos, monorepos with symlink-heavy configs). Default behavior requires EnterWorktree for isolation.

New slash commands and aliases (W16–W17)

Added since the CLI reference was last updated:

Command / alias	Added	Behavior
/usage	W16 (v2.1.111); per-category v2.1.149	Shows what drives your limits: parallel sessions, subagents, cache misses, long context — each with % of last 24 hrs and an optimization tip. Press d or w for day/week views. Merges old /cost and /stats. v2.1.149 (May 22): adds a per-category breakdown — Skills, Subagents, Plugins, and per-MCP-server cost — so you can see which surface is consuming your budget.
/tui	W16 (v2.1.110)	Toggles between classic and flicker-free rendering mid-conversation. Can also set the tui setting in config.
/focus	W16 (v2.1.110)	Collapses view to last prompt, one-line tool summary with diffstats, and final response. Replaces Ctrl+O.
/code-review	W22 (v2.1.147)	Reports correctness bugs at a chosen effort level (e.g., /code-review high). Pass --comment to post findings as inline GitHub PR comments. Renamed from /simplify in v2.1.147 — /simplify is removed; update any automation.
/recap	W17 (v2.1.108)	On-demand session recap: one-line summary of what happened since you last focused this session. Auto-shown on return; toggle from /config.
/fewer-permission-prompts	W16	Scans transcripts for common read-only Bash and MCP calls and proposes an allowlist entry for .claude/settings.json.
/undo	W16 (v2.1.108)	Alias for /rewind.
/proactive	W16 (v2.1.105)	Alias for /loop. See [[claude-ai/scheduled-tasks
vim v / V	W17 (v2.1.118)	Vim visual mode in the prompt input: v for character selection, V for visual-line, with operators and visual feedback.

Settings additions (W16): sandbox.network.deniedDomains — carves specific domains out of a broader allowedDomains wildcard in the sandbox network config. /config now persists to ~/.claude/settings.json (W17, v2.1.119) — theme, editor mode, verbose, and similar settings survive restarts and follow the project/local/policy precedence chain.

New flags (v2.1.178–v2.1.181, 2026-06-21 watchlist sweep)

• --ax-screen-reader (v2.1.181) — Render screen-reader friendly output: flat text without decorative borders or animations. Useful for accessibility needs and for piped output where ANSI TUI decorations are unwanted.
• --teammate-mode default changed (v2.1.179) — Default changed from "auto" to "in-process". The auto value (split panes if inside tmux, otherwise in-process) is still available as an explicit value but is no longer the default. Users who relied on automatic tmux split panes must now set --teammate-mode tmux explicitly.

Removed / deprecated

• --enable-auto-mode — removed in v2.1.111. Auto mode is now in the Shift+Tab permission-mode cycle by default; use --permission-mode auto to start there.

New flags, settings & commands (W25, v2.1.166–v2.1.170)

From the Week 25 release digest (June 6–9 2026):

• fallbackModel setting + --fallback-model (v2.1.166) — configure up to three fallback models tried in order when the primary is overloaded/unavailable; --fallback-model now also applies to interactive sessions. Claude Code also retries a turn once on the fallback model on an unexpected non-retryable API error.
• --safe-mode flag + CLAUDE_CODE_SAFE_MODE (v2.1.169) — start with all customizations disabled (CLAUDE.md, plugins, skills, hooks, MCP servers) for troubleshooting.
• /cd command (v2.1.169) — move a session to a new working directory without breaking the prompt cache mid-session.
• disableBundledSkills setting + CLAUDE_CODE_DISABLE_BUNDLED_SKILLS (v2.1.169) — hide bundled skills, workflows, and built-in slash commands from the model.
• Glob deny rules (v2.1.166) — glob patterns now allowed in the deny-rule tool-name position ("*" denies all tools); allow rules reject non-MCP globs; unknown tool names in deny rules warn at startup.
• Thinking-disable (v2.1.166) — MAX_THINKING_TOKENS=0, --thinking disabled, and the per-model toggle now disable thinking on think-by-default models via the Claude API (3P unchanged; does not apply to always-on Fable 5).
• claude agents --json (v2.1.169) — now includes blocked + just-dispatched sessions; new --all flag (completed sessions) plus id and state fields.

New settings & fixes (W26, v2.1.174–v2.1.176)

From the Week 26 release digest (June 12 2026):

• language setting (v2.1.176) — pin the language for auto-generated session titles. Without this, session titles are generated in the language of the conversation. Set to a BCP 47 tag (e.g., "en") to always use a specific language regardless of conversation language.
• footerLinksRegexes setting (v2.1.176) — array of regex patterns; matching links appear as compact badge entries in the footer row. Configurable via user settings or pinned by managed settings. Use to surface ticket numbers or PR URLs inline.
• enforceAvailableModels managed setting (v2.1.175) — when true, (1) the availableModels allowlist constrains the Default model (a Default that would resolve to a disallowed model falls back to the first allowed model), and (2) user or project settings cannot widen the managed availableModels list. Previously, Default and user-side settings could escape the allowlist. Companion to availableModels (v2.1.162 area) and the version gates added in W24.
• wheelScrollAccelerationEnabled setting (v2.1.174) — set to false to disable mouse-wheel scroll acceleration in fullscreen mode. Useful on trackpads where aggressive acceleration overshoots during code review.
• /model picker now shows actual Default resolution (v2.1.174) — Opus shows as its own row on Max/Team Premium/Enterprise plans; Sonnet on Pro/Team; Opus on pay-as-you-go API.
• VSCode Account & usage (/usage) per-category breakdown (v2.1.174) — cache misses, long context, subagents, and per-skill/agent/plugin/MCP attribution over 24h or 7d. VSCode companion to the CLI /usage per-component breakdown added in W21 (v2.1.149).

New MCP auth commands (v2.1.186, June 22)

• claude mcp login <name> / claude mcp logout <name> (v2.1.186) — authenticate (or sign out of) an MCP server directly from the CLI, without opening the interactive /mcp menu. --no-browser redirects the OAuth handshake through stdin so you can complete login over SSH on a headless box. Adds an auth verb to the claude mcp subcommand family in the Quick command map above. See the Week 26 release digest.

New settings & commands (v2.1.181–v2.1.193, June 17–25)

Settings and commands added in the v2.1.181–v2.1.193 run (see Week 26 digest for full context):

Key / command	Added	Effect
/config key=value	v2.1.181	Set any settings key from the prompt without opening the interactive config UI (e.g. /config thinking=false). Works in interactive, -p, and Remote Control.
/config --help	v2.1.183	List all available shorthand keys for /config key=value. Companion to the v2.1.181 syntax.
sandbox.allowAppleEvents	v2.1.181	Opt-in to let sandboxed commands send Apple Events on macOS. Fixes open, osascript, and browser-based auth flows that were failing with error -600 in the sandbox.
sandbox.credentials	v2.1.187	Block sandboxed commands from reading credential files and secret environment variables — a sandbox-scoped secret-exfiltration guard alongside existing sandbox network controls.
attribution.sessionUrl	v2.1.183	Omit the claude.ai session link from commits and PRs in web and Remote Control sessions.
autoMode.classifyAllShell	v2.1.193	Route all Bash/PowerShell commands through the auto-mode classifier instead of only arbitrary-code-execution patterns. Auto-mode denial reasons also now surface in the transcript, the denial toast, and /permissions recent denials.
respondToBashCommands	v2.1.186	Set to false in settings.json to revert ! bash commands to context-only behavior (default as of v2.1.186: true — Claude responds automatically to ! bash output).
teammateMode: "iterm2"	v2.1.186	Teammate display mode using iTerm2 native panes; shows a warning when auto mode cannot find the it2 CLI.

/config UX changes (v2.1.183): Enter and Space both change the selected setting in toggle mode; Esc now saves and closes instead of reverting. The startup “setup issues” line under the logo was removed — run /doctor or --debug instead.

New releases (v2.1.196–v2.1.200, June 29 – July 3)

CLI-surface changes from the W27 point releases (see Week 27 digest for fuller change lists).

v2.1.197 (June 30) — default model changed. Claude Sonnet 5 is now the default model in Claude Code, with a native 1M-token context window and promotional pricing of $2/$10 per Mtok through August 31. Update to v2.1.197 for access. A bare claude (no --model) now resolves to Sonnet 5, and the sonnet alias points at it.

v2.1.198 (July 1):

• /dataviz skill — new bundled skill: chart and dashboard design guidance with a runnable color-palette validator. Invoke like any slash command.
• Claude in Chrome GA — the browser integration behind --chrome / --no-chrome is now generally available (no install step
• claude agents background sessions now ship PRs — on finishing code work in a worktree they commit, push, and open a draft PR instead of stopping to ask.
• Background agent notifications — sessions that need input or finish fire the Notification hook with agent_needs_input / agent_completed events.
• Explore agent model inheritance — the built-in Explore agent inherits the main session’s model (capped at opus) instead of running on haiku.
• Subagent thinking-config inheritance — subagents and context compaction now inherit the session’s extended-thinking configuration, improving delegated-task output.
• Gateway upstream provider — Claude Platform on AWS (anthropicAws) added as an upstream; model-not-found responses now advance the failover chain.
• --bg cannot combine with -p/--print (v2.1.198). --bg / --background starts a session as a background agent and returns immediately. As of v2.1.198, combining --bg with -p/--print raises an error.
• Removed: the /agents wizard — ask Claude directly, in natural language, to create or manage subagents, or edit .claude/agents/ files yourself. Confirmed verbatim against the official changelog (previously marked inferred in this article).

v2.1.196 (June 29):

• Organization default models — admins set an org-wide default in the org console; it surfaces as “Org default” (or “Role default”) in /model when the user hasn’t chosen one. Companion to the enforceAvailableModels / availableModels managed settings (W26).
• claude mcp list / claude mcp get hardening — no longer spawn .mcp.json servers a repo self-approved via a committed .claude/settings.json; untrusted workspaces show ⏸ Pending approval. Tightens the claude mcp subcommand family in the Quick command map above.
• Readable default session names at session start — easier to identify and message from the Agents view.
• Clickable file attachments — Cmd/Ctrl-click a chat file attachment to reveal it in Finder/Explorer.

v2.1.199 (July 2):

• Stacked slash-skill invocations — /skill-a /skill-b do XYZ now loads all leading skills (up to 5), not just the first. Enables multi-skill composition from a single invocation (e.g., /dataviz /simplify make a chart loads both the dataviz and simplify skills before acting on the prompt).
• CLAUDE_CODE_RETRY_WATCHDOG raises the default retry count for non-capacity transient errors to 300 and lifts the per-session CLAUDE_CODE_MAX_RETRIES cap (previously 15). Relevant for long unattended runs.
• Daemon subcommand routing fix — claude --dangerously-skip-permissions daemon <subcommand> now routes to the daemon subcommand correctly. Earlier versions treated daemon <subcommand> as the prompt for a new interactive session when the flag came first — the subcommand never ran when claude was aliased to include --dangerously-skip-permissions. Only a leading --dangerously-skip-permissions or --allow-dangerously-skip-permissions triggers this fix; any other leading flag still starts an interactive session.
• Transient server 429s (unrelated to your usage limit) now auto-retry with backoff for subscribers.

v2.1.200 (July 3) — “Manual” permission mode rename:

• “default” permission mode renamed to “Manual” across the CLI --help, VS Code, and JetBrains. The --permission-mode flag and "defaultMode" setting both accept manual (new name) alongside default (backwards-compatible alias). The Shift+Tab mode cycle now labels this mode “Manual” instead of “Default”. If you display or parse the mode name from --help output, update your scripts/docs to expect “Manual”. The permission-mode table and flag description above are updated.
• AskUserQuestion dialogs no longer auto-continue by default — previously these dialogs had an idle timeout that would auto-dismiss and continue; the new default requires explicit input. Configure an idle timeout via /config to restore the old behavior.
• Project-scoped plugins now load correctly from git worktrees of the same repository.
• disabledMcpServers / enabledMcpServers crash fix — Claude Code no longer crashes at startup when either key in .claude.json is set to a non-array value (e.g. a string or object instead of a list of server names). These are a distinct settings family from the workspace-trust-gated enableAllProjectMcpServers / enabledMcpjsonServers / disabledMcpjsonServers keys in .claude/settings.json (see MCP reference) — don’t conflate the two when writing automation against either.
• /mcp panel accessibility fix — the interactive /mcp command’s server-list view now tracks focus correctly for screen readers and magnifiers. /mcp (distinct from the claude mcp CLI subcommand family in the Quick command map above) opens a panel showing connected servers, per-server tool counts, and pending-approval/reconnecting state.

New releases (v2.1.202–v2.1.205, July 6–8)

CLI-surface changes from the point releases after W27. /checkup is a same-week maintenance command announced by Boris Cherny (not tied to a numbered release).

v2.1.202 (July 6):

• “Dynamic workflow size” setting in /config — controls how large Claude generally makes dynamic workflows (small / medium / large agent counts). An advisory guideline the model targets, not an enforced cap.
• OpenTelemetry workflow.run_id + workflow.name attributes — workflow-spawned agents now emit these two attributes on their telemetry, so a full workflow run’s activity can be reconstructed from OTel data.

v2.1.203 (July 7):

• Login-expiry warning — Claude Code warns when your login is about to expire, so you can re-authenticate before a background session is interrupted mid-run.
• Grey ⏸ footer badge in manual permission mode — the footer row shows a grey ⏸ badge whenever the session is in manual permission mode, keeping the active mode always visible. Companion to the v2.1.200 “Manual” rename above.
• MCP roots/list includes additional working directories — the session’s extra working directories (from --add-dir) are now exposed to MCP servers via roots/list, with a notifications/roots/list_changed sent when the set changes. MCP servers see every directory the session can touch, not just the launch cwd.

v2.1.205 (July 8):

• Auto-mode transcript-tamper guard — a new built-in auto-mode rule blocks commands that would tamper with session transcript files. Same hardening family as the autoMode.hard_deny / autoMode.classifyAllShell controls above.
• --json-schema validation hardening — an invalid schema now errors instead of silently producing unstructured output, and schemas using the format keyword are now accepted (previously rejected). The --json-schema row in the print-mode table above is updated.

/checkup command (Boris Cherny, July 8). One-pass project/CLI maintenance aimed at sustainable long-running agentic work. In a single pass it: cleans up unused skills, MCP servers, and plugins to reclaim context window; deduplicates CLAUDE.md and reorganizes a bloated root file into nested CLAUDE.md files + skills; disables slow hooks; updates Claude Code to the latest version; enables auto mode by default; and pre-approves frequently-used read-only commands. It always confirms before making any change. Announced by @bcherny; pairs with /doctor (diagnostics) and the Manual-permission-mode default. See Headroom for the broader context-hygiene theme.

Background-agent + worktree reliability, continued (v2.1.202–v2.1.205). The hardening run documented below for v2.1.195–v2.1.200 kept going across these releases — v2.1.204 was fix-only^[inferred] — with further background-session and worktree-isolation robustness fixes: background agents no longer stuck showing “failed”/“completed” after a SendMessage resume (v2.1.205), worktree-isolated subagents no longer running shell commands in the parent checkout (v2.1.203), and Windows worktree removal no longer deleting files outside the worktree through an NTFS junction or directory symlink (v2.1.205).

New release (v2.1.206, July 10)

Claude Code desktop in-app browser. Claude Code on desktop now has an in-app browser: Claude can pull up docs, designs, or any other site, then read, click through, and interact with it the same way it does with your local build. It’s sandboxed and configurable — you choose whether sessions persist. Requires updating to the latest desktop app. Docs: Browse external sites. Distinct from the --chrome / --no-chrome flags above, which integrate with an external Chrome install for web automation/testing — this in-app browser is built into the desktop app itself.^[inferred] Announced first-party by u/ClaudeOfficial on r/ClaudeAI, the same day as the v2.1.206 release below.

v2.1.206 changelog:

• /cd directory path suggestions — /cd now offers directory path suggestions, matching the existing /add-dir behavior. Extends the /cd command (W25, v2.1.169) that moves a session to a new working directory without breaking the prompt cache.
• New /doctor check for checked-in CLAUDE.md files — proposes trimming checked-in CLAUDE.md files by cutting content Claude could already derive from the codebase itself. Companion to the /doctor-related /config UX changes from v2.1.183 above. A community skill, doc-cleanup, tackles the same context-rot problem with a broader rot taxonomy (stale merge-status labels, dead cross-repo paths, unread-footnote corrections) and code-verified claims before flagging.
• /commit-push-pr auto-allows the configured push remote — now auto-allows git push to the repo’s configured push remote (remote.pushDefault, or the sole remote when only one is configured), in addition to origin.
• Gateway: /login supports Anthropic-operated public gateway endpoints — extends the self-hosted claude gateway --config gateway.yaml surface (v2.1.195) with Anthropic-operated public endpoints as an additional login target.
• EnterWorktree confirmation prompt — now asks for confirmation before entering a git worktree outside the project’s .claude/worktrees/ directory.
• Background agents upgrade in the background post-update — background agents now upgrade to a new Claude Code version right after an update completes, instead of paying a slow stale-session upgrade cost the next time you attach.

v2.1.206 bug fixes:

• Expired login now correctly prompts /login, instead of surfacing a misleading “There’s an issue with the selected model” error on every model.
• claude --resume and --continue now respond to keyboard input on startup (previously unresponsive).
• MCP servers configured via --mcp-config or .mcp.json now respect a per-server request_timeout_ms (previously ignored) — long-running MCP tool calls in fresh sessions no longer time out at the 60s default. Distinct from CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT (v2.1.187) above, which covers hung remote MCP calls that get no response at all.
• CLAUDE_CODE_EXTRA_BODY is no longer silently ignored by claude agents / --bg background workers — the shell-exported override now follows the dispatching session.
• OAuth MCP servers no longer require manual re-authentication after a single failed token refresh.
• --permission-prompt-tool pointing at an MCP server no longer crashes with “MCP tool not found” (error text truncated in the source release notes).

New release (v2.1.207, July 11)

Auto mode is now default-available on Bedrock, Vertex AI, and Foundry — no longer gated behind the CLAUDE_CODE_ENABLE_AUTO_MODE opt-in on those platforms; disable with the new disableAutoMode setting. (Elsewhere in this reference: /checkup above enables auto mode by default as part of its one-pass maintenance.)

v2.1.207 bug fixes:

• Fixed the terminal freezing and keystrokes lagging while streaming responses containing very long lists, tables, paragraphs, or code blocks.
• Security-relevant: remote managed settings from a non-interactive run (claude -p, the SDK) were being permanently recorded as consented without the security consent dialog ever showing — now fixed.
• Fixed spurious prompt-injection warnings triggered by benign system-generated conversation updates.
• The auto-updater no longer overwrites a custom launcher script or symlink at ~/.local/bin/claude on every release; /doctor now reports an externally managed launcher.
• Compound commands with cd no longer prompt for permission when the only output redirect is to /dev/null.
• Fixed the transcript jumping above the start of the answer when a response finishes streaming.
• Fixed extensions.worktreeConfig being left in the repo’s .git/config (breaking go-git tools like tea) after the last worktree.sparsePaths worktree was removed.
• Fixed malformed bracket patterns in rules globs, skill paths, .ignore, and .worktreeinclude breaking file reads, file suggestions, and worktree creation.
• Fixed a crash loop in agent teams where a malformed teammate mailbox message caused repeated errors every second until the mailbox file was manually deleted.
• Background sessions auto-named by accepting a plan now show that name on their agent-view row.

New release (v2.1.208–v2.1.209, July 14)

Full narrative in What’s New — Week 29. The new/changed reference surface:

• Screen reader mode expanded (v2.1.208). The --ax-screen-reader flag (v2.1.181, above) gains two more enable paths: env var CLAUDE_AX_SCREEN_READER=1 and setting "axScreenReader": true — opt-in plain-text rendering for screen-reader users.
• vimInsertModeRemaps setting (v2.1.208) — map two-key insert-mode sequences (e.g. jj → Escape) in vim mode.
• CLAUDE_CODE_PROCESS_WRAPPER env var (v2.1.208) — agent view + the background service route every Claude Code self-spawn through a required corporate-launcher wrapper executable (enterprise/managed-launcher).
• Mouse-click support (v2.1.208) for multi-select menus and “Other” input rows in fullscreen mode.
• Safety (v2.1.208): catastrophic removals hidden inside $(…) / backticks / <(…) now prompt in --dangerously-skip-permissions and auto mode, matching the plain-form behaviour.
• Plus a large batch of background-agent reliability and long-session memory/perf fixes (up to 7× faster tool rounds at high MCP-tool counts; up to 79× smaller edit-heavy transcripts) — see the digest.
• v2.1.209 hotfix: fixed /model and other dialogs being blocked in claude agents background sessions (reverts an over-broad guard from v2.1.208).

New releases (v2.1.210–v2.1.211, July 14–15)

v2.1.210 (July 14):

• Live elapsed-time counter on the collapsed tool-summary line — long-running tool calls now visibly tick instead of looking stuck.
• Startup warning for Write(path), NotebookEdit(path), and Glob(path) permission rules — use Edit(path) or Read(path) instead; a rule written against the wrong tool name previously failed silently with no warning.
• Worktree-isolation fix. isolation: 'worktree' subagents could run git-mutating commands against the main repo checkout instead of their own isolated worktree — now correctly contained. Same reliability family as the worktree-isolation fixes logged under v2.1.203/205 above.
• ultracode keyword opt-in no longer fires on non-human-originated input — webhook payloads and relayed PR comments could previously trigger it.
• Fixed a rendered text fragment leaking into crash telemetry when a UI component returned content outside a styled text element.
• Fixed paste markers leaking into external editors opened from Claude Code, which could appear as stray È/É characters around pasted text.
• Fixed claude attach sometimes failing with “job not found” or “agent is still starting” during session transitions — attach now waits for the daemon to settle, and terminal resizes during a slow attach apply once it completes.
• Fixed a session crash when a tool’s result renderer returned a numeric bigint value or plain text instead of a UI element.
• Fixed a hook callback timeout being misreported to the model as a user rejection, which made unattended sessions stop and wait. Relevant to Hooks’ blocking-mechanics reference.
• Fixed Claude assuming a cd took effect after its command was moved to the background; the tool result now states the working directory is unchanged.
• Fixed plugin-provided MCP servers being torn down when a worktree subagent session ended, affecting the MCP server connection for the parent session.

v2.1.211 (July 15):

• --forward-subagent-text flag + CLAUDE_CODE_FORWARD_SUBAGENT_TEXT env var — include subagent text and thinking in stream-json output, so downstream systems consuming a session’s stream see subagent reasoning, not just the parent turn’s.
• Security-relevant: permission-preview spoofing fix. Permission previews relayed to chat channels were not neutralizing bidirectional-override, zero-width, and look-alike quote characters — a tool input could visually alter the rendered approval message. Now neutralized.^[inferred — this closes exactly the class of trust gap Agent Guardrails flags for permission relay: a channel-relayed approval is only as trustworthy as what it displays, and a spoofed preview is a way to get a human to approve something other than what they think they’re approving.] Distinct from, and complementary to, the sandbox.credentials / autoMode.hard_deny controls documented elsewhere in this reference.
• Safety-relevant regression fix: auto mode no longer overrides a PreToolUse hook’s ask decision for unsandboxed Bash — a hook ask now floors the decision at a prompt instead of being silently overridden by auto mode’s own classifier verdict. Directly relevant to the auto-mode classifier behavior documented in Agent Guardrails Layer 2.
• Fixed parallel Claude Code sessions all logging out simultaneously after wake-from-sleep when many sessions share one credential store.
• Fixed plugin MCP servers not reconnecting after an idle web session woke, leaving MCP calls failing until the next message.
• Fixed Claude Code on Vertex and Bedrock attempting the default Opus model at startup and printing a spurious fallback notice when a model is explicitly configured.
• Fixed subagents spawned with an explicit model override reverting to the parent’s model when resumed or sent a follow-up message.
• Fixed nested .claude/rules/*.md files loading even when setting sources exclude project settings.
• File-upload validation edge cases: filenames ending in a DOS device suffix (.prn) or a trailing dot are now accepted; files with multiple hard links are refused.
• Fixed file uploads to Claude in Chrome from remote and CLI sessions.
• Fixed edits that leave the input as ”?” being silently swallowed and toggling the shortcuts panel.
• Fixed a startup hang when another Claude Code process held an exclusive lock on the project’s config file at session start.

New release (v2.1.212, July 17)

/fork → background session; /subtask = in-session fork. As of v2.1.212, /fork creates a new background session in claude agents that copies your current conversation context — it gets its own row and runs independently while you keep the original going. The old in-session fork behavior — delegating a task to a subagent while remaining in the same session — is now /subtask.

/fork evolution:

• Before June 2 (v2.1.160): /fork = copy transcript to a manually-driven new session
• June 2, v2.1.160/161: /fork = in-session subagent delegate; /branch = old manual-copy behavior
• July 17, v2.1.212: /fork = new background session (own claude agents row); /subtask = in-session delegate

claude auto-mode reset [--yes] (v2.1.212) — new subcommand restores the default auto-mode configuration. --yes skips the confirmation prompt. See Auto Mode.

New session-wide caps (v2.1.212):

• CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION (default: 200) — caps WebSearch tool calls per session; further calls are blocked once the cap is reached.
• CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (default: 200) — caps subagent spawns per session. Both caps are tunable via env var.

CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS (v2.1.212) — MCP tool calls longer than this threshold (default: 120000ms / 2 minutes) are automatically moved to the background so the session stays usable. Set to 0 or a very large value to disable.

/resume picker (v2.1.212) — when there is no obvious recent session to resume, /resume now opens a session picker instead of doing nothing.

Deprecated: the Task tool’s mode parameter — scheduling logic has moved to the ScheduleWakeup tool.

v2.1.212 bug fixes:

• Fixed plan mode running file-modifying Bash commands without a permission prompt (correctness regression — plan mode is supposed to block writes).
• Fixed worktree creation following a repository-committed symlink at .claude/worktrees, which could create files outside the repository (same worktree-isolation family as the v2.1.203/205/210 fixes).
• Fixed a continue:false hook halt being dropped when the tool failed or completed mid-stream, and hook-infrastructure errors misreported as user rejections.
• Fixed SIGTERM not propagating to the full Bash process tree when Claude terminates a command — child processes were left running.
• Prompt caching improvement for commands routed behind Claude Code gateways.

New releases (v2.1.214–v2.1.216, July 18–20)

v2.1.214 (July 18) — new capabilities:

• EndConversation tool. Claude can now end a session with highly abusive users or persistent jailbreak attempts — the same capability live on claude.ai since 2025. See Anthropic — Ending a subset of conversations.
• Progress heartbeat for long-running tool calls that previously went silent — the session now emits a periodic heartbeat so long tools don’t look hung.
• ISO modified timestamp added to memory-file frontmatter (memory files now carry a machine-readable last-modified stamp).
• OpenTelemetry: message-level correlation + tool provenance. New message.uuid, client_request_id, and tool_source attributes on OTEL log events; new CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH to cap logged content length.

v2.1.214 permission / Bash-safety hardening (a batch of fail-closed fixes — relevant to Auto Mode and anyone relying on allow-rules):

• Fixed single-segment dir/** allow rules (e.g. Edit(src/**)) auto-approving writes to a nested dir/ anywhere in the tree instead of only <cwd>/dir.
• Fixed a permission-check bypass affecting commands run in Windows PowerShell 5.1 sessions.
• Bash permission checks now fail closed on file-descriptor redirect forms that bash parses differently than the permission analyzer.
• Commands over 10,000 characters now always prompt instead of running automatically.
• zsh variable subscripts/modifiers inside [[ ]] comparisons now prompt (previously treated as inert text).
• No longer auto-approves certain help/man commands that could smuggle unsafe options, command substitutions, or backslash paths.
• Fixed permission prompts on remote sessions that could proceed before the local confirmation dialog resolved.

v2.1.215 (July 19): Claude no longer runs the /verify and /code-review skills on its own — invoke them explicitly with /verify or /code-review when you want them.

v2.1.216 (July 20):

• sandbox.filesystem.disabled setting (new) — skip filesystem isolation while keeping network egress control. For workflows that need full-disk access but still want the sandbox’s network guardrails.
• Fixed a quadratic slowdown in long sessions: message-normalization cost grew with turn count, causing multi-second stalls and slow resumes.
• Fixed auto mode denying commands with “HTTP 401” classifier errors after the OAuth token expired or rotated mid-session (see Auto Mode).
• Fixed AskUserQuestion telling Claude to continue even when the answer asked it to wait or explain first — free-text answers now get neutral wording.
• Fixed Claude Code on the web re-asking the same question and dropping the answer after a few idle minutes.
• Worktree-isolation fixes (same family as v2.1.203/205/210/212): worktree-isolated subagents redirecting git into the shared checkout via git -C, --git-dir, or GIT_DIR/GIT_WORK_TREE; sessions landing in another project’s leftover worktree when cwd didn’t match the selected project; background sessions whose worktree has no git repo being undeletable.
• Fixed resumed background-agent sessions reverting to the default agent — the agent’s prompt and tool restrictions are now restored on resume.
• Fixed claude daemon stop --any potentially terminating an unrelated process via a stale legacy daemon lockfile.
• Fixed assorted UX: @-mentions silently attaching nothing after file-modifying hooks; vim dot-repeat of c-operators and paste; statusline running twice on resume; resume-picker hangs on failure; Esc-Esc at an idle prompt not opening the rewind picker.

New releases (v2.1.217–v2.1.218, July 21–22)

Sources: raw/anthropic-watch-claude-code-tag-v2-1-217.md (tagged 2026-07-21T21:35:10Z) and raw/anthropic-watch-claude-code-tag-v2-1-218.md (2026-07-22T21:24:56Z), both ashwin-ant. Both stubs are truncated mid-item at the source feed — v2.1.217 cuts off at “Fixed Remote Control sessions not showing a …” and v2.1.218 at “…priced at the co…”. Everything below is verbatim-backed; see Open Questions for the tail.

v2.1.217 (July 21) — new:

• Emoji shortcode autocomplete in the prompt input. Type :heart: to insert ❤️, or :hea for suggestions. Disable with the emojiCompletionEnabled setting — the new settings key of this release, and the one to reach for if you write code where a stray : sequence shouldn’t expand.
• Warnings when transcript writes are failing (e.g. disk full) or when session saving is off because of an inherited environment variable — instead of losing transcripts silently. Companion to the W25 fix for VS-Code-inherited env vars killing transcripts; this one surfaces the condition rather than fixing a single cause.

v2.1.217 fixes:

• MCP truncated-output memory leak. Truncated MCP tool outputs kept the full untruncated result in memory for the rest of the session. Directly relevant to long sessions against chatty MCP servers — the visible output was small, the retained footprint was not.
• Background-session isolation now canonicalizes symlinked working directories — previously a symlinked cwd could let a session escape its workspace folder. Same worktree/background-isolation family as v2.1.203/205/210/212/216, and the security-relevant one of this batch.
• Auto-compact never triggering for Claude Opus 4.8 on Bedrock, and /compact failing once already over the limit. Both fixed. Bedrock users on Opus 4.8 were effectively running without auto-compact.
• Windows auto-update failures that could leave claude.exe missing; failed updates now restore the preserved executable automatically.
• Corporate mTLS, TLS-verify, OAuth scope, and proxy settings being ignored in Claude Desktop sessions.
• Managed OTEL_EXPORTER_OTLP_ENDPOINT not governing all signals — lower-scope signal-specific overrides no longer redirect telemetry away from the managed endpoint. An enterprise telemetry-exfiltration gap, closed.
• --resume / --continue / /resume failing with a TypeError on a transcript with a malformed attachment entry.
• Screen-reader mode: startup announcement cut off by the first prompt render; thinking status row re-rendering every few seconds to update elapsed time and token counts.

v2.1.218 (July 22) — the /code-review and /ultrareview release:

• /code-review now runs as a background subagent — review work no longer fills your conversation, and stacked slash commands stay its review target. The most consequential change in this pair for anyone who reviews inside a working session.
• Fixed /ultrareview failing on descriptive arguments like "review my auth changes" — those now run a review of your current branch, with the text applied as a note to the findings rather than being parsed as a target.
• Fixed /code-review ultra silently running a local review in non-interactive sessions — it now launches the cloud review. Silent-downgrade class bug: scripted/CI invocations were getting a weaker review than requested with no signal.
• Fixed the left arrow key discarding the conversation with no undo. Presses right after editing now ask to confirm, and Esc in the agent view returns to the conversation it backgrounded.
• claude mcp list and /mcp now show HTTP status and error text when a server fails to connect, plus a warning for MCP config values with hidden leading or trailing whitespace. Two of the most common silent MCP-config failures, finally surfaced.
• Fixed Windows paths with \u-prefixed segments (e.g. C:\Users\unicorn) being corrupted into CJK characters in tool inputs, which made those files inaccessible.
• Fixed multi-line paste collapsing into one line with j in place of newlines, in terminals that encode pasted newlines as Ctrl+J.
• Fixed /context reporting stale pre-compact token usage after compacting from the message picker.
• Screen-reader announcements of deleted text for word and line deletions (Option+Delete, Ctrl+W, Cmd+Backspace, Ctrl+U, Ctrl+K) in --ax-screen-reader mode.
• Gateway spend metering now prices Bedrock application-inference-profile ARNs and other config-mapped upstream model IDs correctly (item truncated at source).

New releases (v2.1.219, July 24)

Source: ai-research/claude-code-docs-changelog-2026-07-24.md (official changelog, fetched 2026-07-24). Also fills truncation gaps for v2.1.217–218 (previous stubs cut mid-item).

v2.1.219 (July 24) — Claude Opus 5 + settings + subagent depth:

• Claude Opus 5 as default Opus model — claude-opus-5 replaces Opus 4.8 as the default Opus; 1M context; fast mode at $10/$50 per MTok. The /model picker now labels the Opus row “Opus (1M context)”.
• Opus 4.7 removed from fast mode — /fast now applies to Opus 5 and Opus 4.8 only.
• workflowSizeGuideline settings key — controls the Dynamic workflow size guideline from any settings file; hides the /config toggle while set.
• Dynamic workflows now default to medium size (aim for fewer than 15 agents); override via /config or workflowSizeGuideline in settings.
• sandbox.network.strictAllowlist setting — deny non-allowlisted hosts for sandboxed commands without prompting.
• DirectoryAdded hook — fires after /add-dir or SDK register_repo_root registers a new working directory mid-session (see Hooks).
• mcp_server_errors in headless stream-json init event — lists --mcp-config entries skipped by config validation; terminal runs print a startup warning.
• Nested subagent forwarding in stream-json — depth-2+ subagents appear in --forward-subagent-text output, keyed by their spawning Agent tool_use id.
• Managed MCP allowlist/denylist ${VAR} entries now resolve from the startup environment and managed-settings env instead of settings-file env.
• Subagent nesting depth 3 — subagents can spawn nested subagents up to depth 3 by default (was briefly 0 in v2.1.217); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting.
• Fixed claude -p text output dropping the already-produced answer when a turn dies mid-stream on an API error.
• claude mcp list and /mcp now show HTTP status and error text when a server fails to connect, plus a warning for hidden leading/trailing whitespace in MCP config values.
• /model picker highlight updated: only the newest model’s name is highlighted.
• claude-api skill updated to default to Opus 5 with a migration path from Opus 4.8.
• Structured failure categories added to self-hosted runner spawn/session failures.

New releases (v2.1.220–v2.1.224, July 25–August 7)

Source: ai-research/claude-code-docs-changelog-2026-08-07.md (official changelog, fetched 2026-08-07). Full narrative in What’s New — Week 32.

v2.1.220 (July 25): Bug fixes and reliability improvements only — no new CLI surface.

v2.1.221 (August 4) — new surface:

• mode: "mask" for sandbox credential files (Linux/WSL) — new option under sandbox.credentials. The session reads a sentinel copy of the file (or a structured-field extract) while the sandbox proxy substitutes the real value on egress. On macOS, credential masking falls back to deny. Extended in v2.1.224 with extract/onExtractNoMatch, decode: "jwt", and awsPairs/sigv4 options (all require network.tlsTerminate).
• prompt-audit subcommand on the claude-api skill — audits prompts and tool descriptions for patterns written for older models. Run against your CLAUDE.md and skill files. Companion to The New Rules of Context Engineering for Claude 5 Models.
• /status now shows session kind — interactive, background job that is attached, or background job that is unattended.
• Sessions forked with /fork now create their own git worktree (same isolation guarantee as worktree-isolated subagents extended to /fork).
• [VSCode] Focus view — Ctrl+Alt+F or “Claude Code: Toggle Focus view” hides tool activity behind an expandable per-turn summary with a live running-tool indicator.

v2.1.222 (August 4) — changes and removals:

• ultraplan removed. See Ultraplan (removed in v2.1.222).
• Remote Control auto-start can no longer be enabled by a repo-local .claude/settings.json. A committed settings file can disable Remote Control auto-start, but cannot enable it. Enable via user-scope /config only.
• /usage MCP attribution corrected — was inflating MCP server share by counting every turn after any tool call to a server. Now reflects only turns that actually consumed its results. Relevant: any MCP cost estimates derived from /usage before this release are inflated.

v2.1.223 (August 6) — new surface and behavior changes:

• /review is now an alias of /code-review — consolidates the two commands. /code-review reviews the current diff or a PR; /code-review ultra runs a deep cloud review. With no effort level, /code-review reuses the last typed level — type /code-review high to change it. (Note: v2.1.202 changed /review to single-pass; v2.1.223 makes it a full alias.)
• Marketplace "owner/*" wildcard entries in strictKnownMarketplaces and blockedMarketplaces managed settings — allow or block all marketplace repos under a GitHub org in one entry.
• CLAUDE_CODE_DISABLE_1M_CONTEXT now holds every Claude model with a native 1M context window to 200K via auto-compaction — no longer a fixed model list. A startup warning appears when the env var is set but auto-compaction is not enforcing 200K. If you set this env var expecting it to cover a model released after the previous fixed list was compiled, it may not have applied before this release.
• /teleport hint shown in cloud sessions — displays how to continue the session locally via claude --teleport.

v2.1.224 (August 7) — new surface:

• claude self-hosted-runner — new subcommand (Team and Enterprise). Registers your own machines or containers as execution targets for Claude Code web, mobile, and desktop sessions. See Week 32 — Self-hosted runners.
• archive plugin source — claude plugin install <url.zip> installs a plugin from a zip over HTTPS with optional --sha256 pinning. Neither git nor npm required. See Plugins and Marketplaces.
• crossSessionInbound setting — messages sent via SendMessage to a session running with bypassed permissions are held for human approval; messages to other sessions auto-deliver.
• dialogExpiry setting — controls how long held cross-session-inbound approval dialogs remain open.
• ANTHROPIC_BEDROCK_REGION_PREFIX — env var to prefer a specific Bedrock cross-region inference profile over the one derived from AWS_REGION.
• Cross-session SendMessage + ListAgents (macOS and Linux) — Claude Code sessions can now discover and message each other across machines. See Week 32 — Cross-session messaging between machines.
• 200-subagent-per-session spawn cap removed. CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (added v2.1.212, default 200) no longer hard-limits long-running sessions. Concurrency cap (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, default 20) and depth cap (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, default 3) still apply.

v2.1.217–218 gaps now filled (items missing from the truncated raw stubs, now confirmed from official changelog):

v2.1.217 missing items (cut at “Fixed Remote Control sessions not showing a …”):

• Fixed Remote Control sessions not showing a pending permission prompt or dialog to viewers that connected after it appeared.
• Fixed background shells becoming impossible to stop after /background or ← on heavily loaded machines (most visible on Windows).
• Fixed a CLAUDE.md or SKILL.md paths frontmatter value with many brace groups OOM-killing or stalling the CLI — brace expansion is now budget-bounded.
• Fixed transcript preview sitting flush against the input area when attaching to a starting background session.
• Improved footer PR badge links to be clickable hyperlinks even when terminal support can’t be detected (over ssh/tmux); set FORCE_HYPERLINK=0 to opt out.
• Changed login-expiry warning to appear 3 days before expiry instead of 5.
• CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (new, default 20) — cap on concurrently-running subagents; a single message can’t fan out unbounded background agents.
• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH — sets nesting depth; v2.1.217 initially set default to 0 (disabled nesting), v2.1.219 revised default to 3.
• --max-budget-usd now stops background subagents once reached.

v2.1.218 missing items (cut at gateway-spend-metering line):

• Fixed gateway spend metering to price Bedrock application-inference-profile ARNs and other config-mapped upstream model IDs at the configured model’s rates (the truncated “…priced at the co…” line).
• Fixed mojibake when a long IDE selection was truncated mid-emoji, and a case where a tool executor error could be silently dropped.
• Fixed engine teardown race that could start and abandon a phantom turn; input pushed after close now consistently rejected.
• Fixed spurious “[Request interrupted by user]” messages after interrupted tool calls; unpaired tool_use block left when a tool aborted mid-response.
• Fixed VoiceOver reading “new line” instead of echoing the typed space at end of input in --ax-screen-reader mode.
• Fixed plugin and settings panels not moving the terminal cursor to the focused row.
• Fixed crashes (maximum call stack exceeded) on deeply nested watched directory tree deletion and on rendering deeply nested UI trees.
• Fixed PR events occasionally lost when a session exited immediately after creating/linking a PR.
• Fixed Bedrock setup wizard failing for assume-role profiles in partitioned AWS regions and on proxy-only networks.
• Fixed rare negative/incorrect turn duration measurements — turns now timed with a monotonic clock.
• Fixed “N MCP servers need authentication” startup notice over-counting claude.ai connectors that aren’t connected.
• Fixed prompt history entries dropped or duplicated when history writes raced or failed.
• Fixed a retry loop re-sending doomed requests after context-overflow error with large thinking budget.
• Security: Fixed agent frontmatter hooks running from untrusted folders — hooks now require the agent file’s folder to have accepted workspace trust.
• Fixed fork-session lineage lost after compaction in headless/SDK sessions.
• Fixed a resumed session failing every turn when its history held a malformed delta attachment.
• Changed /deep-research to start only when invoked manually.
• Changed plan mode with auto to no longer prompt for Bash commands the static analyzer can’t prove read-only.
• Changed server-managed settings so benign feature/cost toggles no longer trigger the settings-approval prompt.
• Agent names with : are now rejected (reserved for plugin namespacing).
• Skills with context: fork now run in background by default; opt out per skill with background: false.
• yes/no/on/off/1/0 now accepted as boolean values for skill/plugin frontmatter.
• Fixed remote sessions continuing to send heartbeats after worker replacement.

Background agent reliability hardening (v2.1.195–v2.1.200)

A running theme across the W27 point releases, not a single feature ship: long-running background sessions/agents (claude agents, the daemon supervisor) got measurably more resilient to interruption across five consecutive versions. Verified against the official changelog (ai-research/claude-code-docs-changelog-2026-07-06.md) — this closes the “background agents surviving crashes, with cross-OS handover” item flagged by the unofficial @ClaudeCodeLog changelog-thread cluster (raw/x-account-claudecodelog-2072425697629343845.md).

• Cross-platform crash/restart survival (v2.1.196). Long-running background commands and workflows now survive the session’s own process being stopped, restarted, or updated — including on Windows, where background shells are now handed off instead of killed outright. Daemon-restart-killed workers are automatically resumed the next time the agents view opens.
• Daemon-crash recovery (v2.1.200). Fixed background agents never restarting after a crash left a stale daemon.lock file whose PID the OS had since reused (previously blocked all future restarts indefinitely). Hardened daemon handover so a reinstalled older build can no longer hijack a running daemon — build recency is now judged by the version’s embedded build timestamp.
• Sleep/wake and stall fixes (v2.1.200). Fixed background sessions silently stopping mid-turn after sleep/wake or when reopening a previously-stalled session; fixed a stalled session re-running a turn that had already been cancelled with Esc.
• Platform-specific fixes (v2.1.199). Linux: fixed the background-agent daemon killing itself and every running agent roughly every 50 seconds after an unclean shutdown left a corrupted worker record. macOS: fixed background agents failing to cold-start over SSH with “Could not switch to audit session” (a regression introduced in v2.1.196).

See Week 27 digest for the exhaustive per-version bug list (roster corruption, socket auth tokens, control-byte terminal leaks, and more) — this section covers only the subset that answers “does a background agent survive X?”

Recent additions (2026-08-09 watchlist sweep)

New and updated CLI surface from ai-research/watchlist-snapshots/code-claude-com-docs-en-cli-reference-2026-08-09.md:

--autocompact <auto|tokens> flag (v2.1.221)

Set the auto-compact window for a session without changing saved settings. Accepts the same values as /autocompact. Requires Claude Code v2.1.221 or later.

claude --autocompact 500k    # threshold: 500 000 tokens for this session
claude --autocompact auto    # default auto-compaction logic for this session

Useful in one-off sessions or CI scripts where you want a compaction threshold that differs from your persisted /autocompact setting, without touching that setting for future sessions.

--resume now searches all projects on this machine (v2.1.223)

When you pass a session ID to --resume / -r, Claude Code now searches the current project directory and its git worktrees, then every other project on this machine. Before v2.1.223, session ID search covered only the current project and its worktrees — sessions in other projects were unreachable by ID unless you navigated there first.

Name search and the picker are unchanged — they already searched across all projects before v2.1.223.

--mcp-config with -p skips wait for cached servers (v2.1.221)

When using --mcp-config with -p, Claude Code waits for pending servers to connect before running the first turn. Servers with a cached tool list (from a prior session) skip the wait and connect on first use. Both the wait behavior and the cached-tool-list shortcut require v2.1.221 or later.

Recent additions (2026-07-05 watchlist sweep)

New CLI surface in Claude Code as of v2.1.195–v2.1.199, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-cli-reference-2026-07-05.md:

• claude gateway --config gateway.yaml (v2.1.195). New subcommand: starts the self-hosted Claude apps gateway server. For administrators deploying SSO and policy in front of Claude Code on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. Requires --config pointing at a gateway.yaml. Added to the Quick command map above under “Gateway.”
• claude daemon stop --any [--keep-workers]. New subcommand: stops the background-session supervisor and the sessions it hosts. --keep-workers leaves background sessions running so the next supervisor reconnects to them; --any confirms stopping an on-demand supervisor. Use to recover from an unresponsive supervisor.
• --bg cannot combine with -p/--print (v2.1.198). Previously undocumented constraint: combining --bg / --background (start as background agent, return immediately) with -p/--print (SDK/non-interactive mode) raises an error as of v2.1.198.
• Daemon routing fix (v2.1.199). claude --dangerously-skip-permissions daemon <subcommand> now routes to the daemon subcommand. Previously, a leading --dangerously-skip-permissions caused daemon <subcommand> to be treated as an interactive session prompt.

Recent Signals

[Reddit signal — r/ClaudeCode 2026-05-09]: r/ClaudeCode post 1t8712b (“20 Claude Code commands worth using”, score 318) inventories operator-level slash commands grouped into stop/undo/branch (Esc, double-Esc//rewind, /btw, /branch), context management (/compact, /clear, /export, /resume, claude -c, claude -r, /remote-control aka /rc), working-smarter (/model opusplan, /simplify, /insights HTML report at ~/.claude/usage-data/report.html, /loop with .claude/loop.md overrides, /skills [name]), and keyboard shortcuts (Ctrl+V paste screenshots, Ctrl+J newline-without-send, Ctrl+R prompt history search, Ctrl+U clear input). Notable hazard surfaced in comments: /model opusplan has an unresolved bug where every subagent runs Opus (very expensive) — flagged for Quick command map consumers to verify before adopting opusplan as default. Verify each entry exists in this reference and append any that are missing during the next refresh pass.

[X signal — @bcherny 2026-05-21 → SHIPPED v2.1.149]: Boris Cherny (@bcherny) announced an upcoming /usage breakdown by Skills, Agents, MCPs, and Plugins. Shipped in v2.1.149 (2026-05-22) — see the updated /usage row in the table above. /usage now shows per-category attribution on top of the existing day/week view.

[Reddit signal — r/ClaudeCode 2026-05-22]: r/ClaudeCode post 1tkv87g (“/remote-control is a window into what the future is going to be like”, score 490 / 203 comments, u/OpinionsRdumb) is the highest-engagement /remote-control thread to date — workflow validation, not new feature surface. The OP frames /remote-control as a replacement for running 2-3 simultaneous local agents: enter /remote-control in CLI or Desktop, the session syncs in real time to the phone Claude app, you can drive it from anywhere, and the multi-agent burnout pattern collapses into one sequential session you check on from your phone. Anchors the --remote-control / claude remote-control row above as a load-bearing primitive (alongside Managed Agents and the --remote / --teleport siblings) rather than a niche flag. No CC version delta — feature has been live since W21; the signal is community validation crossing into broad awareness.

[Claude Code update — 2026-06-02, @ClaudeDevs]: /fork changed semantics → background agent; old behavior renamed /branch. /fork now spawns a background agent that inherits your exact context (system prompt, tools, conversation history, model selection) plus the prompt cache, and returns its result directly into your current session — delegated/parallel work with no context or cache loss. The previous /fork behavior (copy the transcript into a new session you drive manually) is now /branch — i.e. the /branch in the 2026-05-09 inventory above is this renamed command. Shipped on the v2.1.160/161 line; the full changelog lands in the Week-24 release digest. Source: @ClaudeDevs.

Community-sourced settings (YouTube walkthrough, ingested 2026-07-10)

A creator walkthrough (“These Hidden Settings Will 10x Your Claude Code”) surfaced several settings.json keys and one keyboard interaction not yet cross-verified against an official changelog or docs page reviewed by this wiki. Treat as community-reported, not Anthropic-confirmed, until corroborated.

• autoCompactPercentageOverride^[inferred] (settings.json) — overrides the context-window percentage at which Claude Code auto-compacts. Per the creator, the built-in default waits until the context window is ~95% full; they recommend overriding to ~75%, their stated “sweet spot” for pre-empting context rot (which they say can start around 70-80% full). Accepts a value from 0 to 100. See Headroom for the broader context-hygiene theme.
• cleanupPeriodDays^[inferred] (settings.json) — overrides the default 30-day retention window for saved conversation transcripts (the history shown in /resume). The creator warns not to set it to 0 (wipes history immediately); set a larger number (e.g. 365) to retain more.
• spinnerTipsEnabled: false^[inferred] (settings.json) — disables the rotating tips shown under the input spinner while Claude is working.
• Starter deny-rule pair (settings.json permissions) — the creator’s recommended minimum: deny reads of .env files (keeps secrets/API keys out of context) and deny git push * (keeps publish authority with the human even when commits happen automatically). Deny rules are checked before allow rules at every level — ties into the glob deny-rule support shipped in v2.1.166 above.
• Mobile push notifications for remote-control sessions (settings.json) — the creator describes an “agent push notify enabled” line (set true) that, inside a --remote-control / /remote-control session, pings your phone when a permission prompt or question is waiting. Distinct from CLAUDE_CLIENT_PRESENCE_FILE (v2.1.181) above, which suppresses mobile pushes while a presence marker file exists on the local machine — this is the opt-in push itself, not its suppression.
• Blank commit/PR attribution (settings.json) — the creator shows blanking out the default commit/PR attribution text (normally something like “Generated with AI” / “Co-Authored-By: your alias”) so commits stop being attributed to Claude. The transcript doesn’t spell out the exact key on screen; distinct from attribution.sessionUrl (v2.1.183) above, which only omits the claude.ai session link, not the co-authorship text itself.
• Ctrl+S prompt stash (keyboard interaction) — while typing a prompt, Ctrl+S stashes (cuts) the in-progress draft; pasting or hitting Ctrl+S again from a fresh prompt restores it. Functions like cut/paste for prompt drafts — useful for detouring mid-prompt without losing the draft.
• ClaudeSounds (third-party, not an Anthropic project) — a community notification-hook library by Dave Schumacher that wires custom audio notifications into Claude Code’s notification hooks, as an alternative to the built-in terminal-bell/OS-notification options exposed via /config. Clone the repo, add it to PATH, configure it as a notification hook.

Key Takeaways

• One binary, named subcommands (auth, mcp, plugin, remote-control, agents, auto-mode, setup-token, install, update); everything else is flags on claude.
• claude --help is incomplete by design — refer to this page (or the official source) for the full surface.
• -p / --print is the SDK gateway. Most automation flags (--output-format, --max-turns, --max-budget-usd, --no-session-persistence, --include-hook-events) only apply with -p.
• --bare is the fastest scripted entry — skips auto-discovery of hooks, skills, plugins, MCP, auto memory, CLAUDE.md. Pair with -p for cheap scripted calls.
• --exclude-dynamic-system-prompt-sections is the multi-tenant prompt-cache lever: hoists per-machine state into the user message so the cached prefix is shared across users running the same scripted task.
• --fork-session exists alongside --resume / --continue — the standard way to branch off an existing conversation without overwriting it.
• Three modes for “how does Claude Code talk to claude.ai?”: --remote (push to web), --teleport (pull web back to terminal), --remote-control / claude remote-control (drive local from web/app).
• Mistype protection: claude udpate returns a “Did you mean claude update?” suggestion and exits.

Try It

1. Cheapest non-interactive call. claude --bare -p "summarize this in one line" < notes.txt — no auto memory, no plugins, no MCP, no CLAUDE.md scan. Useful in cron jobs and CI scripts where you just want the model.
2. Force a specific model + effort. claude --model claude-sonnet-4-6 --effort high "..." to pin both for one session without changing settings.
3. Plan-mode start. claude --permission-mode plan so the first turns plan-only; switch to write mode via Shift+Tab once aligned.
4. Worktree-isolated session. claude -w feature-auth --tmux — clean branch + tmux split. Keeps speculative work out of the main checkout.
5. Resume by name. claude -r "auth-refactor" (note: works because you set -n "auth-refactor" when you started). --fork-session if you want a copy that diverges.
6. Web ↔ terminal handoff. claude --remote "Triage open Sentry issues" to spin a web session, then claude --teleport later to pull it down to your terminal.
7. Multi-user prompt-cache reuse. claude -p --exclude-dynamic-system-prompt-sections "..." in scripted multi-user workloads — different users, same cache prefix.
8. CI-safe auth. claude setup-token once locally → store the OAuth token in CI secrets → CI runs claude -p "..." non-interactively against it.

Related

• Claude Code Hooks — --init, --init-only, --maintenance are the CLI entry points to the hook lifecycle.
• Claude Code Scheduled Tasks — /loop is the in-session counterpart; the CLI gives you the flags to start that session.
• Claude Code Channels — --channels and --dangerously-load-development-channels configure which MCP push channels a session listens to.
• Claude Code Agent Teams — --teammate-mode selects how teammates display.
• Claude Code Subagents — --agent pins one; --agents declares them inline.
• Claude Managed Agents — --remote / --teleport connect terminal sessions to the cloud surface.
• Claude Code Routines — durable cloud scheduling counterpart to local CLI invocations.
• Essential MCP Servers — claude mcp, --mcp-config, --strict-mcp-config configure the MCP surface.
• Plugins and Marketplaces — claude plugin (alias plugins), --plugin-dir.
• Opus 4.7 Best Practices — what --effort xhigh means and when to use it.
• Extended Thinking (API Reference) — model-config sibling for the API surface.
• Claude Cowork — --remote creates a new web session on the same surface.
• Ultrareview — slash-command counterpart that runs in a Claude-managed sandbox.

Open Questions

• The page lists claude subcommands but does not include slash commands — those live under a separate “Interactive mode” / commands reference. Worth a future ingest.
• Environment variables referenced (CLAUDE_CODE_SIMPLE, CLAUDE_CODE_DEBUG_LOGS_DIR, CLAUDE_CODE_DISABLE_CRON, CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX) point to a separate /en/env-vars page. Ingest candidate for the env-var matrix.
• The “See also” section names Chrome extension, Interactive mode, Quickstart, Common workflows, Settings, and Agent SDK pages — none currently in the wiki at full depth. Candidate ingests if the surface keeps growing.
• v2.1.217 / v2.1.218 stubs truncated at source. The anthropic-ecosystem-watch GitHub-release feed cuts both bodies mid-item: v2.1.217 at “Fixed Remote Control sessions not showing a …” (the Remote Control fix is unrecoverable from this raw file) and v2.1.218 at the gateway-spend-metering line (“…priced at the co…”, presumably “at the correct rate”). Trailing items after those points are unknown. Reconcile against the official CHANGELOG.md or code.claude.com/docs/en/release-notes — the same truncation pattern hit v2.1.208 and v2.1.210–211.
• emojiCompletionEnabled default and scope unconfirmed. The v2.1.217 note says the feature is disabled with this setting, implying it ships on by default, but neither the default value nor whether it is a boolean or an enum is stated in the stub.