The complete guide to Claude Code. Opus 4.7, Sonnet 4.6, Haiku 4.5. 1M token context window. 27 hook events. 43 production-tested chapters across 6 topical Parts (Foundation, Workflow, Extension, Context Engineering, Advanced, Reference). Three install tiers. CC 2.1.121+ compatible.
A curated reference of Claude Code releases. Each entry highlights features that still matter in the current 2.1.121 line. Superseded features are noted once with their replacement.
For the definitive changelog, run /release-notes inside CC or see claude update output.
alwaysLoad: true MCP server config — opt a server out of ENABLE_TOOL_SEARCH deferral so its tools are always loaded. Use sparingly; each always-loaded tool consumes context every turn. Per-tool opt-in also available via _meta.anthropic/alwaysLoad: true in the tool definition.claude plugin prune (alias autoremove) removes auto-installed plugin dependencies that no longer have a parent. Flags: --dry-run (preview), --scope user|project|local (default user), -y (skip confirm — required when stdin is not a TTY). claude plugin uninstall --prune cascades the cleanup.hookSpecificOutput.updatedToolOutput now works for all tools (previously MCP-only). Hooks can rewrite or redact Bash, Read, Write, etc. output before it reaches the model./skills gains a type-to-filter search box for long lists.CLAUDE_CODE_FORK_SUBAGENT=1 works in non-interactive -p and SDK sessions.--dangerously-skip-permissions no longer prompts for writes to .claude/skills/, .claude/agents/, .claude/commands/.mcp_authenticate accepts redirectUri for custom scheme completion and claude.ai connectors.stop_reason, gen_ai.response.finish_reasons, and user_system_prompt (gated behind OTEL_LOG_USER_PROMPTS)./usage on machines with large transcript histories, leak when long-running tools fail to emit progress events.--resume failing on large/corrupt session transcripts; corrupt lines are now skipped.claude ultrareview [target] non-interactive CLI subcommand. Runs cloud multi-agent review on the current branch, a PR number, or a base branch. Flags: --json (raw bugs.json payload), --timeout <minutes> (default 30). Exits 0 on completion, 1 on failure. Suitable for CI gating; billed, so wire to manual triggers, not pre-push.${CLAUDE_EFFORT} substitution in skill content — skills can reference the active effort level (low|medium|high|xhigh|max) to weight their guidance.AI_AGENT env var set on subprocesses spawned by the Bash tool, so gh and similar tools can attribute traffic to Claude Code.claude plugin validate accepts $schema, version, description at the top level of marketplace.json and $schema in plugin.json./rewind and other interactive overlays not responding to keyboard input after claude --resume.DISABLE_TELEMETRY / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC not suppressing usage metrics for API/enterprise users.find in the Bash tool exhausting open file descriptors on large trees, causing host-wide crashes (macOS/Linux native builds)./config settings persist to ~/.claude/settings.json (theme, editor mode, verbose, etc.) and now participate in project/local/policy override precedence. Project .claude/settings.json still wins.prUrlTemplate setting points the footer PR badge at a custom code-review URL instead of github.com. Supports {host}, {owner}, {repo}, {number}, {url} placeholders.CLAUDE_CODE_HIDE_CWD env var hides the working directory in the startup logo (privacy/screencast). Does NOT affect statusline, OTEL spans, or hook stdin paths.--from-pr now accepts GitLab merge-request, Bitbucket pull-request, and GitHub Enterprise PR URLs. Auth inherits per-provider CLI credentials.--print mode honors the agent’s tools: / disallowedTools: frontmatter, matching interactive-mode behavior.--agent <name> honors the agent definition’s permissionMode for built-in agents.PowerShell(Get-ChildItem:*) allow, PowerShell(Remove-Item:*) deny.PostToolUse and PostToolUseFailure receive duration_ms in their JSON input (tool execution time only — excludes permission prompts and PreToolUse hooks).owner/repo#N shorthand links now use your git remote’s host (not always github.com).blockedMarketplaces correctly enforces hostPattern and pathPattern entries.tool_result and tool_decision events include tool_use_id; tool_result adds tool_input_size_bytes.effort.level and thinking.enabled.type: "mcp_tool" with ${tool_input.*} / ${cwd} templating. Replaces subprocess plumbing for MCP-writing hooks. Non-blocking on server disconnect; 60s default timeout; avoid on SessionStart (MCP servers typically not yet connected)./cost and /stats merged into /usage. Both remain as typing shortcuts that open the relevant tab./theme or hand-edit ~/.claude/themes/*.json. Plugins can ship themes via a themes/ directory.DISABLE_UPDATES env var blocks all update paths including manual claude update — stricter than DISABLE_AUTOUPDATER.wslInheritsWindowsSettings policy key."$defaults" placeholder — include in autoMode.allow / soft_deny / environment to extend the built-in list instead of replacing it.claude plugin tag creates release git tags for plugins with version validation.v) and visual-line mode (V) with selection, operators, and visual feedback.--continue / --resume finds sessions that added the current directory via /add-dir./fork writing the full parent conversation to disk per fork (now writes a pointer and hydrates on read).Stop / SubagentStop.bfs and ugrep replace Glob and Grep tools (available through the Bash tool). Faster searches without a separate tool round-trip. Windows and npm-installed builds unchanged./context 1M-window bug fixed — CC was computing /context % against a 200K window, inflating usage and triggering early autocompact. If you measured context baselines during 2.1.111–2.1.116 on Opus 4.7, re-measure.cleanupPeriodDays retention sweep extended to ~/.claude/tasks/, ~/.claude/shell-snapshots/, and ~/.claude/backups/ (previously only todos/).CLAUDE_CODE_FORK_SUBAGENT=1 enables forked subagents on external builds.mcpServers loads for main-thread agent sessions via --agent./resume offers to summarize stale, large sessions before re-reading them.high (was medium).user_prompt events include command_name and command_source for slash commands. cost.usage, token.usage, api_request, api_error include an effort attribute when the model supports effort levels. Custom/MCP command names redacted unless OTEL_LOG_TOOL_DETAILS=1./resume up to 67% faster on 40MB+ sessions; handles sessions with many dead-fork entries more efficiently.resources/templates/list deferred to first @-mention./doctor can be opened while Claude is responding (previously had to wait for turn)./reload-plugins and background auto-update now auto-install missing plugin dependencies from already-added marketplaces.gh commands hit GitHub’s API rate limit.rm / rmdir targeting /, $HOME, or other critical system directories.https://downloads.claude.ai/claude-code-releases.sandbox.network.deniedDomains setting blocks specific domains even when a broader allowedDomains wildcard would permit them./loop: pressing Esc cancels pending wakeups. Wakeups display as “Claude resuming /loop wakeup”.env / sudo / watch / ionice / setsid and similar exec wrappers.Bash(find:*) allow rules no longer auto-approve find -exec / -delete.dangerouslyDisableSandbox respects permissions (no silent bypass)./private/{etc,var,tmp,home} paths treated as dangerous removal targets under Bash(rm:*) allow rules.xhigh effort level, between high and max./effort slider for setting reasoning depth./less-permission-prompts skill: scans transcripts and proposes allowlist entries for .claude/settings.json./ultrareview cloud multi-agent review.--enable-auto-mode flag needed).plan-1.md./skills sort-by-token toggle.OTEL_LOG_RAW_API_BODIES env var for raw request/response debugging.CLAUDE_CODE_USE_POWERSHELL_TOOL./tui command and tui setting for fullscreen mode./focus split from Ctrl+O; Ctrl+O is now verbose-only.autoScrollEnabled setting./doctor warns on MCP-scope conflicts.TRACEPARENT and TRACESTATE from env.ENABLE_PROMPT_CACHING_1H (1-hour cache window) and FORCE_PROMPT_CACHING_5M env vars./recap command, default-on for telemetry-disabled users./undo aliased to /rewind./model warns on cache miss./resume prefers the current working directory./init, /review, /security-review) re-implemented via the Skill tool.PreCompact hooks can block compaction (exit 2 or {"decision":"block"}).description cap raised from 250 to 1536 characters.monitors manifest entry.WebFetch strips <script> and <style> before returning./doctor f applies auto-fixes./proactive aliased to /loop.EnterWorktree accepts a path parameter./team-onboarding skill generates a teammate ramp-up guide from local usage patterns.CLAUDE_CODE_CERT_STORE=bundled to restrict.API_TIMEOUT_MS is honored (previous 5-minute hardcoded timeout removed).settings.json. Only the bad entry is skipped. Audit hooks after upgrading — silently-dead hooks may start firing.permissions.deny now overrides a PreToolUse hook’s permissionDecision: "ask".claude mcp add).--resume <name> accepts session titles set via /rename or --name./team-onboarding command (see 2.1.101).--dangerously-skip-permissions being silently downgraded to accept-edits mode.permissions.additionalDirectories changes not applying mid-session.which fallback.echo x && killall node) now prompt in auto/bypass modes.killall\ node) no longer auto-allowed./dev/tcp and /dev/udp redirects prompt instead of auto-allowing.LANG=C killall node) prompts unless the var is known-safe (LANG, TZ, NO_COLOR, etc.).Bash(cmd:*) wildcards match extra spaces/tabs.CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 is set.CLAUDE_CODE_SCRIPT_CAPS=<N> limits per-session script invocations.TRACEPARENT to subprocesses. Opt-in span attributes: OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT (debug-only, never in shared config)./agents view split into Running and Library tabs.--exclude-dynamic-system-prompt-sections flag for print mode enables cross-user prompt caching.CLAUDE_CODE_NO_FLICKER=1 mode): clean view showing prompt, one-line tool summary with diffstats, and final response. (Split to dedicated /focus in 2.1.110.)refreshInterval setting re-runs the script every N seconds for live indicators.workspace.git_worktree field added to statusline stdin JSON — shows active worktree path. Important for multi-worktree setups.LANG=, NO_COLOR=, timeout)./agents view shows ● N running indicators for live subagent instances.AWS_BEARER_TOKEN_BEDROCK and CLAUDE_CODE_SKIP_BEDROCK_AUTH.medium to high for API-key, Bedrock, Vertex, Foundry, Team, and Enterprise users. Use /effort low to revert per-session.CLAUDE_CODE_USE_MANTLE=1.keep-coding-instructions frontmatter.Retry-After headers.CLAUDE_PLUGIN_ROOT is unset./cost per-model and cache-hit breakdown for subscription users./release-notes presents an interactive version picker.apply-seccomp helper ships in npm and native builds for Linux sandbox./tag and /vim removed. Editor mode now in /config._meta.anthropic/maxResultSizeChars.bin/ directory.disableSkillShellExecution setting blocks inline shell in skills/commands/plugins./powerup command: interactive lessons with animated terminal demos for CC features.--resume.cat/sed/head/tail without a prior Read call.{"defer": true} to pause headless -p sessions for later resume.sandbox.failIfUnavailable, managed-settings.d/ drop-in directory, disableDeepLinkRegistration, showThinkingSummaries (now OFF by default).MCP_CONNECTION_NONBLOCKING, CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE.Significant stability release. Highlights worth remembering:
if compound-command fix — if: "Bash(git *)" now correctly matches ls && git push, FOO=bar git push, etc. Hooks may now fire more often than before (correct behavior).file_path — Write/Edit/Read hooks now receive absolute paths, not relative.CLAUDE_CODE_NO_FLICKER=1 env var opts into alt-screen rendering with virtualized scrollback (reduces flicker, especially on WSL2). Tradeoff: scrollback discarded on exit.{retry: true} to allow retry.@ mention typeahead.showThinkingSummaries now OFF by default.computer-use MCP server./stats dropping subagent/fork tokens.wc -c loop over ~/.claude/skills/*/SKILL.md.@-mention content no longer JSON-escaped — token savings on @file references./skills sorted alphabetically..jj and .sl added to VCS exclusions (Jujutsu, Sapling).X-Claude-Code-Session-Id header for proxy session aggregation.if field for hooks on PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest. Uses permission-rule syntax (Bash(git *), Edit(*.ts)). Filters BEFORE process spawn — zero overhead for misses. Eliminates ~90% of wasted spawns in hooks that matched broadly and filtered internally.CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL available in MCP headers./compact failing on very large sessions.paths: frontmatter accepts YAML list on rules and skills. Domain-specific rules can now scope to file types (**/*.py, **/*.sh) so they only load when relevant.ENABLE_TOOL_SEARCH=true — previously the two were incompatible, forcing a choice between cache savings and deferred tools.typescript-lsp, pyright-lsp, gopls-lsp, rust-analyzer-lsp, clangd-lsp, ruby-lsp). Enable per-plugin in enabledPlugins.TaskCreated hook event./clear after 75+ minutes idle.CwdChanged (fires on directory change, useful for direnv allow) and FileChanged (fires on disk changes, enables hot-reload patterns).TaskOutput tool deprecated — use Read on the task’s output file path instead./ to search, n/N for next/previous.CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 strips API credentials from all subprocesses.CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS extends SessionEnd hook timeout beyond 1.5s default.initialPrompt: in frontmatter for autonomous first-turn dispatch./ causing hangs.sandbox.failIfUnavailable, managed-settings.d/, disableDeepLinkRegistration settings added.--bare flag: skips hooks, LSP init, plugin sync, skill-directory walks. Requires ANTHROPIC_API_KEY. For CI pipelines and scripted -p calls.--channels permission relay (GA) — routes approval prompts to a mobile notification channel.rate_limits field (5-hour and 7-day usage/limit).effort: in YAML frontmatter.source: 'settings' plugin marketplace declaration (groundwork for discovery).--resume dropping parallel tool results.claude auth login --console — terminal-only OAuth via paste-back code. For remote servers, Docker, CI./config./remote-control for VS Code.StopFailure hook event fires when CC stops from API error (rate limit, network, auth). Fills the gap between Stop (normal) and SessionEnd (always).${CLAUDE_PLUGIN_DATA} env var — per-plugin persistent state directory.effort, maxTurns, disallowedTools.sandbox.allowRead — grant read-only sandbox access to specific paths./copy N copies the Nth-latest response./branch (renamed from /fork) for conversation branch points.PostCompact hook event fires after compaction completes. Reload critical rules, CLAUDE.md, or state that compaction discarded. Pairs with PreCompact (save-before, restore-after)./effort low|medium|high slash command (xhigh added in 2.1.111).--name / -n flag and /rename command for session display names.worktree.sparsePaths setting — git sparse-checkout for large monorepo worktrees.Elicitation and ElicitationResult hook events.autoMemoryDirectory setting redirects auto-memory storage to a custom path./context command shows actionable diagnostics, not just token counts.autoMemoryDirectory, /context diagnostics.Features that shipped but have since been replaced or deprecated:
| Shipped | Feature | Replaced by |
|---|---|---|
| Pre-2.1.88 | Commands directory (commands/) |
Skills directory (skills/<name>/SKILL.md) |
| 2.1.83 | TaskOutput tool |
Read on the task’s output file path |
| Pre-2.1.92 | /tag, /vim commands |
Removed; editor mode via /config |
| 2.1.86 | 250-char skill description cap | Raised to 1536 in 2.1.105 |
| 2.1.88 | Ctrl+O = focus view | /focus command (2.1.110); Ctrl+O is verbose-only |
| 2.1.76 | /fork |
/branch |
| 2.1.118 | /cost, /stats commands |
/usage (both remain as typing shortcuts) |
| Pre-2.1.120 | Git for Windows requirement on Windows | PowerShell fallback when Git Bash absent (2.1.120) |
/release-notes inside CC for the interactive version picker (2.1.92+).