> esc

Claude Code / terminal reference

Built from Anthropic's official docs as of 7 November 2026 (Claude Code ~v2.1.319). Click any command to copy it. Things move fast — the source of truth is code.claude.com/docs, and inside a session /help plus typing / always shows what your build actually has.

Cheat sheet Cookbook Changes
what changed · 7 November 2026 · v2.1.319 ~7 changed all changes →

Recently added

New in the last 30 days. Each row also lives in its own section below.

/restartnewRestart Claude Code and resume this session, applying an installed update. Native install on macOS/Linux (not WSL), Pro/Max/Ultra. Alias /update. · in Session & context
/plugin-authoringskillnewLoad the reference Claude works from to write a mod. Claude normally loads it itself; it ships in a built-in plugin you can turn off in /plugin. · in Config & extensions
/artifact-capabilitiesskillnewLoad the reference for the runtime capabilities a published artifact can use, such as calling your connectors or offering a file download. · in Config & extensions
/artifact-diagrammingskillnewLoad diagramming guidance for artifacts: when a diagram helps, what to draw, and inline SVG that stays legible in light and dark themes. · in Config & extensions
"onFailure": "block"newHandler field on command and http hooks: block the action if the hook fails or times out. Default "continue" lets it through, so a broken policy hook fails open. · in Hooks

no matches in this section

Launch

Everything you can type before you're in a session.

claudeStart an interactive session in the current directory.
claude "query"Start interactive with an opening prompt.
claude -p "query"Non-interactive (print mode). Runs the query, prints, exits. The scripting entry point.
cat file | claude -p "query"Pipe stdin through Claude. Pairs with --output-format json.
claude -cContinue the most recent conversation in this directory.
claude -r "<session>" "query"Resume by session ID or name. No args opens the picker.
claude updateUpdate to the latest version.
claude gateway --config gateway.yamlStart the self-hosted Claude apps gateway server — for admins deploying SSO and policy in front of Claude Code on Bedrock, Vertex, or Foundry. --config is required.
claude install [version]Install/reinstall the native binary. Accepts stable, latest, or a pinned version.
claude doctorRead-only install + settings diagnostics without starting a session. (In-session /doctor can also fix things.)
claude import [source]Start a session that runs /import to bring in config from Codex, Gemini CLI, or Cursor. Takes --dry-run and --yes.
claude auth login | logout | statuslogin --console to bill via API instead of subscription. status prints JSON, exit 0 = logged in; since v2.1.318 its loginExpiresAt gives the date a stored claude.ai sign-in ends.
claude setup-tokenGenerate a long-lived OAuth token for CI/scripts.
claude agentsOpen agent view: monitor and dispatch parallel background sessions. --json for scripting.
claude attach <id|name>Attach to a background session in this terminal. Part of a running session's name works in place of the ID (v2.1.290+).
claude logs <id|name>Print recent output from a background session. Part of a session's name works in place of the ID (v2.1.290+).
claude stop <id> / claude rm <id>Stop a background session / remove it from the list (transcript survives).
claude respawn <id>Restart a background session with its conversation intact. --all to pick up a new binary.
claude daemon status | stop --anyInspect/kill the background-session supervisor. --keep-workers leaves sessions running.
claude mcpConfigure MCP servers. claude mcp login <name> runs a server's OAuth flow from the shell; claude mcp logout <name> clears its stored credentials.
claude plugin install <name>@<marketplace>Plugin management from the shell (list, enable, disable, update, init, prune).
claude purge [path]Delete all local state for a project (transcripts, history, debug logs). --dry-run first; --all for every project. Formerly claude project purge (still works).
claude ultrareview [target]Deep multi-agent cloud review, non-interactive. Exits 1 on findings — CI-friendly. --post posts findings to a github.com PR as a comment. Needs workspace trust: asks on a terminal, else refuses — scripts pass --trust-workspace.
claude remote-controlServer mode: drive this machine's Claude Code from claude.ai or the mobile app.
claude self-hosted-runner setup|doctor|orchestratorRegister this machine/container as a place Claude Code web, mobile, and desktop sessions can run (Team/Enterprise). setup walks an operator through config; doctor diagnoses a deployed runner. --hold-idle-file and --max-hold-min keep an idle session while your host reports processes it left running.
claude auto-mode defaultsPrint the auto-mode classifier's built-in rules as JSON. --label <prefix> filters by rule label; claude auto-mode config shows your effective config with settings applied.
claude auto-mode resetRestore auto mode to its default configuration by clearing the autoMode section from user settings. -y/--yes skips the confirmation prompt.

