Claude Code has a set of power features that experienced users reach for on complex or risky work. Planning mode, extended thinking, auto mode, sandboxing, and headless operation all change how Claude works in fundamental ways. This module covers each one in depth.
Planning Mode and Extended Thinking
Planning mode separates thinking from doing. When you activate it, Claude first researches the codebase and creates a detailed implementation plan. You review and optionally modify the plan, then Claude executes it. This prevents the common failure mode of Claude starting to code before fully understanding the problem.
Activate it with /plan <description>, the --permission-mode plan CLI flag, or Shift+Tab to cycle permission modes. When Claude presents a plan, press Ctrl+G to open the proposed plan in your default text editor and edit it directly before approving. The opusplan model alias routes planning to Opus and execution to Sonnet:
claude --model opusplan "redesign the database schema for multi-tenancy"Extended thinking gives Claude more time to reason before responding. Toggle it with Option+T (macOS) or Alt+T. The /effort command sets reasoning depth: low, medium, high, xhigh, or max. In an interactive session, pressing Enter in the /effort slider saves the level as your default and applies it in later sessions, while s applies it to that session only (requires Claude Code v2.1.257 or later). max applies to the current session only unless CLAUDE_CODE_EFFORT_LEVEL sets it, and a -p run applies the level to that session only. Set it per-session with export CLAUDE_CODE_EFFORT_LEVEL=high. For prompts where you want deeper reasoning on a single turn, include the word “ultrathink” anywhere in your prompt — Claude Code recognizes the keyword and adds an in-context instruction without changing your session effort setting, and from v2.1.311 the word typed in the terminal can also raise that turn to xhigh effort (it shows in rainbow colors when it can). Other phrases such as “think”, “think hard”, and “think more” are passed through as ordinary text and are not recognized as keywords. The word ultracode triggers a dynamic workflow run — the trigger keyword was renamed from workflow to ultracode in v2.1.160. The word workflow no longer triggers a run; asking for one in your own words still works. Dynamic workflows are enabled with /effort ultracode — a slash command (the CLI form is claude --effort ultracode, not a bare --ultracode flag). /effort ultracode turns on automatic workflow orchestration at the session’s current effort level and doesn’t raise the effort level by itself; launching with claude --effort ultracode additionally sets effort to xhigh on models that support it (v2.1.203+). The /effort slider’s own keys are rebindable in keybindings.json as of v2.1.284: the effortSlider:decreaseEffort and effortSlider:increaseEffort actions move between levels (the arrow keys by default) and effortSlider:toggleUltracode toggles the ultracode run (the Tab key by default).
To put a ceiling on how much effort a session can use — leaving lower levels available but forcing any higher request down to the cap — set maxEffortLevel in settings.json (v2.1.267+) to low, medium, high, xhigh, or max (a value of max sets no cap). The cap overrides any higher level from /effort, the /model picker, --effort, CLAUDE_CODE_EFFORT_LEVEL, or the model’s own default, and Claude Code applies it before each request, so it holds on every provider — including Bedrock, Google’s Cloud Agent Platform, and Foundry. When several settings scopes set a cap the lowest one wins, so a cap set in one scope can’t be raised from another; deploy it in managed settings to enforce it across an organization. For a per-model cap, add a maxEffortLevel field to that model’s modelSettings entry.
MAX_THINKING_TOKENS=0 disables thinking on the Anthropic API on every model except Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable models (where thinking also cannot be disabled). For positive values, the fixed thinking budget mode only applies on the older, fixed-budget models: on Fable models, Sonnet 5 and later, Haiku 5.5, and Opus 4.7+, adaptive reasoning is always used, so positive MAX_THINKING_TOKENS values have no effect. On Opus 4.6 and Sonnet 4.6, which use adaptive reasoning by default, set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 first to revert to the fixed thinking budget that positive MAX_THINKING_TOKENS values control.
The combination of plan mode plus high effort is powerful for complex architectural decisions:
claude --permission-mode plan --effort high --model opusplan "migrate from REST to GraphQL"Fallback Model Chains
When the primary model is overloaded, unavailable, or returns another non-retryable server error, Claude Code can switch to a fallback model instead of failing the request. Authentication, billing, rate-limit, request-size, and transport errors never trigger a switch — those follow normal retry and error handling. Configure one or more fallback models and Claude Code tries them in order, showing a notice when it switches. The switch lasts for the current turn only, so your next message tries the primary model first again. Chains are capped at three models after duplicate removal, and extra entries are ignored.
Set a chain for a single session with the --fallback-model flag, which accepts a comma-separated list:
claude --fallback-model sonnet,haikuTo persist a chain across sessions, set fallbackModel in settings as an array:
{
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}The --fallback-model flag takes precedence over the fallbackModel setting. Each element accepts a model name or alias, and "default" expands to the default model for your account type. That default is currently Opus 5.5 (claude-opus-5-5) on Pro, Max, Team, Enterprise, and Anthropic API accounts and on the AWS, Bedrock, and Google Cloud platforms, while Microsoft Foundry defaults to Sonnet 4.5. The opus alias resolves to the newest Opus version on the Anthropic API and on Claude Platform on AWS — currently Opus 5.5 — but to an older model on some providers, so on Microsoft Foundry opus resolves to Opus 4.6. Pin an exact model ID, or set ANTHROPIC_DEFAULT_OPUS_MODEL, wherever you need a specific version.
Haiku 5.5, the newest small model, is available as claude-haiku-5-5 — switch to it with /model claude-haiku-5-5 in a session or launch with claude --model claude-haiku-5-5 (requires Claude Code v2.1.293 or later). On the Anthropic API it runs with a 1M-token context window on every plan, with no [1m] suffix to select; a request whose prompt is longer than 100K tokens costs more per token.
Auto Mode and Permission Control
Auto Mode is a permission mode that uses a background safety classifier to decide whether tool calls are safe to run without prompting. With Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions. It’s designed for higher-autonomy workflows where you still want guardrails around risky actions.
You use it the same way as the other permission modes: select auto in your permission settings or cycle to it with Shift+Tab when that mode is available in your setup. Organizations can tune what Auto Mode treats as trusted infrastructure with the autoMode settings block.
Out of the box, Auto Mode is conservative around actions that look like data exfiltration, risky shell execution, or production-impacting changes. When a permission check stalls, the spinner turns red — making it clear that a check is in progress rather than a tool running. If your team has trusted repos, internal domains, buckets, or services that Auto Mode should treat as normal, define them in autoMode.environment.
Before Auto Mode allows a file read outside your working directories, it asks first. As of v2.1.284 that prompt offers four answers — “Yes, and keep allowing any reads outside the working directories”, “No, and block reads outside the working directories from now on”, “No, and ask again next time”, and “Yes, but ask again next time” — so you can allow that one read without silencing the prompt for every later read outside the working directories.
When customizing autoMode.allow, autoMode.soft_deny, autoMode.hard_deny, or autoMode.environment, include the special "$defaults" token to keep the built-in rules and add yours alongside them. Without "$defaults", your array replaces the defaults entirely.
Inside the classifier, precedence works in four tiers: hard_deny rules block unconditionally (user intent and allow exceptions do not apply). soft_deny rules block next, but user intent and allow exceptions can override them. allow rules then override matching soft_deny rules. Explicit user intent overrides remaining soft blocks — asking Claude to “force-push this branch” clears the soft block, but a vague “clean up the repo” does not. If the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. These thresholds are not configurable.
Use claude auto-mode defaults to print the built-in rules, claude auto-mode config to see your effective merged config, and claude auto-mode critique for AI feedback on your custom rules:
{
"autoMode": {
"allow": ["$defaults", "Deploying to staging is allowed"],
"soft_deny": ["$defaults", "Never run migrations outside the migrations CLI"],
"hard_deny": ["$defaults", "Never send repo contents to third-party APIs"],
"environment": ["$defaults", "Internal API: api.corp.example.com"]
}
}As of v2.1.246, /permissions includes an Auto mode tab for viewing and editing these classifier rules directly in the interface — an interactive alternative to the claude auto-mode commands and hand-editing the autoMode settings block.
/auto-mode-setup is the guided version of the same job. Run it and Claude Code drafts autoMode.environment entries — and sometimes rule entries too — from your project and your recent sessions in it, then writes the draft to ~/.claude/settings.json if you accept it:
/auto-mode-setupThe command needs v2.1.228 or later (v2.1.233 on native Windows) on Pro, Max, and Team plans, and v2.1.283 or later on Enterprise plans or with a Claude Console API key. As of v2.1.304 it also works on Bedrock, Vertex, Foundry, Claude apps gateway, and telemetry-disabled sessions.
Permission modes span a spectrum. default reads freely but prompts for actions beyond that. acceptEdits auto-approves file edits for the session, except writes to protected directories. plan switches into planning-first research mode. auto uses the classifier. dontAsk only runs pre-approved tools and denies everything else. bypassPermissions skips most permission prompts — writes to protected paths are also included as of v2.1.126. The --dangerously-skip-permissions flag is a shorthand for --permission-mode bypassPermissions — the deliberately alarming name makes the security trade-off explicit, so reserve it for trusted CI/CD pipelines.
Start a session in any mode with the --permission-mode <mode> flag. It accepts default, acceptEdits, plan, auto, dontAsk, or bypassPermissions, and overrides defaultMode from your settings files for that run — so you can pin a stricter mode for one-off automation without editing config. The same flag works with -p for non-interactive runs, and dontAsk only ever activates through this flag (it’s not in the Shift+Tab cycle):
claude --permission-mode plan "draft the migration"
claude -p "audit dependencies" --permission-mode dontAskSet a default in settings so most sessions start in the mode you want without passing the flag:
{
"permissions": {
"defaultMode": "acceptEdits"
}
}To customize Auto Mode for your environment:
{
"autoMode": {
"environment": [
"Source control: github.example.com/acme-corp and all repos under it",
"Trusted internal domains: *.corp.example.com, api.internal.example.com"
]
}
}On the Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry, Auto Mode is available by default once your account meets the model and admin requirements (on Team and Enterprise it is available by default too — there is no Owner opt-in step, and administrators turn it off with permissions.disableAutoMode: "disable" in managed settings). The CLAUDE_CODE_ENABLE_AUTO_MODE=1 opt-in that additionally gated the three non-Anthropic providers in v2.1.158–v2.1.206 was removed in v2.1.207 — the variable is still accepted for backwards compatibility but has no effect. On those three providers, only Claude Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and the Fable models are supported. Older models, including Sonnet 4.5, Opus 4.5, Haiku 4.5, and claude-3 models, are not supported on any provider. permissions.disableAutoMode: "disable" also removes auto mode from the Shift+Tab cycle. A session starts in default (Manual) mode instead of auto mode when a settings file sets permissions.disableAutoMode to "disable", when the active model is not one auto mode supports on that provider, or when the session isn’t an interactive terminal or VS Code extension session — claude -p and Agent SDK runs start in default by default. A session whose organization has the HIPAA configuration applied also starts in default, with Claude Code v2.1.285 or later, and auto mode stays available to switch to. And when auto mode isn’t available to a session at all — including the case where Anthropic has temporarily turned it off server-side — the session starts in Manual instead. Otherwise, on Claude Code v2.1.283 or later, interactive sessions on Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and signed-in Claude apps gateway sessions start in auto mode by default.
As of v2.1.278, on Enterprise plans, Claude API accounts, and the AWS, Bedrock, Vertex, and Foundry platforms (subject to each platform’s rollout), auto mode asks the server to run its classifier safety checks as part of the session’s normal model requests — and doesn’t charge for them. When those server-side checks can’t reach a session (most often an LLM gateway or proxy in the path), Claude Code falls back to its own classifier requests, billed as before, and /status shows an Auto mode server row reading Enabled or Disabled. If you already know your gateway can’t pass the checks through, set CLAUDE_CODE_AUTO_MODE_SERVER=0 before starting the session to always use Claude Code’s own requests. On a direct connection to the Anthropic API the variable is read from Claude Code v2.1.281 or later, where setting it to 1 turns server review on in a session that doesn’t have it yet, and setting it to 0 skips asking the server. It’s also temporary — it may be removed in a later release, so don’t build managed policy around it.
CLAUDE_CODE_AUTO_MODE_MODEL sets the model for the classifier requests Claude Code sends in auto mode — use a full model ID such as claude-sonnet-4-6. It does not change the model for server-side auto mode, and the official reference lists the remaining cases where Claude Code ignores it. Requires Claude Code v2.1.302 or later.
Two recently added settings are worth noting: enforceAvailableModels (v2.1.175) extends the availableModels allowlist to also constrain the Default model, not just alternate models. footerLinksRegexes (v2.1.176) adds regex-matched link badges to the footer row for custom integrations.
The parentSettingsBehavior managed setting (v2.1.133, admin-tier) controls how SDK/IDE-supplied parent-tier settings — such as those set by embedding hosts — interact with admin-deployed managed policies. The default 'first-wins' ignores parent-supplied settings entirely, so only the admin tier applies. Setting it to 'merge' layers those parent settings beneath the admin policy through a restrictive-only filter: they can tighten the policy (for example, unioning deny lists) but never loosen it. The setting has no effect unless an admin tier is deployed — without one, 'first-wins' behavior remains in force.
A self-hosted Claude apps gateway — the service that sits between developers’ clients and the model provider and enforces managed settings by identity-provider group — describes those per-group rules in a managed.policies[] array. As of v2.1.296 each policy entry accepts cli, code, and desktop blocks: code holds the same managed-settings document as cli, while desktop is what opts Claude Desktop in to the gateway. The code settings reach Claude Desktop’s Code tab only when the policy also has a desktop key and the user’s machine is set up for it; they never reach Cowork or Chat.
policy_mode: layered changes how the gateway stacks those per-group rules. By default a user who matches several role policies gets only the first; set policy_mode: layered beside policies and every policy that matches the user applies instead — down to the first match: {} catch-all, so a role policy listed after the catch-all never applies. The setting needs Claude Code v2.1.316 or later on the gateway server: a gateway on an older version refuses to start when it finds the key, so upgrade every replica before you add it and remove it before you roll back.
Each upstream has its own base_url. You can point a provider: anthropic upstream’s base_url at a proxy you run instead of at the Anthropic API.
On the developer side, allowedProviders is a managed list of the providers a machine may reach Claude through. To stop developers from bypassing the gateway with a cloud provider variable or an ANTHROPIC_BASE_URL of their own, add "allowedProviders": ["gateway"] to the client-side managed-settings.json on each developer machine — not to the gateway server’s own configuration. Claude Code then refuses every session on the machine that isn’t set up for a Cloud gateway, and admits a gateway only when it is the one forceLoginGatewayUrl names or one whose URL the file’s env block sets as ANTHROPIC_BASE_URL. claude gateway refuses to run on a machine that sets the list, so keep the key off the gateway host.
Model Access Controls
Two managed settings added in v2.1.283 give administrators tight control over which models Claude Code can use, layered on top of the existing availableModels allowlist and enforceAvailableModels (v2.1.175).
availableModelsMatch controls how an availableModels entry is matched against the actual model. With "exact", an entry allows only the model version it names — new model releases stay blocked until they’re listed in availableModels. This is the strictest match mode: it stops an availableModels allowlist from being silently widened by an auto-updated model alias.
deniedModels blocks specific models even when availableModels allows them. Use it for explicit denies such as retiring a model or restricting access to a more expensive variant. enforceAvailableModels (v2.1.175) extends the availableModels allowlist to also constrain the Default model — without it, the Default model is unaffected and an admin can block a single experimental model without locking down the everyday one.
{
"availableModels": ["claude-sonnet-4-5", "claude-haiku-4-5"],
"availableModelsMatch": "exact",
"deniedModels": ["claude-opus-4-1"]
}A non-string availableModelsMatch value is treated as exact until the setting is fixed. A non-string entry in deniedModels is stripped and the rest of the list is enforced; a wholly invalid value is dropped with a warning and blocks no models until it is fixed.
Restricted Mode
--restricted starts Claude Code in a hardened mode — its documented use is when an evaluation harness drives claude on a shared machine and Claude Code must not run commands or read that machine’s settings. It removes the built-in tools for running commands or code, and WebFetch, unless they’re explicitly named in --tools. The remaining file tools stay confined to the working directory, bypassPermissions is refused even if requested later, and only managed settings and --settings are loaded — the user, project, and local settings files are ignored for the session. This makes it useful for ephemeral or untrusted execution contexts where the surface area needs to be as small as possible:
# Run a one-off task without bringing in shell, code-execution, or fetch tools
claude --restricted -p "summarize the contents of README.md"Use --restricted when you want the session to start without the built-in command, code-execution, and WebFetch tools; other built-in tools remain available even when not listed in --tools. The remaining file tools stay confined to the working directory, so this narrows the surface area rather than fully isolating it. To make a removed tool available inside restricted mode, add it to --tools:
claude --restricted --tools "Bash,WebFetch" -p "fetch and summarize today's commits"Programmatic and Sandboxed Operation
Running Claude Code programmatically with claude -p "your prompt" executes it non-interactively. Output goes to stdout, making it composable with shell pipelines and automation systems. Combine it with --output-format json for structured output. Use --permission-mode bypassPermissions for fully automated CI/CD use. Hooks running in these sessions can read the active effort level via the $CLAUDE_EFFORT environment variable.
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS sets the minimum interval in milliseconds between checks of whether a usage limit was already lifted, while a request waits for that limit to reset with CLAUDE_CODE_RETRY_WATCHDOG set. When a check finds the limit lifted, the request goes out at once instead of waiting out the rest of the interval. Give it a whole number in plain digits, from 60000 (one minute) to 10800000 (three hours).
/cd <directory> moves a session to a new working directory without breaking the prompt cache mid-session.
# Automated code review in CI
git diff HEAD~1 | claude -p "review these changes for security issues" \
--output-format json \
--permission-mode bypassPermissions
# Generate docs for changed files
claude -p "generate JSDoc for all functions in $CHANGED_FILE" \
--print --no-session-persistenceSandboxing provides OS-level isolation for file system and network access. Sandboxed Bash is available on macOS, Linux, and WSL2. Native Windows is not supported; on Windows, run Claude Code inside a WSL2 distribution. Enable it with /sandbox in-session. In sandbox mode, Claude can only access approved paths and network rules you configure. This is valuable for running Claude on untrusted code or in environments where you want strict boundaries.
Fine-tune network isolation with sandbox.network.allowedDomains and sandbox.network.deniedDomains in your settings.json. allowedDomains whitelists domains for outbound traffic, while deniedDomains blocks specific domains even when a broader wildcard in allowedDomains would permit them — deniedDomains always takes precedence. Both support wildcards like *.example.com:
{
"sandbox": {
"enabled": true,
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"],
"deniedDomains": ["uploads.github.com"]
}
}
}In managed deployments, deniedDomains is merged from all settings sources (managed, user, project, local) regardless of allowManagedDomainsOnly. That flag only restricts which scopes allowedDomains is read from — deny rules from any scope are always honored, so a user-level block cannot be silently dropped by enterprise policy.
sandbox.network.strictAllowlist (v2.1.219) adds a stricter isolation mode: when enabled, all hosts not in allowedDomains are denied without prompting. This is useful for high-security sandboxed environments where you want guaranteed network containment with no interactive exceptions.
On Linux and WSL, use sandbox.bwrapPath and sandbox.socatPath to specify custom binary locations for bubblewrap and socat:
{
"sandbox": {
"bwrapPath": "/usr/local/bin/bwrap",
"socatPath": "/usr/bin/socat"
}
}sandbox.allowNestedUserNamespaces (v2.1.305+) lets a sandboxed command create nested user namespaces on Linux and WSL2. Set it to true in ~/.claude/settings.json — not in the project’s .claude/settings.json, which a repository cannot use for it — to keep Chromium’s or Electron’s own sandbox, or to run a nested bubblewrap or unshare:
{
"sandbox": {
"allowNestedUserNamespaces": true
}
}With it on, do not rely on protected paths: code from a sandboxed command can end up running outside the sandbox.
For enterprise deployments, managed settings override user settings through platform-native management: plist on macOS, Registry on Windows, managed configuration files, and managed-settings.d/ drop-ins merged alphabetically. That’s separate from managed memory files such as organization-level CLAUDE.md guidance.
# Test headless with sandboxing (sandbox.enabled: true in a settings file)
claude -p "analyze the security of this codebase" \
--permission-mode plan \
--output-format jsonHooks
Hooks let you react to events during a Claude Code session. The DirectoryAdded hook (v2.1.219) fires after /add-dir or the SDK register_repo_root control request registers an additional working directory mid-session — it responds to a directory being added to the session (expanding the files Claude can reach), not to a change of the session’s current directory. This is useful for scripts that need to track or reconfigure whenever a new directory is registered.
Advisor Tool (Experimental)
The Advisor Tool is an experimental dual-model feature that lets a faster, lower-cost executor model (like Sonnet) consult a higher-intelligence advisor model (like Opus) mid-task for strategic guidance. The advisor reads the full conversation and produces a plan or course correction, then the executor continues with the task. This pattern fits long-horizon agentic workloads where most turns are mechanical but having an excellent plan is crucial.
Enable it with the /advisor command. When active, sessions show an “experimental” label and a startup notification. The executor model is set as the main session model, and the advisor model is selected through the /advisor dialog. The Advisor Tool is enabled via the /advisor command, the advisorModel setting, or the --advisor flag. The only advisor-related environment variable is CLAUDE_CODE_DISABLE_ADVISOR_TOOL, which disables the tool rather than enabling it.
Native Glob and Grep on macOS/Linux
On native macOS and Linux builds, the Glob and Grep tools are replaced by embedded bfs and ugrep binaries available through the Bash tool. The result is faster file searches without a separate tool round-trip — Claude issues a single Bash command instead of calling a dedicated tool, which reduces latency on large codebases.
Windows and npm-installed builds are unaffected and continue using the original Glob and Grep tools. The environment variables CLAUDE_CODE_GLOB_HIDDEN, CLAUDE_CODE_GLOB_NO_IGNORE, and CLAUDE_CODE_GLOB_TIMEOUT_SECONDS still apply to the original tools where they remain in use.
Session Cleanup with cleanupPeriodDays
The cleanupPeriodDays setting in settings.json controls how long session files are retained before automatic deletion at startup. The default is 30 days and the minimum is 1 — setting it to 0 is rejected with a validation error. The setting also controls automatic removal of orphaned subagent worktrees (from crashes or interrupted parallel runs) at startup, provided they have no uncommitted changes, no untracked files, and no unpushed commits. Worktrees you create with --worktree are not removed by this sweep unless you background that session — the sweep leaves a worktree in place when it belongs to a --worktree session you haven’t backgrounded, but when you background a --worktree session its worktree becomes a background-session worktree that the sweep can remove. Configure the retention period like this:
{
"cleanupPeriodDays": 14
}To keep transcripts from being written at all in non-interactive mode, use --no-session-persistence.
Project Purge
When cleanupPeriodDays isn’t enough and you want to wipe all Claude Code state for a project right now, use claude purge. The command was renamed from claude project purge in v2.1.288 — the old name still works but prints a notice. It deletes transcripts, task lists, debug logs, file-edit history, prompt history, and the project entry itself:
# Preview what would be deleted
claude purge --dry-run
# Purge state for the current project
claude purge
# Skip the confirmation prompt
claude purge --yes
# Interactively choose which items to remove
claude purge --interactive
# Purge state for every project at once
claude purge --allFlags can be combined: claude purge --all --dry-run previews what a full wipe would remove. The -y and -i short forms work too.
Debugging and Platform Environment Variables
A few environment variables unlock surfaces that aren’t exposed as commands or settings yet.
OTEL_LOG_RAW_API_BODIES=1 emits full API request and response bodies as OpenTelemetry log events — set it when debugging why a request failed or what exactly Claude sent to the model. Be careful with the logs afterwards since request bodies can contain secrets.
OTEL_RESOURCE_ATTRIBUTES adds custom comma-separated key=value pairs (no spaces, percent-encode special characters) that Claude Code attaches as labels on every metric datapoint and event, in addition to sending them in the OTLP resource block. Use it to slice metrics by team, department, or cost center in your backend — department=engineering,team.id=platform,cost_center=eng-123. Custom keys never override built-in attributes like user.id or session.id. To keep custom attributes in the resource block only and skip the per-datapoint label (lower cardinality, cheaper storage), set OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false.
OTEL_METRICS_INCLUDE_REPOSITORY=true (requires Claude Code v2.1.269+, off by default) tags every metric and event with the session’s repository identity — vcs.repository.url.full, vcs.owner.name, vcs.repository.name, and vcs.provider.name — derived once per session from the origin remote, so a shared collector can attribute usage per repository. Commit events additionally carry vcs.ref.head.* when OTEL_LOG_TOOL_DETAILS is set. It stays false by default, keeping repository names out of your telemetry unless you opt in.
OTEL_LOG_TOOL_CONTENT=1 adds a tool.output span event on claude_code.tool carrying the file contents, Bash output, and what MCP tools, WebFetch, and WebSearch return — truncated at 60 KB by default, configurable via CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH (which itself requires Claude Code v2.1.214 or later). Results from MCP tools, WebFetch, and WebSearch specifically require Claude Code v2.1.283 or later. The span attributes carry tool content under their own gates, and tracing must be enabled.
The OpenTelemetry tool_decision event records how each permission check was resolved. Three attributes make auto mode decisions legible in your traces: classifier_verdict carries the auto mode classifier verdict for the call, or why Claude Code denied the call when none came — allow when the classifier approved the call, block when it blocked it; classifier_category names the built-in rule the classifier named when it blocked the call, in lowercase with underscores, such as data_exfiltration for the Data Exfiltration rule, and needs OTEL_LOG_TOOL_DETAILS=1; and permission_mode records the permission mode active when the call’s permission check began — default, plan, acceptEdits, bypassPermissions, dontAsk, or auto, where manual mode appears as default and a subagent call reports the subagent’s permission mode rather than the session’s. Requires Claude Code v2.1.301 or later.
CLAUDE_CODE_USE_POWERSHELL_TOOL=1 enables the PowerShell tool on Linux, macOS, and WSL (requires pwsh on PATH). On Windows without Git Bash the tool is enabled automatically; set 0 to disable it. On Windows with Git Bash installed it is on by default for claude.ai and Console accounts; set 1 to enable it in Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry sessions, or 0 to turn it off. With the tool enabled on Windows, Claude can run PowerShell commands natively instead of routing through Git Bash.
DISABLE_UPDATES=1 blocks all update paths, including manual claude update. This is stricter than DISABLE_AUTOUPDATER (which only blocks auto-updates) and is intended for locked-down enterprise deployments where the installed version must not change.
CLAUDE_CODE_SAFE_MODE=1 or --safe-mode starts Claude Code with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled for troubleshooting — useful when debugging unexpected behavior or a broken configuration.
CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 or disableBundledSkills in settings hides bundled skills, workflows, and built-in slash commands from the model.
CLAUDE_CODE_HIDE_CWD=1 hides the working directory from the startup logo banner. Useful for screen recordings or presentations where you don’t want to leak path information.
CLAUDE_CODE_NATIVE_CURSOR=1 shows the terminal’s own cursor at the input caret instead of Claude Code’s drawn block. The native cursor respects the terminal’s blink, shape, and focus settings — useful when your terminal is configured for a specific cursor style or accessibility need.
CLAUDE_AX_SCREEN_READER=1 (or the --ax-screen-reader flag) renders screen-reader-friendly output: flat text with no decorative borders or animations, for use with assistive technology. The same mode is available as the axScreenReader setting (v2.1.181+), but the environment variable and CLI flag take precedence over it. Screen-reader mode always uses the classic renderer, so the fullscreen/tui renderer preference has no effect while it is active.
CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE was removed in v2.1.160 and is now a no-op.
CLAUDE_CODE_RESUME_PROMPT overrides the continuation message Claude injects when resuming a session that ended mid-turn. The default is Continue from where you left off.. Long-running spawn scripts can set a more directive boot message; an empty string falls back to the default.
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS (v2.1.296+) raises the ceiling on the exponential backoff between automatic retries of a request the API rejects with a 529 overloaded error. In place of the default 32000, give whole milliseconds from 32000 to 64000 so later retries keep spreading apart when the API is at capacity. Its companion CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS (v2.1.292+) sets the starting delay in place of the default 500 (range 500 to 32000). Both are ignored when CLAUDE_CODE_RETRY_WATCHDOG=1 or the request was sent in fast mode, and a value outside the allowed range is treated as unset.
CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1 routes the “How is Claude doing?” session quality survey to your own OpenTelemetry collector when Anthropic-bound nonessential traffic is blocked. Survey ratings are emitted only as OTEL events to your configured collector — no survey data is sent to Anthropic. It applies when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, or DO_NOT_TRACK is set, and has no effect otherwise. CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY and your organization’s product feedback policy still take precedence.
ANTHROPIC_WORKSPACE_ID is the workspace ID used by workload identity federation. Set it when your federation rule is scoped to more than one workspace so the token exchange knows which workspace to target — without it, an over-scoped rule has no way to pick a workspace and the exchange fails. Leave it unset when your federation rule is scoped to exactly one workspace.
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 opts into a set of x-claude-code-* gateway hint headers so LLM gateways can group the requests that serve one user prompt and inspect their routing context. Enabling it sends x-claude-code-prompt-id, and from v2.1.273 also the five additional headers x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction, and x-claude-code-context-compacted. By default the headers depend on where the request goes: on a direct connection to the Anthropic API they are sent by default, on a custom base URL they are off by default, and on any other backend — Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and Claude Platform on AWS — they are sent only when CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 is set. Setting the variable to 0 stops the headers on every connection. Enable the opt-in when your gateway needs to correlate the multiple internal requests that result from a single user prompt or surface routing metadata alongside the prompt ID.
CLAUDE_CODE_ATTRIBUTION_HEADER=0 omits the attribution block, which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on auto mode classifier requests even when you set 0, so it is not a blanket “no attribution” switch — the docs’ System prompt attribution block section lists which connections and credentials the block covers.
CLAUDE_CODE_GZIP_REQUEST_BODIES=0 turns off gzip compression of Claude API, telemetry, and artifact publish request bodies sent to api.anthropic.com. By default, Claude Code compresses large request bodies on direct connections, and skips compression when you send requests through a proxy, configure a client certificate, or set NODE_EXTRA_CA_CERTS — set it to 0 when a TLS-inspecting proxy that Claude Code cannot detect mishandles compressed requests. New in Claude Code v2.1.300, where large requests are compressed even when telemetry is disabled.
CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT (added in v2.1.312) chooses between Claude Code’s full system prompt and a shorter one with abbreviated tool descriptions. When unset, Haiku 4.5, Sonnet 5, Opus 4.7, and earlier models in those families use the full prompt by default, and newer models use the shorter one. Set it to 1 to use the shorter prompt on any model, or to 0 (also false, no, or off) to use the full prompt on any model, even where an experiment or server configuration would otherwise select the shorter one. Either prompt keeps the full tool set, hooks, MCP servers, and CLAUDE.md discovery.
CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1 turns off the automatic model switch when a safety classifier flags a request — the same behavior the switchModelsOnFlag setting controls. It was added in v2.1.312.
CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST is set by host platforms that embed Claude Code and manage model provider routing on its behalf. When it is set, Claude Code ignores provider-selection, endpoint, and authentication variables such as CLAUDE_CODE_USE_BEDROCK, ANTHROPIC_BASE_URL, and ANTHROPIC_API_KEY in settings files, so user settings cannot override the host’s routing. It also ignores model-selection keys such as model, fallbackModel, and modelOverrides in managed settings — whichever managed source delivers them — so the host’s model configuration takes precedence over an out-of-date managed model pin.
# Drop the attribution block from the start of the system prompt
CLAUDE_CODE_ATTRIBUTION_HEADER=0 claude
# Capture full OTEL telemetry while reproducing an API bug
OTEL_LOG_RAW_API_BODIES=1 claude --print 'reproduce the failure'
# Slice metrics by team and cost center in your OTEL backend
OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123" \
claude
# Attribute telemetry per repository in a shared collector
OTEL_METRICS_INCLUDE_REPOSITORY=true claude
# Capture tool output (file contents, Bash, MCP/WebFetch/WebSearch results) in OTEL spans
OTEL_LOG_TOOL_CONTENT=1 claude
# Enable PowerShell tool on macOS or Linux
CLAUDE_CODE_USE_POWERSHELL_TOOL=1 claude
# Block all updates on a locked-down machine
DISABLE_UPDATES=1 claude
# Hide the working directory in the startup banner
CLAUDE_CODE_HIDE_CWD=1 claude
# Use the terminal's own cursor at the input caret
CLAUDE_CODE_NATIVE_CURSOR=1 claude
# Override the resume continuation message for an agent boot script
CLAUDE_CODE_RESUME_PROMPT="Resume the migration and stop after the next test run." \
claude --resume
# Route the session quality survey through your OTEL collector
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1 claude
# Workload identity federation with a multi-workspace rule
ANTHROPIC_WORKSPACE_ID=ws_01abcd... claudeBehind a gateway, Claude Code retries a request the upstream rejects. When the upstream rejects output_config.effort or its anthropic-beta value, Claude Code retries and adds neither to requests for that model until Claude Code exits. Your gateway needs no change if it forwards the upstream’s 400 unmodified and the message: the message starts with Unexpected value(s) and lists effort-2025-11-24 for the anthropic-beta header. That handling requires v2.1.310 or later. Developers whose ANTHROPIC_BETAS lists the value keep sending it and getting the 400, so have them remove that entry.
The same retry applies to mid-conversation system messages. When the upstream rejects a role: "system" entry inside messages, Claude Code retries once without those mid-conversation system messages and carries their text in user messages instead. Later requests in the conversation keep that shape until the developer runs /clear or the conversation compacts.
Sizing Inline Command Output
When a Bash command finishes, Claude Code reads only part of a long result back into the conversation — enough to work with, capped so a runaway command can’t flood the context. The default cap is 30,000 characters. To let Claude see more of a valid result inline, set bashOutputMaxChars (v2.1.261+) in settings.json, up to 128,000 characters. It sizes the inline ceiling and the read-back window together and takes precedence over the older BASH_MAX_OUTPUT_LENGTH environment variable, which Claude Code then ignores.
{
"bashOutputMaxChars": 128000
}Claude Code on the Web and Session Handoff
Claude Code on the web runs tasks on Anthropic-managed cloud infrastructure at claude.ai/code. Cloud sessions persist even when you close your browser, and you can monitor them from the Claude mobile app.
Launch a cloud session from your terminal with claude --cloud "your task" (the canonical flag; claude --remote is a deprecated alias that still works). Claude clones your repo from GitHub (push local commits first), executes the prompt autonomously, and can open PRs when done. Use multiple --cloud calls to run tasks in parallel.
/teleport (alias /tp) pulls a cloud session back into your local terminal — it fetches the branch, loads the full conversation history, and lets you continue locally. There is no reverse direction from the CLI: claude --cloud (with --remote as a deprecated alias) starts a new cloud session from a task description, and you can’t push an existing terminal session to the cloud. The Desktop app can send a local session to the cloud from its Code tab, so the round trip works only when you re-create the task in the cloud yourself.
/autofix-pr spawns a cloud session that watches your current PR. When CI fails or reviewers leave comments, Claude investigates and pushes a fix. Pass a prompt to narrow its scope: /autofix-pr only fix lint and type errors. Requires the Claude GitHub App installed on the repository.
# Plan locally, execute in the cloud
claude --permission-mode plan
# ... finalize plan, commit, push ...
claude --cloud "Execute the migration plan in docs/migration-plan.md"
# Pull the cloud session back when done
/teleportCloud sessions include standard runtimes (Node.js, Python, Go, Rust, Java, Ruby, Docker, PostgreSQL), up to 16 GB RAM, and configurable network access levels. Repo-level configuration (CLAUDE.md, settings, MCP servers, skills) carries over automatically. User-level settings (~/.claude/) do not — commit project config to the repo.
The cloud image also bundles a headless browser: Chrome for Testing at /usr/bin/google-chrome, with the CHROME_PATH environment variable set to that path. You don’t have to download a browser — point your tooling at the pre-installed one. Tools that honor CHROME_PATH (Lighthouse and other chrome-launcher-based tools) pick it up automatically; Playwright needs it passed explicitly as the launch option (chromium.launch({ executablePath: process.env.CHROME_PATH })), and Puppeteer reads PUPPETEER_EXECUTABLE_PATH, so set that to the same path. With the tool pointed at it, “fix the failing e2e tests” or “take a screenshot of the homepage” works in a cloud session without installing a browser first.
If custom roles govern your access, you also need a role with the cloud sessions permission to start sessions on Anthropic’s infrastructure from the browser, apps, or terminal. Ask an Owner to add it to one of your roles at Organization settings > Roles.
Remote Control has its own permission as well. Your roles must give you both the cloud sessions permission and the Claude Code remote control permission. If either is missing, starting Remote Control shows Remote Control is disabled by your organization’s policy. Ask an Owner to check your roles and add what’s missing at Organization settings > Roles.
Launching the Claude Desktop App
claude --desktop (v2.1.285+) opens the Claude desktop app on the current directory and exits without starting a session in the terminal — the app starts its own session on that folder, so you don’t re-pick the project. Add --continue to open your most recent local session in the app instead, or --resume <session-id> to open a specific past session; here --resume takes a session id only, not a name or a transcript path. It takes no prompt and no other flags except --verbose and the --debug flags, since the app runs the session itself. Available on macOS and x64 Windows when you’re signed in with a Claude subscription:
# Open the desktop app on the current project
claude --desktop
# Open the desktop app and continue the most recent local session
claude --desktop --continue
# Open the desktop app on a specific past session
claude --desktop --resume <session-id>Where claude --cloud sends work out to a cloud session, --desktop moves a local session from the terminal into the desktop GUI without losing the directory or the session you point it at.
PR URL Customization
The prUrlTemplate setting in settings.json points the footer PR badge at a custom code-review URL instead of the default GitHub link. This is useful for teams using GitLab, Bitbucket, or an internal review tool:
{
"prUrlTemplate": "https://gitlab.example.com/org/repo/-/merge_requests/{number}"
}Commit and PR Attribution
By default Claude Code adds an attribution trailer to the commits it makes and an attribution line to the pull requests it opens. The attribution setting in settings.json controls both — set it to false to hide all commit and PR attribution:
{
"attribution": false
}For finer control, use the object form instead of the bare boolean. attribution.commit changes or hides the trailer added to commits, attribution.pr changes or hides the attribution line in pull request descriptions, and attribution.sessionUrl omits the claude.ai session link from cloud and Remote Control commits:
{
"attribution": {
"sessionUrl": false
}
}attribution replaces the deprecated includeCoAuthoredBy setting. One version caveat: older CLI releases skip a settings file that contains "attribution": false, so in a settings.json shared across machines that run different Claude Code versions, prefer the object form over the bare boolean.
Worktree Configuration
Git worktrees let you check out multiple branches simultaneously without stashing or branching. claude --worktree <name> creates a new worktree at <repo>/.claude/worktrees/<name>/, on a new branch named worktree-<name>. The worktree.baseRef setting (new in v2.1.133) controls which ref to branch from when creating a worktree. Set baseRef to fresh (origin/<default>, the default — branches from a clean tree matching the remote) or head (your local HEAD):
{
"worktree": {
"baseRef": "head"
}
}Setting head preserves unpushed local commits in new worktrees. This affects --worktree, EnterWorktree, and agent-isolation worktrees.
Computer Use (Research Preview)
Computer use lets Claude open apps, control your screen, and interact with GUIs on macOS — building a Swift app, launching it, clicking through every button, and screenshotting the result, all in the same conversation. It handles tasks that require a GUI: validating native app builds, end-to-end UI testing without a test harness, debugging visual layout issues, and driving GUI-only tools like design apps or the iOS Simulator.
Claude tries more precise tools first: MCP servers, Bash, or Chrome integration. Computer use is the fallback for things nothing else can reach — native apps, simulators, and tools without an API.
Enable it by running /mcp in a session, finding the computer-use server, and selecting Enable. The setting persists per project. On first use, macOS prompts for Accessibility and Screen Recording permissions. When Claude wants to control a specific app in a session, a prompt appears for you to approve — approvals last for the current session only. Apps with broad reach (terminals, Finder, System Settings) show extra warnings.
While Claude works, other visible apps are hidden so it only interacts with approved apps. Your terminal window stays visible and is excluded from screenshots. Press Esc anywhere or Ctrl+C to abort immediately. Only one session can control the machine at a time.
Computer use requires a Pro or Max plan, macOS, Claude Code v2.1.85+, and an interactive session (not available with -p). It’s not available on Team, Enterprise, Bedrock, Vertex AI, or Foundry.
Emoji Shortcodes
Claude Code turns emoji shortcodes into emoji as you type in the prompt input — a lightweight input convenience added in v2.1.217. Type a complete shortcode such as :heart: and Claude Code replaces it with ❤️ the moment you type the closing :. Type a : plus at least two characters of a name, such as :hea, to open a suggestion popup, then press Tab or Enter to insert the highlighted emoji. The shortcode must start the input or follow a space, so a : inside a word or a URL doesn’t open suggestions.
The feature is on by default. Turn it off by setting emojiCompletionEnabled to false in settings.json — that disables both the suggestion popup and the inline replacement:
{
"emojiCompletionEnabled": false
}More Advanced Features
Claude Code’s advanced toolkit goes further. Background tasks let long-running work continue while you keep chatting. Scheduled tasks support /loop for session-scoped recurring checks and /schedule for cloud-backed scheduled work. Session tools like /resume, /rename, and /teleport make it easy to move between local CLI, the browser, and the desktop app.
There are also platform features for daily use: voice dictation with /voice, Chrome integration with --chrome, remote control via /remote-control, the /powerup interactive feature discovery lessons, persistent task lists, and git worktree workflows with claude --worktree. These all share the same permission system, so advanced usage is mostly about combining the right mode with the right surface.
The VS Code extension typesets LaTeX math in Claude’s responses — the chat panel shows LaTeX math as typeset formulas rather than raw markup. In terminal mode, math isn’t typeset. Requires Claude Code v2.1.301 or later.