no matches in this section

CLI flags

claude --help does not list every flag — absence from help ≠ unavailable.

Session shape

--print, -pNon-interactive mode. Gate for most scripting flags below.
--continue, -c  |  --resume, -rContinue latest / resume by ID or name.
--fork-sessionOn resume, branch to a new session ID instead of writing into the original.
--session-id <uuid>Pin the session ID (useful when you're orchestrating runs).
--name, -n "<name>"Name the session; resume later with claude -r "<name>".
--from-pr <n|url>Resume the sessions linked to a PR.
--worktree, -w [name|#PR|MR-url]Start inside an isolated git worktree at <repo>/.claude/worktrees/<name>. Pass a GitHub PR or GitLab MR URL to branch from it.
--tmuxWith -w: spin the worktree up in a tmux (or iTerm2) pane.
--bg, --backgroundLaunch as a background agent and return immediately. Monitor with claude agents.
--exec '<cmd>'With --bg: run a shell command as a PTY-backed background job (no model).
--add-dir ../pkg-a ../pkg-bExtra working dirs. Grants file access + loads their .claude/skills/, not the rest of their config.
--cloud "task"  |  --teleportPush a task to a web session / pull a web session down into this terminal.
--remote-control, --rc ["name"]Start an interactive session that you can also drive from claude.ai or the Claude app.
--desktopOpen the Claude Desktop app on the current directory and exit. Add --continue or --resume <id> to open that session there. macOS and x64 Windows only.
--environment <environment-id>Run a new cloud session on a specific self-hosted environment (ccpool_...) instead of the default.
--ref <branch>With --environment: base the new session's checkout on a named ref instead of local HEAD.
--autocompact <auto|tokens>Set the auto-compact window for this session without touching saved settings. Same value forms as /autocompact.

Model & reasoning

--model sonnet|opus|haiku|fable|<id>Session model. Overrides settings and ANTHROPIC_MODEL.
--effort low|medium|high|xhigh|max|ultracodeReasoning effort for this session. ultracode = xhigh + automatic workflow orchestration.
--fallback-model sonnet,haikuOrdered fallback chain when the primary is overloaded or retired.
--advisor fable|opus|sonnetConsult a second model at key moments in a task. fable requires Fable 5 access on your org.
--system-prompt[-file]Replace the entire system prompt. You now own tool guidance and safety text.
--append-system-prompt[-file]Keep the Claude Code prompt, bolt your rules on the end. Usually what you want.
--append-subagent-system-promptSame, but applied to every subagent (print mode only).
--system-prompt-snapshot offRebuild the system prompt on every request instead of reusing the one recorded on the conversation's first request — handy while iterating on --append-system-prompt across --continue runs.

Permissions & tools

--permission-mode <mode>default(=manual), acceptEdits, plan, auto, dontAsk, bypassPermissions.
--allowedTools "Bash(git log *)" "Read"Pre-approved rules — the whitelist for autonomous runs.
--disallowedTools "Edit" "mcp__*"Deny rules. A bare tool name removes the tool from context entirely.
--tools "Bash,Edit,Read"Restrict which built-in tools exist at all. "" = none, default = all.
--dangerously-skip-permissions= --permission-mode bypassPermissions. Prefer auto + an allowlist for real work.
--allow-dangerously-skip-permissionsAdds bypass to the Shift+Tab cycle without starting in it.
--restrictedFor eval harnesses on shared machines: drops command-running tools and WebFetch, confines file tools to the working dirs, loads only managed settings and --settings, refuses bypassPermissions.
--permission-prompt-tool <mcp tool>Route permission prompts to an MCP tool in non-interactive runs.
--permission-prompts host|nonePrint mode: who answers permission prompts. none denies them when nobody can answer.

Scripting & output

--output-format text|json|stream-jsonPrint-mode output shape. Since v2.1.318, JSON results carry credential_expires_at, and text output warns on stderr from 10 days before a stored claude.ai sign-in ends.
--input-format text|stream-jsonFeed structured turns in.
--json-schema '{...}'Validated structured output after the agent finishes (print mode).
--include-partial-messagesToken-level streaming events. Needs -p --output-format stream-json.
--include-hook-eventsEmit every hook lifecycle event into the stream.
--forward-subagent-textEmit subagent text/thinking as assistant/user messages with parent_tool_use_id set, so you can reconstruct each subagent's transcript. Needs -p --output-format stream-json.
--max-turns N  |  --max-budget-usd NHard stops for unattended runs. Subagent spend counts toward --max-budget-usd; hitting it blocks new subagent spawns and halts ones still running (v2.1.217+).
--bareSkip discovery of hooks/skills/plugins/MCP/CLAUDE.md. Fastest cold start for scripted calls.
--exclude-dynamic-system-prompt-sectionsMove machine-specific bits out of the system prompt → better cache reuse across machines/users.
--no-session-persistenceDon't write the session to disk (print mode).

Config, extensions, debugging

--settings ./settings.json | '{json}'Override settings keys for this session only.
--setting-sources user,project,localChoose which settings layers load.
--mcp-config ./mcp.json  |  --strict-mcp-configLoad servers from a file / ignore every other MCP config. In -p mode, Claude Code now waits (up to the MCP_TIMEOUT) for these to connect before the first turn (v2.1.221+).
--plugin-dir ./my-plugin  |  --plugin-url <zip>Load a plugin for this session only — the fast dev loop for plugin authoring.
--agents '{"reviewer":{...}}'Define subagents inline as JSON (same fields as frontmatter + prompt).
--agent <name>Run the whole session as a named agent.
--disable-slash-commandsKill all skills/commands for the session.
--safe-modeStart with all customization disabled — the bisect tool when your config breaks something.
--debug "api,mcp"  |  --debug-file <path>Category-filtered debug logging. Negate with !statsig.
--verboseFull turn-by-turn output.
--ax-screen-readerFlat-text output for screen readers — no borders or animations, forces the classic renderer. Also CLAUDE_AX_SCREEN_READER=1 or axScreenReader in settings.
--chrome / --no-chrome  |  --ideBrowser integration / auto-connect to a running IDE.
--init | --init-only | --maintenanceRun Setup/SessionStart hooks (with matcher) before — or instead of — a conversation.

no matches in this section

Session & context

Typed inside a session. A command is only recognized at the start of a message.

/clear [name]New conversation, empty context. Old one stays in /resume; a name labels it there. Aliases /reset, /new.
/compact [instructions]Summarize the conversation to free context, staying in the same thread.
/context [all]Grid of what's eating the window, with optimization hints. Run this before you blame the model.
/autocompact [auto|<tokens>]Set how full the context window gets before auto-compacting, e.g. 500k, or auto for the model-tuned default. Saves to user settings and applies to this session; saved per model as of v2.1.288.
/resume [session]Picker or direct resume by ID/name. Background sessions show as bg.
/branch [name]Fork the conversation at this point and switch into the copy. Original preserved.
/rewindRoll code and/or conversation back to a checkpoint, or summarize from a chosen message. Aliases /undo, /checkpoint.
/btw [question]Side question: sees the full conversation, has no tools, never enters history. Press f to fork it into a real session. No question reopens your last side question's answer.
/recapOne-line summary of the session so far.
/diffInteractive diff viewer: git diff ↔ per-turn diffs.
/copy [N]Copy the last (or Nth-last) response. Picker for individual code blocks; w writes to a file.
/export [file]Export the conversation as plain text.
/release-notesInteractive changelog picker — notes appear in your transcript without entering the conversation.
/rename [name]Name the session; shows on the prompt bar.
/color [color|default]Set the prompt bar color for this session; default resets. Syncs to claude.ai/code under Remote Control.
/memoryEdit CLAUDE.md files, toggle and audit auto-memory.
/initGenerate a starter CLAUDE.md. CLAUDE_CODE_NEW_INIT=1 for an interactive flow covering skills + hooks.
/add-dir <path>  |  /cd <path>Grant access to another directory / move the session there (keeps the prompt cache).
/focus  |  /tui [fullscreen]Collapse to prompt + summary + answer / switch the renderer (fullscreen = flicker-free alt-screen).
/restartnewRestart Claude Code and resume this session, applying an installed update. Native install on macOS/Linux (not WSL), Pro/Max/Ultra. Alias /update.
/exitQuit. In an attached background session this detaches and leaves it running.

no matches in this section

Model, cost & settings

/model [model]Switch model and save as default. Press s on a row for session-only. ←/→ adjusts effort.
/effort [level|auto|status|ultracode [on|off]]low → medium → high → xhigh → max; max is session-only. status prints it; ultracode on|off toggles ultracode at the current level (v2.1.284+; earlier, /effort ultracode just set xhigh).
/fast [on|off]Fast mode — lower latency, higher token cost. Deprecated for Opus 4.8 (removed Nov 30, 2026); migrate to Opus 5.5 to keep the speedup.
/advisor [model|off]Second-model consult at key decision points. Accepts fable, opus, sonnet, or a full model ID — fable requires Fable 5 access.
/config [key=value]Settings UI, or set directly: /config theme=dark, /config thinking=false. /config --help lists keys.
/statusVersion, model, account, connectivity — plus (v2.1.221+) session kind: interactive or background job (attached/unattended). Works while Claude is responding.
/output-style [style]List output styles or switch to one, e.g. /output-style concise.
/usageCost, plan limits, and usage broken down by skill / subagent / plugin / MCP server. Aliases /cost, /stats.
/insightsReport on your own sessions: project areas, interaction patterns, friction points.
/usage-creditsConfigure usage credits, or request them from your admin when you hit a limit.

no matches in this section

Review & ship

skill = prompt-based bundled skill (Claude can also trigger it on its own). workflow = fans out across subagents in the background.

/code-review [level] [--fix] [--comment] [--max-findings n|all] [target]skillCorrectness bugs + cleanup review of the diff, run as a background subagent (v2.1.218+) so it doesn't fill your conversation. Levels low…max (omit to reuse your last pick, v2.1.223+), or ultra for the cloud review. --comment posts findings on the GitHub PR or GitLab MR (MR needs v2.1.257+). --max-findings raises or lowers the findings cap and sticks until you pass default (v2.1.288+). Claude won't trigger this on its own — you have to invoke it.
/simplify [target]skillCleanup-only pass (reuse, simplification, efficiency, abstraction level) — applies fixes, doesn't hunt bugs.
/review [level] [--fix] [--comment] [--max-findings n|all] [target]Alias of /code-review, same levels and flags. Before v2.1.223 this was a separate single-pass PR review.
/security-reviewScan the branch diff for injection, authz, and data-exposure risks.
/ultrareview [PR]Deep multi-agent review in a cloud sandbox. Alias for /code-review ultra, the preferred form.
/verifyskillBuild + run the app and observe the result, instead of trusting tests and type checks. As of v2.1.215, Claude no longer triggers this on its own — you have to invoke it.
/runskillLaunch and drive the app to watch a change actually work.
/run-skill-generatorskillRecords how to build/launch this project into .claude/skills/run-<name>/ so /run and /verify stop guessing. Run once per repo.
/autofix-pr [prompt]Cloud session that watches the current branch's PR and pushes fixes when CI fails or reviewers comment.
/install-github-appWire up the GitHub app + Actions workflow for automated PR review.

no matches in this section

Parallel & background work

/plan [description]Enter plan mode from the prompt, optionally with the task attached.
/fork [prompt]Copy the conversation into a new background session that runs independently — its own row in claude agents, not reporting back. As of v2.1.221 the copy creates its own git worktree before editing code (unless it edits in place). (Contrast /branch, which switches you into the copy instead.)
/subtask <task>Background subagent that inherits the full conversation, works on the task, and reports its result back here. (What /fork did before v2.1.212.)
/batch <instruction>skillDecompose a codebase-wide change into 5–30 units, one background subagent per unit, each in its own worktree, each opening a PR.
/background [prompt]Detach the whole session to keep running headlessly; frees the terminal. Alias /bg. Monitor via claude agents. As of v2.1.221, background sessions commit and push their work as they go, open a draft PR only when the task calls for one, and report where the work lives when done.
/tasksEverything running in the background of this session, plus finished subagents under "Earlier in this session" that you can reopen and message (v2.1.319+). Alias /bashes.
/list-agentsList subagents and your other live Claude Code sessions Claude can message, with the name to address each by. Alias /peers.
/workflowsWatch / pause / resume / save running dynamic workflows.
/goal [condition|clear]Keep working across turns until a condition is met.
/loop [interval] [prompt]skillRe-run a prompt on a cadence while the session is open. /loop 5m check if the deploy finished. Omit the interval and Claude self-paces; since v2.1.319 that loop ends when a turn doesn't reschedule (CLAUDE_CODE_LOOP_KEEPALIVE=1 keeps the old fallback). Defaults to .claude/loop.md.
/schedule [description]Create routines that run on Anthropic-hosted infra (cron, API, or GitHub triggers). Alias /routines.
/deep-research <question>workflowFan out web searches, cross-check sources, synthesize a cited report.
/stopStop the attached background session (transcript and worktree kept).

no matches in this section

Config & extensions

/permissionsAllow / ask / deny rules by scope, working dirs, and recent auto-mode denials. Since v2.1.318, Ctrl+C twice in its dialogs goes back or cancels instead of quitting. Alias /allowed-tools.
/fewer-permission-promptsskillMines your transcripts for repeated read-only calls and writes an allowlist into project settings.
/hooksView hook configuration for tool events.
/mcp [reconnect|enable|disable <server>]MCP servers + OAuth. In -p mode with no args it prints a status summary.
/plugin [list|install|enable|disable]Plugin menu or direct subcommand.
/reload-plugins [--force]Apply plugin changes without restarting. --force when it would invalidate the prompt cache.
/import [codex|gemini|cursor] [--dry-run] [--yes]Bring instruction files, MCP servers, commands, subagents, and skills over from Codex, Gemini CLI, or Cursor. Cursor needs v2.1.265+.
/reload-skillsRe-scan skill + command directories mid-session. (SKILL.md text edits are already hot-reloaded.)
/skillsList skills. Type to filter, t sorts by token cost, Space cycles visibility → writes skillOverrides.
/skill-doctorWhat each skill costs in context and how often it's used — find ones to turn off. Needs feature-flag fetching.
/agentsAs of v2.1.198 this just points you at .claude/agents/ — ask Claude to create/manage subagents, or edit the files.
/doctor [prompt-audit [path]]skillSetup checkup that can fix: dupe installs, PATH, broken settings, unused skills/MCP/plugins vs their context cost, slow hooks, CLAUDE.md dedupe. Alias /checkup.
/debug [description]skillTurn on debug logging now and analyze the session debug log.
/heapdumpWrite a JS heap snapshot and memory breakdown for diagnosing high memory use. Share only the -diagnostics.json — the snapshot holds your conversation and credentials. Hidden from the menu; type it in full.
/feedback [report]Send product feedback, or /bug to report one — same dialog, with a consent step before anything is sent.
/statusline  |  /theme  |  /keybindingsStatus line (describe what you want), color theme, and your keybindings file.
/sandboxToggle OS-level sandboxing (filesystem + network isolation) where supported.
/auto-mode-setupDraft autoMode.environment entries from your project and recent sessions, review, and save to user settings. Pro/Max/Team from 2.1.228; Enterprise and Console API keys from 2.1.283.
/terminal-setupInstall Shift+Enter bindings for VS Code, Cursor, Alacritty, Zed.
/scroll-speedTune mouse-wheel scroll speed with a live preview ruler. Fullscreen rendering only.
/dataviz [request]skillChart/dashboard design guidance with colorblind + contrast validation.
/update-config [request]skillDescribe a settings change (allow a command, set an env var, add a hook) and Claude edits the right settings.json.
/claude-api [subcommand]skillLoads Claude API reference for your language. Subcommands include migrate, upgrade, api-version, managed-agents-onboard, managed-agents-secure, prompt-audit, cost-optimize, latency-optimize, build-eval, hillclimb — each has its own minimum version.
/design-sync [hint]skillShip your repo's React design system to Claude Design so generated designs use real components.
/design [brief]skillDraft UI mockups, flows, landing pages, or posters as artboards on one canvas, published as a Claude Design artifact.
/slides [brief]skillMake a Claude Slides deck artifact from your brief. Needs artifacts available on your account.
/artifactsList artifacts you own or that are shared with you; attach one to the session, open it, or copy its link.
/workflow-authoringskillLoad the reference for writing dynamic workflow scripts. Claude normally loads it itself.
/plugin-authoringskillnewLoad the reference Claude works from to write a mod. Claude normally loads it itself; it ships in a built-in plugin you can turn off in /plugin.
/artifact-capabilitiesskillnewLoad the reference for the runtime capabilities a published artifact can use, such as calling your connectors or offering a file download.
/artifact-diagrammingskillnewLoad diagramming guidance for artifacts: when a diagram helps, what to draw, and inline SVG that stays legible in light and dark themes.
/team-onboardingTurn 30 days of your usage into a setup guide a teammate can paste as a first message.
/powerupInteractive lessons with animated demos for discovering Claude Code features.
/mcp__<server>__<prompt>MCP servers can expose prompts as commands. Discovered dynamically.

no matches in this section

Platforms & handoff

/desktopContinue this session in the Claude Code desktop app. Alias /app.
/teleportPull a Claude Code web session into this terminal (branch + conversation). Alias /tp.
/remote-controlDrive this local session from claude.ai or the mobile app. Alias /rc.
/web-setup  |  /remote-envConnect GitHub for cloud sessions / pick the default cloud environment.
/ide  |  /chromeIDE integration status / Chrome browser automation settings. Since v2.1.318, starting claude in an IDE terminal no longer installs the extension — run /ide from an outside terminal, or use the editor's extensions view.
/claude-in-chrome [task]skillHave Claude do a task in your browser — test a page, fill a form, read console logs.
/voice [hold|tap|off]Voice dictation (hold or tap Space).
/install-slack-app  |  /mobileSlack integration / QR code for the mobile app.
/setup-bedrock  |  /setup-vertexInteractive wizards for Bedrock / Vertex auth, region, and model pins. Hidden until CLAUDE_CODE_USE_BEDROCK=1 / CLAUDE_CODE_USE_VERTEX=1.

no matches in this section

Keyboard & input modes

Input prefixes

/Command or skill menu — built-ins, bundled + your skills, plugin and MCP commands. You can stack up to 6 skills: /code-review /fix-issue 123.
!Shell mode. Runs the command, adds output to context, and (since v2.1.186) Claude responds to it. ! npm test → explanation of the failures.
@File path autocomplete / mention. With cross-session messaging on, typing a letter after @ also suggests your other live sessions to message.
TabAccept the greyed-out prompt suggestion (also completes paths in shell mode).
:Emoji shortcode. Type :heart: to insert ❤️, or 2+ characters for suggestions. Toggle with emojiCompletionEnabled.
?On an empty prompt, toggle the shortcut help panel.

Control

EscInterrupt Claude mid-turn and redirect. Work so far is kept.
Esc EscClear the draft (saved to history) — or, on an empty prompt, open the rewind menu.
Shift+TabCycle permission modes.
Ctrl+CInterrupt; on an idle prompt, first press clears input (Up on the empty prompt brings the draft back), second exits.
Ctrl+DExit the session.
Ctrl+OToggle the transcript viewer (expands tool calls and collapsed MCP output).
Ctrl+TToggle the task list.
Ctrl+BBackground the running bash command or agent. (Twice under tmux.)
Ctrl+X Ctrl+KStop all background subagents in this session and turn off artifact auto-replies (press twice within 3s to confirm).
Ctrl+RReverse-search prompt history. Ctrl+S cycles scope: session → project → all (fullscreen only).
Ctrl+SStash the draft and clear the prompt; press again on an empty prompt to restore it (text, cursor, pastes).
Ctrl+Enter / Ctrl+X Ctrl+SSend queued messages now, with your draft. Ctrl+X Ctrl+S works in any terminal.
Ctrl+G / Ctrl+X Ctrl+EOpen the prompt in $EDITOR.
Ctrl+VPaste an image from the clipboard as an [Image #N] chip. (Alt+V on Windows/WSL.)
Ctrl+LRedraw the screen when the terminal gets garbled.
Alt/Option+PSwitch model without losing your prompt.
Alt/Option+TToggle extended thinking. (No effect on Opus 5.5, Sonnet 5.5, or Fable — they always think.)
Alt/Option+OToggle fast mode.
Shift+Enter / \ + Enter / Ctrl+JNewline. Shift+Enter is native in iTerm2, Ghostty, WezTerm, Kitty, Warp, Terminal.app, Windows Terminal.

no matches in this section

Permission modes

Cycle with Shift+Tab, set at launch with --permission-mode, or persist as defaultMode in settings.

default (aka manual)Ask before each new tool use.
planRead-only analysis; produces a plan you approve before anything is written.
acceptEditsFile edits auto-approved; other tools still prompt.
autoA classifier approves safe actions and blocks risky ones. The sane default for long autonomous runs — tune it with claude auto-mode defaults and review denials in /permissions.
dontAskOnly pre-approved tools run; everything else is denied rather than prompted.
bypassPermissionsNo checks at all. Reach for a sandbox or container before you reach for this.

no matches in this section

Skills authoring

Custom commands merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both produce /deploy. Skills add supporting files, invocation control, and automatic loading. Follows the agentskills.io standard.

Where they live (precedence: enterprise → personal → project; a same-named skill overrides a bundled one)

~/.claude/skills/<name>/SKILL.mdPersonal — all your projects.
.claude/skills/<name>/SKILL.mdProject — commit it. Also loads from parent dirs up to the repo root, and from nested package dirs on demand (apps/web:deploy).
<plugin>/skills/<name>/SKILL.mdPlugin — namespaced /plugin-name:skill-name, so it can't collide.
.claude/commands/<name>.mdLegacy custom command. Still works, same frontmatter. Skill wins on a name clash.

Frontmatter

descriptionThe only field that really matters — Claude matches on it. Key use case first; combined with when_to_use it's truncated at 1,536 chars.
when_to_useExtra trigger phrases / example requests, appended to the description.
disable-model-invocation: trueOnly you can fire it. Use for anything with side effects (/deploy, /commit). Also keeps its description out of context.
user-invocable: falseOnly Claude can fire it. Use for background knowledge that isn't a meaningful command.
allowed-tools: Bash(git add *) ReadPre-approves those tools while the skill is active. Doesn't restrict anything else.
disallowed-toolsRemoves tools from the pool while active (e.g. AskUserQuestion for an unattended loop). Clears on your next message.
context: fork  +  agent: ExploreRun the skill as a subagent — SKILL.md becomes the prompt. Only makes sense for skills with a real task in them.
background: falseWith context: fork, wait for the forked subagent's result in the invoking turn instead of running it in the background (the default since v2.1.218).
shell: bash | powershellShell for !`cmd` blocks in the skill. powershell runs them via PowerShell.
model / effortOverride for the duration of the turn. Session settings resume on your next prompt.
paths: "ios/**"Only auto-activate when working on matching files.
argument-hint / argumentsAutocomplete hint, and named positional args for $name substitution.
hooksHooks scoped to this skill's lifecycle.

Substitutions & dynamic context

$ARGUMENTS  /  $0 $1  /  $nameAll args / positional / named. If $ARGUMENTS is absent, args are appended as ARGUMENTS: ….
${CLAUDE_SKILL_DIR}The skill's own directory — use it to call bundled scripts regardless of cwd.
${CLAUDE_PROJECT_DIR}Repo root. Works in the body and in allowed-tools rules.
${CLAUDE_SESSION_ID} / ${CLAUDE_EFFORT}Session ID for logging; current effort level for adapting instructions.
!`git diff HEAD`Runs before Claude sees the skill; output is inlined. Multi-line: a fenced ```! block. Only recognized at line start or after whitespace.
ultrathinkPut the word anywhere in the skill body to request deeper reasoning for that run.

Minimal SKILL.md

---
name: summarize-changes
description: Summarize uncommitted changes and flag risks. Use when the user asks
  what changed, wants a commit message, or asks to review their diff.
allowed-tools: Bash(git *)
---

## Current changes
!`git diff HEAD`

## Instructions
Summarize in 2–3 bullets, then list risks: missing error handling,
hardcoded values, tests that need updating.

Gotchas worth internalizing: skill content enters context once and stays for the session (write standing instructions, not one-time steps) — keep SKILL.md under ~500 lines and push reference material into sibling files. If you have many skills, descriptions get truncated to a context budget (1% of the window; raise with skillListingBudgetFraction); /doctor tells you who's eating it. Turn skills off per-project without editing them via skillOverrides in .claude/settings.local.json.

no matches in this section

Subagents & teams

.claude/agents/<name>.mdSubagent definition: frontmatter (description, tools, model, permission mode, skills to preload, hooks) + a body that becomes its system prompt.
Explore / Plan / general-purposeBuilt-in agents. Explore and Plan skip CLAUDE.md and git status to stay small — ideal for parallel research.
Subagent vs /btwSubagent = full tools, empty context (go find out something new). /btw = full context, no tools (ask about what's already known).
Fork mode (`subagent_type: "fork"`)On by default in interactive sessions: a fork inherits the full conversation + prompt cache instead of starting fresh, and non-fork spawns also run in the background by default. Start one yourself with /subtask.
Agent teamsMultiple teammates with shared task claiming, plan approval, and quality-gate hooks. Display mode via --teammate-mode in-process|auto|tmux|iterm2.
IsolationSubagents can each get their own git worktree; /batch does this automatically per unit of work.
CostNon-fork subagents don't share the parent's prompt cache — use them to isolate high-volume reads, not to generate parallel opinions. A fork's first request reuses the parent's cache.
Nesting & limitsSubagents nest 3 layers deep by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH) and cap at 20 running concurrently (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, exempt under ultracode). No limit on the total spawned over a session.

no matches in this section

Hooks

Shell, HTTP, prompt-based, or agent-based handlers on lifecycle events. Configure in settings under hooks, in a plugin, or in skill/agent frontmatter. Exit code 2 blocks; JSON output can inject context or make decisions. Inspect with /hooks, debug with claude --debug hooks.

SessionStart · Setup · SessionEndSession lifecycle. Setup supports init / maintenance matchers via CLI flags.
UserPromptSubmit · UserPromptExpansionIntercept or enrich the prompt before it reaches the model.
PreToolUse · PostToolUse · PostToolUseFailure · PostToolBatchAround tool calls. Filter with matchers and the if field (tool name + args). Auto-format on edit lives here.
PermissionRequest · PermissionDeniedAuto-approve or auto-deny specific permission prompts.
Stop · StopFailure · Notification · MessageDisplayTurn boundaries and notifications (terminal bell, Slack ping, etc.).
SubagentStart · SubagentStop · TeammateIdleAgent lifecycle — quality gates for teams.
TaskCreated · TaskCompletedTask-list events.
PreCompact · PostCompact · InstructionsLoadedRe-inject context after compaction; audit what loaded.
FileChanged · CwdChanged · ConfigChangeReact to the environment moving under you.
PreModelSwitch · PostModelSwitchAround a model switch. PreModelSwitch can block it (a timeout blocks too); PostModelSwitch fires after any change, including restores on resume. Matcher is the model name.
DirectoryAddedFires after /add-dir or an SDK register_repo_root call adds a working directory mid-session — not the --add-dir startup flag.
WorktreeCreate · WorktreeRemoveCopy gitignored files (.env, xcconfig, local secrets) into new worktrees.
Elicitation · ElicitationResultAround an MCP server's mid-tool-call request for user input; can auto-decide the response.
"onFailure": "block"newHandler field on command and http hooks: block the action if the hook fails or times out. Default "continue" lets it through, so a broken policy hook fails open.

no matches in this section

File map

~/.claude/settings.jsonUser settings: model, hooks, permissions, statusline.
.claude/settings.jsonProject settings — commit these.
.claude/settings.local.jsonPersonal project overrides — gitignored. skillOverrides lands here.
CLAUDE.md / AGENTS.mdAlways-loaded project memory. Layer per-directory in large repos; move procedures out to skills.
.claude/rules/Path-scoped rules — the alternative to one bloated CLAUDE.md.
.claude/skills/  ·  .claude/commands/Skills (dir + SKILL.md) and legacy commands (single .md).
.claude/agents/Subagent definitions.
.mcp.jsonProject-scoped MCP servers (shared with the team).
.claude/worktrees/Where -w and /batch put isolated worktrees.
.claude/loop.mdDefault prompt for /loop.
~/.claude/projects/<slug>/Session transcripts as JSONL — tail these to watch an autonomous run.
~/.claude/themes/  ·  keybindingsCustom themes; /keybindings opens your bindings file.

no matches in this section