Claude Code — commands, settings, flags

Hi!

This is a reference. Not a story about how to work with the agent properly — I have a separate article for that — but a list: what you can type, what you can put in the settings, what each of those does and how it looks in practice.

Current as of August 2026, Claude Code 2.1.251. For a technical article that matters more than usual: between neighbouring builds commands disappear, get renamed and swap places. If you're on a different version, /help and claude --help are always right, and I'm only right as of the day I wrote this.

The three places commands go

Before you start scrolling through the tables, it helps to know that there are three surfaces and they don't overlap.

Slash commands are typed inside a running session, with / at the start of the line. They drive the conversation: switch the model, compact the context, roll back edits, kick off a review. They don't work in the terminal.

settings.json is a file on disk. It defines how Claude Code starts up: which model, what the tools are allowed to do, which hooks, what to show in the status line. A large share of the settings exist only here and have no command equivalent.

The claude terminal commands are typed in an ordinary shell, before a session or alongside one: installation, login, MCP servers, plugins, background agents, non-interactive runs for scripts.

The split isn't decorative. Half of the "why isn't this working" questions come down to someone typing /model in the terminal or --effort in the settings file. There is one pleasant exception, though: in the non-interactive claude -p mode slash commands inside the prompt text do work — more on that below.

Slash commands

Typed inside a running session, with / at the start of the line. Each command below has everything in one place: arguments with all their values, the fine print, and examples.

Markers: [Skill] — a built-in skill, that is, a ready-made prompt scenario; [Workflow] — a built-in multi-agent workflow; [undocumented] — present in the build, not described in public sources; [disabled] — registered, but doesn't work in 2.1.251.

Sessions and the conversation

Four commands in this group do something similar, and people mix them up constantly. The difference is what gets copied and where the result shows up:

/clear [name]

Start a new conversation with a clean context. Aliases: /reset, /new.

The old conversation isn't deleted — it stays on disk and opens through /resume. The optional argument labels it in the list: with no label, a week later you'll be staring at a dozen nameless rows.

If you cleared it by accident, you can undo that within the same process: the /rewind menu has an entry for the previous session, shown as /resume <id> (previous session).

The price is worth remembering too: /clear costs nothing, whereas /compact is a large request carrying the whole context. If you don't need the conversation any more, clearing is cheaper than compacting by the entire window.

/clear
/clear queue experiment, didn't pan out

/resume [id or search phrase]

Go back to a past conversation. Alias: /continue.

The list is tied to the working folder: a conversation from another project won't show up in it. By id, though, a session opens from any folder on the machine — before 2.1.223 the search covered only the current project and its worktrees. Handy for scripts: grab the session_id out of claude -p --output-format json and carry on from anywhere.

Transcripts are cleaned up according to cleanupPeriodDays, thirty days by default. If you expect to come back to old conversations, raise the value in advance — there's nowhere to restore a deleted one from.

Terminal forms: claude -c continues the folder's last conversation with no picker (skipping background sessions), claude -r opens that same picker before the session starts, and claude -r <id> --fork-session continues an old conversation under a new id, leaving the original untouched.

/resume
/resume 8f3c1d2e-4b5a-...
/resume deadlock in the pool

/branch [name]

Branch the conversation off at the current point; the original is kept in full.

This is the save-before-the-boss move. You're at a point where it's unclear which of two approaches is better; you branch off, try the first one, and if it doesn't work out you go back to the original through /resume and try the second, without dragging the failed attempt along in the context. The name is optional, but with one it's easier to find the right branch in the list later.

/branch
/branch try-it-through-a-queue

/fork [task]

Copy the conversation into a background session that works on a task in parallel with you.

This is "let someone else deal with that while I get on with mine". The copy inherits all the accumulated context; you collect the result by attaching to it with claude attach or through the claude agents screen. Starting with 2.1.221 the copy is also told to create its own git worktree before it edits any code — so two agents don't step on each other's toes in the same tree.

Careful with other people's instructions. In versions 2.1.161 through 2.1.211 what is now called /subtask was called /fork, and the names swapped places in 2.1.212. An article or a script written before that means the exact opposite. Plus one special case: if the agents screen is turned off, /fork falls back to the old behaviour and acts as a subagent.

/fork
/fork put together release notes from the commits since the last tag
/fork run the whole test suite and list the failures with their causes

/subtask <task>

Send off a subagent carrying your context; the result comes back into this same conversation.

This is "go take a look and come back". The difference from /fork is fundamental: the noisy part of the work — reading twenty files, walls of output — stays in the subagent's context, and only the answer reaches you. The main way to keep reconnaissance out of your main context.

Requires version 2.1.212; before that this command was called /fork. Unavailable when the agents screen is off.

/subtask find every call to this method
/subtask find where the authorization header is built and describe the chain
/subtask read the last month of migrations and tell me what changed in the orders schema

/background [prompt]

Move the current session into the background and free up the terminal. Alias: /bg.

Nothing is copied — this very session is what goes into the background, and the work carries on. With an argument you also hand it a task for the road. To come back: claude attach or the claude agents screen; to stop it: /stop or claude stop <id>.

/background
/bg catch up with the build and fix the linter

/rename [name]

Rename the session. Alias: /name [undocumented].

The name shows up in the input line, in the /resume list and in the terminal tab title. With no argument it's generated from the conversation's topic.

Three things happen to a name you type in: control and invisible characters are replaced with spaces, the length is trimmed to two hundred characters, and if nothing is left after the cleanup, the name is rejected as empty. If another live session on this machine already holds that name, a variant of it is applied — not an error, the name just ends up slightly different.

The terminal title changes if terminalTitleFromRename is on (yes by default); to forbid touching the title altogether, use the CLAUDE_CODE_DISABLE_TERMINAL_TITLE variable.

/rename
/rename payment refactor

/cd <path>

Move the session to a different working folder.

The new folder's settings, hooks, MCP servers, skills and agents take effect immediately rather than after a restart, and the new folder's env block is layered on top of the old one. That's what makes /cd different from /add-dir, which grants access to files but not to configuration.

/cd ../backend

/recap

Compress the whole session into a one-line summary — a quick way to remember what it was about.

/recap

/btw [question]

Ask a short side question without cluttering the main context: the answer isn't mixed into the rest of the work.

With no question it opens your past side questions so you can page through the answers; before version 2.1.212 the question was mandatory.

/btw how is grpc-web different from grpc
/btw

/export [file]

Dump the conversation to a file or the clipboard.

With no argument the whole conversation goes to the clipboard, with an argument it's written to a file; ~ is expanded. The format is text with role markup: it's a transcript for a human or for handing to another tool, not a machine format for importing back.

/export
/export ~/logs/session.md
/export ./docs/decision.md

/copy [N]

Copy a single reply to the clipboard: with no argument the last one, with a number the Nth from the end.

It counts assistant replies, not lines on screen, so /copy 2 means "the reply before last". Little known: if the reply contains code blocks, a picker opens — you can take one block instead of the whole message. And right there the w key writes the selection to a file instead of the clipboard; over SSH, where the clipboard is useless, that's the only thing that works.

/copy
/copy 2

/stop

Stop the current background session. The transcript and the worktree are kept.

/stop

/exit

Leave the CLI. Alias: /quit. In a background session it detaches instead, and the session keeps running.

/exit

Context and memory

/context [all]

Show a colored grid of what's filling the context, plus tips on what you could unload. The all argument expands the details: exactly which files, and how much each one takes.

Every cell of the grid is a chunk of the context window, colored by source. The point isn't the pretty picture: sources behave differently, and each one is cured differently.

The practical value is in all: there's almost always a file or two, or one chatty MCP server, that has eaten more than all the useful work put together.

Then comes the fork. History has ballooned — /compact. The files you've read have ballooned — /clear and start over. Tool and skill descriptions have ballooned — that's cured by settings, not by commands: next session the context will be bloated in exactly the same way.

/context                                # what's taking up the context right now
/context all                            # the same, broken down file by file

/compact [instructions]

Compact the conversation history into a summary and free up room. The argument isn't a flag and isn't a filter — it's an instruction to whoever writes the summary: what to pay attention to, what must not be lost.

Compaction is loss. The summary is written by the model, it's inevitably shorter than the original, and everything that didn't make the emphasis is either reproduced approximately or gone. A meaningful argument isn't politeness, it's how you control what exactly you agree to lose.

Compaction on its own is an expensive request: the whole context goes into it. /clear costs nothing. If you no longer need the conversation, the second command is cheaper than the first by the entire size of the window.

The threshold at which the context compacts itself is controlled by /autocompact.

/compact                                # compact the history however it comes out
/compact keep the DB schema decisions    # compact, but don't lose this thread
/compact keep the decisions made on the schema and why we rejected triggers
/compact leave only what relates to the payments module

/autocompact [auto|<tokens>]

Set how full the context has to get before it starts compacting itself. The command appeared in 2.1.221.

Values outside the range are not accepted. The permanent equivalent is the autoCompactWindow key; auto-compaction is switched off entirely with autoCompactEnabled: false, and there's a launch flag --autocompact taking the same values. A separate setting, precomputeCompactionEnabled, prepares the compaction in advance while normal work goes on — so when the threshold is reached the pause is shorter; it only works with auto-compaction enabled.

/autocompact                            # see the current threshold
/autocompact auto                       # let it pick for itself
/autocompact 400000                     # compact on reaching 400k tokens

/memory

Open the memory files for editing and manage them.

What exactly gets loaded from them is shown by /context, and /doctor knows how to put them in order: it clears out duplicates, moves the rarely needed parts into separate files loaded on demand, and cuts whatever the agent would work out from the code anyway.

/memory                                 # open the memory files for editing

/pause-memory

Pause auto-memory for the session. Aliases: /memory-pause, /toggle-memory. [disabled] — in build 2.1.251 the command is registered but does nothing.

/pause-memory

/init

Create CLAUDE.md: the agent looks the repository over and describes its structure and commands. [Skill]

CLAUDE.md is an instructions file that gets mixed into the context of every session.

A little-known variable: CLAUDE_CODE_NEW_INIT=1 turns on an interactive version that walks you through not just the project instructions but the skills, hooks and personal memory files as well. And if the folder turns out to hold another coding agent's configuration that /import knows how to bring over, you'll be offered the chance to take it.

/init                                   # generate CLAUDE.md from the repository

CLAUDE_CODE_NEW_INIT=1 claude    # interactive /init with skills and hooks

/add-dir <path>

Add another working directory so the agent can see files outside the project folder.

An important subtlety: it grants access to the files, not to the configuration — that folder's hooks and settings are not picked up. The one exception is skills and commands: those are taken from the added folder. Moving the session into another folder wholesale, together with its settings and hooks, is /cd, not /add-dir.

/add-dir ../shared-protocol             # let the agent into a neighbouring repository

/rewind

Roll the code and/or the conversation back to a checkpoint, or compact a slice of the conversation. Aliases: /checkpoint, /undo.

The first thing to know: the command doesn't always work. Copies of files are taken before an edit only if fileCheckpointingEnabled is on. Off — and there's nothing to restore from.

The second: the menu opens from more than just the command. Double Esc on an empty input line does the same thing. If there's text on the line, double Esc clears it — so clear the line first.

The menu has six items, and half of them aren't about rolling back:

The two compaction items are essentially a targeted /compact: free up context, but a specific slice of the conversation rather than the whole thing. The line has an optional field for saying what to pay attention to while compacting, and a marker is left where the compacted part was.

Of the rollbacks, "restore code" is the one you need most often: the edits went sideways, but the discussion they grew out of is valuable and it'd be silly to lose it.

Boundaries worth knowing before you need them. The last hundred checkpoints are kept, and they're deleted along with the session after thirty days — the same cleanupPeriodDays. Not restored: whatever the shell commands you ran did, most subagent edits, changes made from outside, and everything living behind symbolic and hard links. Meaning a database wiped by a migration won't come back, a git reset won't be undone, installed packages will stay. This is an undo for recent edits, not a version control system and not a substitute for commits.

/rewind                                 # the rollback and compaction menu

Model and performance

/model [model]

Switch the model and remember the choice. With no argument, a list of what's available opens.

The choice is remembered and survives a restart — that's how /model differs from the ANTHROPIC_DEFAULT_MODEL variable, which it overrides.

Where things stand in August 2026. The current models are Opus 5, Sonnet 5, Fable 5 and Haiku 4.5. There is no Haiku 5: the haiku alias still leads to 4.5, and that regularly misleads people reading examples with fallbackModel.

What sits behind an alias depends on the provider, and that's a non-obvious detail for anyone working through a cloud. On Anthropic's own API sonnet is Sonnet 5; on Amazon Bedrock and Google Cloud it's Sonnet 4.5; on Microsoft Foundry opus is Opus 4.6 outright. The same config on two providers gives you different models.

All of this is configured three ways. What sits behind the aliases — through ANTHROPIC_DEFAULT_OPUS_MODEL and its relatives (there's no such variable for best). The picker list itself — through the modelPicker key: you add your own entries with labels there, including Bedrock and Vertex identifiers, and replaceBuiltInOptions replaces the built-in list entirely. On top of it all, the corporate availableModels constrains everything; since version 2.1.205 a family alias isn't rejected in that case but resolves to the newest permitted model.

fallbackModel lives separately — a list of models Claude Code will switch to on its own if the main one is overloaded. That's not a change to your choice, it's insurance for the time it's unavailable.

/model                # pick from the available list
/model opus           # by alias
/model claude-opus-5  # by full identifier
/model opusplan       # plan on Opus, execute on Sonnet

/effort [level|auto|status]

The effort level sets how much the model thinks over a turn. It isn't the same thing as choosing a model: the model decides who is thinking, the effort decides how much.

Four things that aren't obvious.

max can't be saved in the settings. The effortLevel key only accepts values up to xhigh. The maximum is set per session — by the command or the --effort max flag — and deliberately doesn't stay switched on forever. ultracode works the same way: the command and the flag work, but it isn't among the values listed in the schema; permanently it's turned on by a separate boolean key, ultracode.

The level is remembered per model. Since version 2.1.248 every model has its own saved level: switch to another one and you get its setting, not your last one.

Other commands override it. /code-review high raises the effort for that turn, /code-review low lowers it, even if the session was running on xhigh.

The word ultracode works right inside the prompt text — by default it's enough to turn orchestration on for a single turn; workflowKeywordTriggerEnabled is what's responsible for that. If it fired by accident, it's cancelled on the spot with Alt+W (Option+W on macOS). To start with it straight away: claude --effort ultracode.

2.1.251 also fixed an edge case that's easy to run into: Opus 5 refused to work with xhigh and max when thinking was turned off. Now in that combination the effort is simply sent as high.

/effort status     # what the level is right now
/effort low        # cheap and fast
/effort xhigh      # deep reasoning
/effort ultracode  # xhigh plus constant workflow orchestration
/effort auto       # back to automatic selection

/fast [on|off]

Fast mode: the same model, but with accelerated output.

It's not a different model and not a different effort level — it's an output mode, and it costs more. The settings keys sit right next to each other: fastMode turns it on permanently, while fastModePerSessionOptIn makes every session start without it, even if you turned it on last time.

/fast on   # accelerated output
/fast off  # back again

/brief

"Short answers only" mode: maximally condensed replies with no expanded explanations. No arguments.

/brief  # answer as briefly as possible

/advisor [model|off]

An advisor: a stronger model prompts the main agent at key moments.

The second model doesn't intervene constantly, only at key points — when the main agent is making a decision where a mistake costs a lot. The argument is an alias or a full model identifier; off turns it off. With no argument a picker opens. There's also a launch flag --advisor <model> which, by the way, isn't in the output of claude --help.

/advisor opus  # hints from Opus
/advisor off   # turn the advisor off

/plan [open|share|description]

Planning mode: the agent reads, analyses and proposes a plan but changes nothing — file edits and dangerous commands are unavailable. The exit is accepting the plan; after that the session returns to the normal mode and starts carrying it out.

Plan files live in ~/.claude/plans/ unless plansDirectory is set — people point it into the project repository so the plan gets discussed and versioned along with the code.

The plan-acceptance dialog has a "clear context" option: the plan stays, and all the recon it was built on is thrown away. It's only shown with showClearContextOnPlanAccept, which is off by default, and on long tasks it's one of the most useful settings — execution starts with a clean window.

The mode is available from the very start too: claude --permission-mode plan. And it's worth knowing separately that auto mode applies by default inside planning as well; that's switched off with the useAutoModeDuringPlan key.

/plan                                    # enter planning mode
/plan move payments into its own service # enter with the task right away
/plan open                               # open the session's current plan
/plan share                              # share the plan

/goal [condition|clear]

Set the condition under which the work counts as finished; the agent keeps going on its own until it's met, instead of stopping after every turn.

The condition has to be checkable — a command, a file's state, a marker in the output. A vague "until it's good enough" turns into endless work, because there's nothing to check it with.

A separate cost item few people think about: while a goal is active, the agent periodically wakes up and checks on stuck background work, and every such check is a full turn with the full context. The frequency is set by CLAUDE_CODE_GOAL_CHECKIN_MINUTES, zero disables the checks entirely; since version 2.1.246 there are no more than three per goal.

/goal until all the tests are green        # work until the condition is met
/goal until `npm test` passes in full
/goal until not a single call to the deprecated client is left in the file
/goal                                      # show the current goal
/goal clear                                # drop the goal

Code review and quality

The first three commands look at the same diff and are therefore easy to confuse; the fourth analyzes nothing at all:

/code-review [level|ultra] [--fix] [--comment] [--post|--no-post] [target]

Reviews the diff for bugs and simplifications [Skill]. Alias: /review.

The most configurable of the built-in commands: an effort level, four flags, a review target and a separate cloud mode — and each of them is parsed by its own rules. The full form is /code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [--post|--no-post] [<PR#>|<branch>|<path>|<note>], and every part of it is optional: a bare /code-review is a valid call.

What it looks for. Two different things. Correctness bugs: an inverted condition, an off-by-one, a null dereference, a forgotten await, a check that got dropped, an error swallowed in a catch, broken callers of a changed function, the classic pitfalls of the language at hand. And cleanliness: new code that repeats something already in the repository; needless complexity and dead code; needless work such as recomputing the same thing or running independent operations one after another; the "wrong level of fix", where a patch is slapped on the spot instead of repairing the shared mechanism; outright violations of the rules in your CLAUDE.md.

Correctness bugs always outrank cleanliness findings: when there are more findings than the level's limit, the cleanliness ones are cut first. The review itself changes nothing until you pass --fix.

Where it runs. Usually in a background agent: the session isn't blocked, and the findings arrive as a separate message. In three cases the review takes over the session entirely: if you launch it again while a previous one is still running; if you're in the non-interactive -p mode or in the SDK; and if CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set, which disables background tasks altogether.

Who can launch it. Not just you. Ask "take a look at my changes" in plain prose and the agent will start the review itself, and a scheduled task with /code-review in its prompt will fire too. If that gets in the way, keep the command typable but forbid the agent and the scheduler from launching it:

{
  "skillOverrides": { "code-review": "user-invocable-only" }
}

The cloud mode is the exception: the agent never launches ultra, neither on its own nor on a schedule.

Argument order. Three rules that make a call behave differently than you expected:

1. ultra is recognized only as the first word. /code-review ultra --fix is a cloud review, while /code-review --fix ultra is an ordinary local one in which the word ultra is read as the target.
2. The level is the first word left once the flags are stripped out of the line. That's why /code-review --fix high works, and the level will be high.
3. Flags can go anywhere: at the start, at the end, between the level and the target. The only exception is rule 1.

And a fourth one, separate: this command "eats" the command typed after it. Normally several skills stack in one message, and /write-tests /fix-issue 123 loads both. But since version 2.1.218 /code-review /fix-issue 123 reads /fix-issue 123 as target text, not as a second command. Before 2.1.218 it was the other way around.

Effort levels.

The numbers in this table were read off the binary: the official documentation describes the levels qualitatively — "lower levels return the most confident findings, higher ones broaden coverage and may include less confident ones" — and nowhere publishes how many search angles there are or what the ceiling on findings is.

The exact pipeline depends on the session's model, so the table is about what the levels mean, not about a guaranteed number of agents. On Opus 5, medium and high currently collapse into a single careful pass with a limit of fifteen findings, and the differences begin at xhigh; on Sonnet 5, at high, xhigh and max the number of search agents is chosen by the size of the diff — from two to eight.

Remembering the level. If you don't name a level, it takes the one you typed last time: it lives across sessions, and the top of the report says so with a line like "using high, the level from last time". Two exceptions: a level passed in a non-interactive -p run remembers nothing, and ultra neither reads the remembered level nor changes it. If you've never typed one, it takes the current session's effort level. The level you type also sets the model's effort for that turn, including downward: /code-review low in an xhigh session lowers it.

A typo doesn't break the call: /code-review higher gets you a warning that the value wasn't recognized, plus the previous or the default level. The abbreviation med is accepted as medium.

Flags.

--fix repairs what it found right in the working tree, both bugs and cleanliness. A finding is skipped if the fix would change intended behavior, would require changes far outside the diff under review, or looks like a false positive; at the end you're told what was skipped and why. With ultra, the fixes are applied locally the moment the cloud returns its result.

--comment requires the target to be a pull request. If it isn't, the flag is ignored, the findings are simply printed, and the agent says so. Comments go out through the GitHub integration, or through gh api if the session doesn't have one.

--post isn't the same as --comment: one shared comment instead of per-line remarks, and only for the cloud review. In an interactive session the launch dialog still asks for confirmation; in non-interactive mode it posts on the flag alone. Passed to an ordinary local review, it's ignored — you'll be reminded that posting there is --comment's job.

--no-post is there so you don't see the offer to post at all. Passing both at once is pointless: the command only reads --post, so --post --no-post still offers to post.

The review target. With no target, it reviews the current work: the branch's commits above its upstream plus the uncommitted changes. That's why the command makes sense before a commit too.

In a local review the target is handed to the model as a string, and the model decides for itself what it is: a pull request number, a branch name, a path to a file or a folder — or just a hint about where to look first. In ultra the target is parsed strictly:

Reviewing in the cloud: what it needs, what it costs and where the ceiling is. ultra launches a background agent in Claude Code on the web: it clones the repository into a cloud sandbox, runs a multi-agent search over the diff and sends the findings to your session as a notification. It takes minutes, and you can keep working the whole time.

It needs a git repository with a GitHub remote, a claude.ai account with GitHub connected, and, for a private repository, the Claude app installed on the owner. It's unavailable on third-party providers, with optional requests turned off, in zero-data-retention organizations and when the organization forbids it. An important detail: when the mode is unavailable, /code-review ultra doesn't fail — it quietly runs an ordinary local review — so if you were expecting the cloud one, it's worth making sure it actually started.

The diff ceiling is up to five hundred changed files and eight thousand changed lines. A pull request that's too big is rejected, and the refusal names the limits in force, the size of your diff and the largest files; an empty diff is rejected too.

The price: three free runs on Pro and Max, then it comes out of credits, usually five to twenty-five dollars per review depending on the size of the changes. A run counts from the moment the cloud session starts: a review you stop or one that crashes still spends a free run, while a paid one is billed only for the part it worked through. If credits aren't connected, a paid run is simply blocked.

From CI. Since version 2.1.218 the cloud review can be launched non-interactively:

claude -p '/code-review ultra'

The command starts the review, prints a link for tracking it and doesn't wait for the result. But if the review would have to spend credits, the run stops: confirming payment requires an interactive session. For that case there's a separate subcommand, and the very act of launching it counts as your consent to be billed:

claude ultrareview                       # cloud review of the current branch
claude ultrareview 1234 --post           # review a PR, summary as a comment on it
claude ultrareview --json                # raw findings instead of a report
claude ultrareview dev --timeout 60      # against the dev branch, wait up to an hour

The exit code is 0 if the review finished (with findings or without), and 1 if it couldn't be started. --timeout defaults to thirty minutes.

The canonical form is /code-review ultra; /ultrareview is its alias, available not to every account, and the whole capability is marked as research. Articles often say the opposite, as if /ultrareview were the main command.

In GitHub Actions. The review has a separate life in CI, and there it's configured by a file rather than by flags. You put a REVIEW.md in the repository root that sets the rules: which paths and branches to skip, which categories of findings to hide, what counts as important, how to behave when the same pull request is reviewed again.

Findings come in three tiers: important ones, nitpicks, and ones that were already in the code before these changes. Violations of your CLAUDE.md rules land among the nitpicks. The check always ends with a neutral status and therefore never blocks a merge by itself — but its last line prints a finding counter as JSON like {"normal": 2, "nit": 1, "pre_existing": 0}, which you can use to put up your own gate in your own pipeline.

/code-review                                   # the current changes, level as last time
/code-review low                               # a quick read-through before a commit
/code-review high                              # and remember high as the default level
/code-review --fix                             # find it and fix it right away
/code-review high --fix                        # deeper, and fix what it finds
/code-review medium --comment 1234             # review PR 1234 with comments right in it
/code-review xhigh applications/backend/src    # this folder only, as thorough as it gets
/code-review max dev                           # the current branch's diff against dev
/code-review higher                            # typo: warns and takes the previous level
/code-review ultra                             # cloud review of the current branch
/code-review ultra 1234 --fix                  # cloud review of a PR, findings applied locally
/code-review ultra 1234 --post                 # cloud review of a PR, summary as a comment
/code-review ultra look at the error handling  # the branch plus a note on where to look

/simplify [target]

Find simplifications in the changed code and apply them right away [Skill].

It looks at the same diff as /code-review, but hunts only for cleanliness, and does it with four parallel agents: reuse of helpers already written, simplifications, efficiency, and whether this is the right level of abstraction. It doesn't look for bugs as a matter of principle — that's a division of labor, not an oversight. And unlike the review, it applies what it finds right away. The argument is an optional target: a path, a folder or a pull request number.

A historical trap: before version 2.1.147, /simplify was the name of today's /code-review, and it applied fixes by default. An old script that called /simplify to hunt for bugs does something entirely different today.

/simplify                                # all the changed code
/simplify src/payments                   # this folder only
/simplify src/api/handlers               # or this one
/simplify 1234                           # simplifications in this pull request

/security-review

Check the branch's changes for vulnerabilities. Takes no arguments.

It looks for injections, authorization and authentication problems, data leaks, and unsafe handling of secrets and input.

The one requirement people trip over: you need a remote named origin — the diff is computed against its main branch. Without it the command dies with a git error about an ambiguous argument, and it looks mysterious.

/security-review                         # vulnerabilities in the branch's changes

/diff

Browse the uncommitted changes interactively. Takes no arguments.

It analyzes nothing, it's a viewer: the uncommitted changes and, more usefully, the diff of each agent turn separately. Something worth using before /rewind, not after.

/diff                                    # look at what's uncommitted

Development and workflows

/run and /verify get mixed up constantly: both are about "check it live", but they answer different questions.

/run

Launch the project's app and check a change live, not just with tests. [Skill]

This is about the app as a whole: bring it up the way it comes up in this project, and let you look at it. For it to know how exactly, it needs a launch skill — /run-skill-generator creates one, once per project. Without it /run will try to guess from the project type, and on a non-standard build it will guess badly.

/run  # launch the app and look at it with your own eyes

/verify

Confirm a change works: build it, run it, watch the behavior. [Skill]

The logic is simple: review checks that the diff reads right, /verify — that it works right.

Since version 2.1.200 the command can write the verification recipe it found into its own skill, .claude/skills/verify/SKILL.md, and then at the repository root it replaces the built-in one — meaning you work out once how to verify this project, and after that it works for everyone.

An important change: since version 2.1.215 /verify is launched only by you. The agent used to be able to call it itself. The same happened to /deep-research in 2.1.218. If you've read an article saying the agent will verify itself, it's out of date.

/verify  # build, run, make sure it works

/run-skill-generator

Create a skill that knows how to launch this project's app — /run then runs on top of it. [Skill]

Done once per project.

/run-skill-generator  # teach the project the /run command

/batch <instruction>

Plan a large-scale edit and carry it out in parallel across 5–30 isolated working copies, each opening its own pull request. [Skill]

The heaviest of the built-in commands, and the only one that spawns dozens of agents by default. The instruction first turns into a plan — a list of the concrete places that need editing — and then each place gets its own agent in its own isolated git working copy, and each one opens a separate pull request.

The key thing here is isolation. The agents edit files in parallel, and without separate working copies they'd be stepping on each other's toes. Hence the requirements: a git repository, a clean tree and a configured gh, otherwise there's nothing to open a pull request with.

The number of agents is five to thirty, and it's derived from the plan rather than set by you: as many agents as there are places found, up to the ceiling. If the plan comes out to two places, no fan-out is needed, and the command will say so.

A good instruction is one where the boundaries of each place are obvious and the edits aren't tied to one another. A bad one is "refactor the project": the plan comes out of vague items, and thirty agents independently invent thirty different architectures.

The fan-out's behavior is shaped by the worktree settings: symlinkDirectories saves disk space if the project has heavy dependencies, sparsePaths speeds up the checkout in large monorepos, baseRef decides whether to branch off the remote main branch or off your current local state.

/batch move all the controllers to the new client  # a fan-out of isolated agents, each with its own PR
/batch move every use of the deprecated http client to the new one
/batch add the missing indexes from the planner's report
/batch split the shared DTOs out into the modules that use them

/debug [description]

Turn on debug logs for the session and help work through a problem. [Skill]

The description is optional — with it you say up front what exactly you're chasing.

/debug                                    # turn on debug logs
/debug fails only on CI, green locally    # the same plus a description of the problem

/fewer-permission-prompts

Go through the transcripts, find the frequent safe calls and build a permission list out of them. [Skill]

/fewer-permission-prompts  # build a permission list from history

/commit [preferences]

Put a commit together: look at the status and the diff, write a message in the accepted format. [Skill]

The argument isn't flags, it's your preferences in plain text; the same goes for /pr. Preferences affect what lands in the commit and how the message gets written. The message format is derived from this repository's commit history, not from general rules.

What goes into the commit message as attribution is set by the attribution object with its commit and pr fields, where an empty string removes it entirely. You can switch off the built-in commit instructions altogether with includeGitInstructions: false — then the agent goes by your rules only.

/commit  # a commit with a message in the project's format
/commit only the schema changes, leave the rest alone
/commit as a single commit, without mentioning the test refactor
/commit split it in two: schema first, then the code

/pr [preferences]

Open a pull request: create a branch, push, write the description through gh. [Skill]

A branch is created if you're still on the main one. Preferences set the draft flag, the reviewers, the shape of the description.

/pr  # branch, push, pull request with a description
/pr as a draft, don't assign reviewers
/pr in the description, list in a separate section what was left out

/commit-push-pr

All three steps in one go: commit, push, pull request. [Skill]

It has one quirk: dangerous git and gh flags are not auto-approved. --force, --amend, --no-verify will still ask for confirmation, even if your permissions are generous. That's deliberate: a chain of three steps runs fast, and a human doesn't get the chance to notice that history is being rewritten somewhere in the middle.

/commit-push-pr  # all three steps at once

/update-config

Change the settings: hooks, permissions, environment variables — editing settings.json for you. [Skill]

/update-config add a hook that runs the formatter after edits

/claude-code-docs [question]

Answers about Claude Code itself: features, settings, the SDK, the Claude API, the Slack app. [Skill]

/claude-code-docs how do I limit the agent's access to a folder

/claude-in-chrome

Allow work inside your Chrome: clicking, filling in forms, reading the console. [Skill]

/claude-in-chrome  # allow work in the browser

/plugin-types [folder]

Generate the input types for the connected MCP tools.

/plugin-types ./my-plugin  # MCP tool types for the plugin

/workflow-authoring

A reference for writing workflow scripts. [Skill]

It doesn't authorize running a workflow itself.

/workflow-authoring  # how to write workflow scripts

/claude-api [migrate|upgrade|prompt-audit|managed-agents-onboard|cost-optimize]

Help with the Claude API and the SDK. [Skill] The only command in this group with a fixed set of arguments.

The skill also switches on by itself, without the command: if the project's code imports the official Anthropic library, it activates on tasks that touch it.

/claude-api migrate       # migrating to a new model
/claude-api prompt-audit  # find instructions written for older models in prompts

/deep-research <question>

A fan-out of web searches across many sources, fact-checking, and a report with links. [Workflow]

Since version 2.1.218 it's launched only by you — the agent used to be able to call it itself.

/deep-research how do approaches to idempotency in queues differ

Subagents, background tasks, automation

/list-agents

A list of the subagents, teammates and other sessions you can write to. Alias: /peers.

/list-agents

/agents

Gone. Now it just replies that subagents are created as files in .claude/agents/.

/agents

/tasks

Listing and managing background tasks and running processes. Alias: /bashes.

/tasks

/daemon

Managing background services: assistants, scheduled tasks, remote control.

/daemon

/workflows

The history of workflows, running and finished: progress, pause, resume.

/workflows

/loop [interval] [prompt]

Repeat a prompt or a command on an interval; with no interval the pace picks itself. Alias: /proactive. [Skill]

The command takes two things in a row: an optional interval and the thing to repeat. What you repeat can be a plain prompt or a slash command.

The interval is written as a human shorthand: 5m, 30m, 1h. The mode without an interval should be taken literally: the agent picks the pause based on what it's waiting for. A build that takes eight minutes it will wait out in a single pause, not in eight one-minute checks.

There's exactly one trap, and it's an expensive one: a loop that wakes up every minute to check on a background task is almost always pointless. You'll be told when background work finishes anyway, and every wake-up is a full request carrying the whole context.

The list of what's already running is managed by /loops — but in this build that one is disabled.

/loop 5m /code-review low               # every five minutes — a quick review pass
/loop 10m /code-review low
/loop 1h check whether new failing tests have shown up, and fix the obvious ones
/loop check if the build broke          # no interval: the pace picks itself
/loop watch the deploy and tell me when it's done

/loops

Viewing and deleting recurring tasks. [disabled] — doesn't work in build 2.1.251.

While it's disabled, /usage is what shows you what is running and how often.

/loops

/schedule [description]

Create, update or run a scheduled remote agent. Alias: /routines. [Skill]

The difference from /loop is where it runs. /loop works in your session, on your machine, for as long as it's open. /schedule files the task in the cloud: it runs on schedule whether or not your laptop is on.

The argument is a description in words, and the schedule, the task and the intent are all derived from it: the command can not only create, but also update, show, run out of turn and delete.

The requirements are the same as for everything cloud-based: a claude.ai account, a connected GitHub, no block from your organization. The default environment comes from the remote setting.

About the cost, remember one thing: a scheduled task wakes up and sends the full context even while you're at the computer busy with your own work. It's the least visible line item of them all.

/schedule every morning at 9 put together a report on failing tests
/schedule on Mondays check for outdated dependencies and file a task
/schedule show my scheduled tasks
/schedule run the morning summary right now
/schedule delete the task about dependencies

/autofix-pr [prompt]

A web session watches the pull request of the current branch and pushes fixes itself.

/autofix-pr                              # watch the PR and fix CI failures
/autofix-pr only fix the linter, don't touch the logic

Artifacts, documents and design

An artifact is a page published on claude.ai that you can open, click through and hand to colleagues to look at. Almost everything below is a built-in skill, and the set depends on your account: some of it only switches on for certain subscriptions and organizations.

The official command reference lists only /artifacts, /design, /design-login and /design-sync from this group; the other dozen and a half are [not in the documentation] — not in the changelog, not in search — so what follows is what's actually in the build, not what's been promised somewhere.

/artifacts

A list of the artifacts you've published and the ones shared with you.

/artifacts

/prototype

Turn an idea into a working prototype: one self-contained page you can click through.

/prototype

/doc

Publish a working document that's edited right on the page.

/doc

/plan-artifact

Publish a plan as its own shareable page.

/plan-artifact

/artifact-pr-review [number or link]

A pull request review as its own page: the conclusion, the recommendation, the contentious spots, the blind spots.

/artifact-pr-review 1234

/artifact-dashboard

A dashboard from a ready-made template.

/artifact-dashboard

/artifact-report

A report from a ready-made template.

/artifact-report

/artifact-data-table

A data table from a ready-made template.

/artifact-data-table

/artifact-explainer

An explainer page from a ready-made template.

/artifact-explainer

/artifact-components

Drop ready-made reusable components into an artifact.

/artifact-components

/artifact-design

The rules for styling artifacts: layout, typography, dark theme.

/artifact-design

/artifact-diagramming

How to draw diagrams that show the real mechanism.

/artifact-diagramming

/artifact-capabilities

What a published page can do at runtime: read your data, remember what visitors did, ask Claude.

/artifact-capabilities

/dataviz

The rules for styling charts and dashboards: palettes, axes, labels, accessibility.

/dataviz

/whiteboard

A shared board: you draw, and the answers come back right on it.

/whiteboard

/whiteboard-mp

The same, but a live board the agent draws on as well — the two of you draw together.

/whiteboard-mp

/workshop

Build a design together, one decision at a time.

/workshop

/design [sync|login|consent|revoke|import|export|status|description]

The Claude Design hub.

Officially this is a single command "with a design description", and /design-login and /design-sync are two separate ones. In the binary, /design additionally understands the seven subcommands listed in the heading, and that's documented nowhere. The whole thing appeared in version 2.1.234 and is marked experimental — meaning it will change.

/design status                           # the state of the connection to Claude Design
/design login                            # log in
/design import                           # pull the design system from there
/design export                           # push yours to it
/design revoke                           # revoke access

/design-sync [hint]

Push a React project's design system to claude.ai/design.

/design-sync Acme DS

/design-login

Authorize access to the design system — the very access the push needs.

/design-login

Configuration and interface

/config [key=value]

The settings panel: with no argument it opens a panel with every setting you can change from the interface. Alias: /settings.

With an argument the setting is applied immediately, without the panel: /config theme=dark. The full list of accepted keys is printed by /config --help — don't guess, it's shorter than the list of keys in the settings file.

The direct form appeared in 2.1.181, named shortcuts like theme and model — in 2.1.182. It works in non-interactive mode too, and from a phone over remote control, which makes it the main way to change a setting from a script.

There's exactly one limitation, and it isn't obvious: the key=value form can't turn on a setting that requires your confirmation in the panel. It can turn autoContinueAtUsageLimit off, for instance, but not on — turning it on brings up a dialog, and this form has nowhere to show one.

/config                  # open the settings panel
/config --help           # which keys the key=value form accepts
/config theme=dark       # set it immediately, no panel
/config model=sonnet     # the same for the model
/config thinking=false   # turn thinking off

/permissions

Tool allow and deny rules, plus the auto-mode tab. Alias: /allowed-tools.

/permissions   # access permission rules

/theme

Change the interface color theme.

Besides light and dark there are colorblind variants, ANSI variants for terminals with their own palette, and auto, which adapts to the terminal background. Your own themes go into ~/.claude/themes/ or come from plugins; the picker itself has an entry for creating a new one.

/theme   # pick a theme

/keybindings

Open or create the keyboard shortcuts file.

/keybindings   # your own keyboard shortcuts

/terminal-setup

Set up terminal key combinations — Shift+Enter for a line break, for example.

/terminal-setup   # Shift+Enter and other terminal key combinations

/statusline

Configure the status line: with your own script, or generated from your shell prompt.

/statusline   # configure the status line

/voice [hold|tap|off]

Voice input.

/voice hold   # talk while holding a key down
/voice tap    # press, talk, press again to send
/voice off    # turn voice input off

/tui [default|fullscreen]

The interface renderer: fullscreen is full-screen and flicker-free, default puts it back to normal.

/tui fullscreen   # full-screen renderer without flicker
/tui default      # back to normal

/color [color|default]

The prompt line color for the current session. It's not a theme, it's specifically the color of the input line; handy when you have four terminals open and don't want to mix them up.

The palette is fixed: red, blue, green, yellow, purple, orange, pink, cyan, plus default to reset. If remote control is connected, the color syncs to the web interface as well.

/color purple    # prompt line color
/color           # random color
/color default   # reset

/scroll-speed

Mouse wheel scrolling speed.

/scroll-speed   # mouse wheel scrolling speed

/focus

Focus view: only your prompt, the tool summary and the final answer stay on screen.

/focus   # keep only the essentials on screen

/hooks

A view of the hooks configured for each event.

/hooks   # which hooks are configured

/auto-mode-setup

Tell auto-mode about your environment and adjust its rules.

/auto-mode-setup   # tell auto-mode about your environment

/sandbox [exclude "pattern"|install]

Configure the sandbox for commands. The command is only visible where the sandbox is supported.

exclude is for the case where a build or a container command doesn't work inside the isolation and you deliberately pull it out; the list accumulates in the sandbox.excludedCommands key.

/sandbox exclude "docker *"   # take a command out of the sandbox
/sandbox install              # install the sandbox (Windows)

/import [codex|gemini] [--dry-run] [--yes]

Bring configuration over from another coding agent: instruction files, MCP servers, commands, subagents and skills. codex and gemini are supported.

In non-interactive mode the command prints what it found and suggests the line to run to confirm the import. Not available on third-party providers, or when fetching server flags is turned off. Requires 2.1.213 or newer.

What /import does not do matters too: Claude Code doesn't read the AGENTS.md file some other agents use — but /import can carry the configuration from there into a form it does understand.

/import codex              # pull in another agent's configuration
/import gemini --dry-run   # see what would be imported
/import codex --yes        # import without questions

/cloud-plugins

Whether cloud sessions should use the plugins enabled on this machine.

/cloud-plugins   # plugins in cloud sessions

/skills

The list of skills, with control over their visibility.

The descriptions of every available skill sit in the context permanently, every session, whether you use them or not. With a large set of plugins that's a noticeable share of the window — which is exactly what the /skills screen is for.

Type and the list filters by name, description and source. The t key sorts by token count, and that's usually where you discover that half the window is taken up by three skills you've never used once. Space or Enter toggles a skill's visibility for the model and for the menu, Esc saves and closes.

Not everything can be toggled: plugin skills, skills with disable-model-invocation: true in the frontmatter, and ones whose visibility is set in enterprise settings or via --settings won't budge. The permanent equivalent is the skillOverrides key, and /skill-doctor helps find the ones that simply go unused.

/skills   # the list of skills and their visibility

/plugin

Managing plugins and marketplaces. Aliases: /plugins, /marketplace.

/plugin   # plugins and marketplaces

/reload-skills

Pick up skills and commands changed on disk without restarting the session. You need it when you're writing your own skill and don't want to restart on every edit.

/reload-skills   # pick up skill changes from disk

/reload-plugins [--force]

Apply pending plugin changes — the same as /reload-skills, only for plugins.

The meaning of --force here is the opposite of the intuitive one: it does not mean "reload harder". If the reload would change the set of loaded MCP tools, it invalidates the prompt cache, so the command warns you and refuses to do it — and --force makes it go ahead anyway. The flag overrides a refusal rather than deepening the work.

/reload-plugins           # apply pending plugin changes
/reload-plugins --force   # do it even if it drops the prompt cache

/wellbeing

Break reminders and quiet hours. Aliases: /breaks, /break-reminder, /downtime. [disabled] — in build 2.1.251 the command doesn't work, but the break settings themselves do apply.

/wellbeing   # break reminders and quiet hours

MCP and integrations

/mcp [reconnect|enable|disable [<server>|all]]

Managing MCP servers and their OAuth authorization.

Servers expose their own prompts as commands. They show up in the menu as /server-name:prompt-name — and that's the form worth remembering, because the second one, /mcp__server__prompt, works too but only turns up in older articles. Arguments are passed after a space and split on spaces: each argument is one token, and there's no way to pass a quoted phrase as a single argument.

Server resources are pulled in with @. The form is @server:protocol://path, and it's a mechanism separate from tools: not "call a tool", but "put this content into the context".

/mcp                                     # list of servers and their state
/mcp reconnect github                    # bring a dead server back up
/mcp reconnect all                       # reconnect all of them
/mcp disable jira                        # turn a server off temporarily
/mcp enable jira                         # turn it back on
/jira:create_issue login-bug high        # a server prompt, current form
/mcp__jira__create_issue login-bug high  # the same one, old form

/ide [open]

IDE integrations and their status. With no argument it shows the status of the editor integration; with open it opens the file in the connected IDE.

/ide                                     # editor integration status
/ide open                                # open the file in the connected IDE

/chrome

Claude in Chrome settings.

/chrome                                  # settings for working in the browser

Account and authorization

/login

Log in to an Anthropic account or switch accounts.

/login                                   # log in or switch accounts

/logout

Log out of the account.

/logout                                  # log out

/setup-bedrock

Set up Amazon Bedrock: authorization, region, model pins. Visible when Bedrock is enabled.

Together with /setup-vertex this is an example of commands hidden by state: they appear only once the matching provider environment variable is set. Until it is, they're not in /help either.

/setup-bedrock                           # set up Amazon Bedrock

/setup-vertex

Set up Google Cloud: authorization, project, region, model pins. Like /setup-bedrock, it's visible only when the provider environment variable is set.

/setup-vertex                            # set up Google Cloud

/install-github-app

Install Claude GitHub Actions for a repository.

/install-github-app                      # put review in CI on the repository

/install-slack-app

Install the Slack app.

/install-slack-app                       # install the app into Slack

/privacy-settings

View and change privacy settings.

/privacy-settings                        # what goes outside

Usage and cost

/usage

Session cost, plan limit usage and activity statistics. Aliases: /cost, /stats.

The screen shows three things: how much this session has spent, how full the plan limits are, and where the tokens go — broken down by skills, subagents, plugins and individual MCP servers, plus notes about any behavior accounting for more than ten percent of the spend. The d and w keys switch the window between a day and a week, and since 2.1.242 scheduled tasks get their own rows.

Next come four things worth understanding, and not one of them is obvious.

The breakdown is computed from the local session history. That is, from the transcripts on this machine. Work done from another computer or from the web interface doesn't make it in — even though the limits themselves are shared across the account. The gap between "I've barely spent anything" and "the limit is nearly gone" usually comes down to exactly this.

There are several limits, and switching models only helps against one of them. The messages "you've run out of session limit" and "you've run out of weekly limit" refer to windows shared by every model — /model won't save you there. Only after "you've run out of Opus limit" or "Sonnet limit" will moving to a model from another family get you working again. Since version 2.1.234 Claude Code can wait for the reset and resume the interrupted task on its own; you turn that on through /rate-limit-options and the autoContinueAtUsageLimit key.

The prompt cache lives an hour only on a subscription. The moment you start spending credits beyond the plan, cache lifetime drops from an hour to five minutes — and the same lunch break that cost nothing yesterday means reprocessing the entire context from scratch today. On an API key and with cloud providers it's five minutes by default.

The session counter resets on /clear. Before version 2.1.211 it accumulated across clears, so the numbers in older articles don't match today's.

If the limits server is unavailable, the screen shows the last loaded data with a note and offers to retry with the r key.

Invisible spending that doesn't show up in the breakdown but really does burn the limit while you're doing nothing: scheduled tasks wake up and go off with a full context; a message from another of your sessions arrives as a new turn (cured by crossSessionInbound: "hold"); active-goal checks start turns while background work is running; every live teammate spends until it finishes. And /compact is itself a large request, whereas /clear costs nothing.

/usage                                   # limits, spend, breakdown
/stats                                   # the same, straight to the stats tab
/cost                                    # the same, in the usual view

/usage-credits

Set up credits so you can keep working once you hit the plan limit. Remember the side effect described above: as soon as you spend beyond the plan, the prompt cache lives five minutes instead of an hour.

/usage-credits                           # enable credits beyond the plan

Remote work and environments

/desktop

Continue the current session in the desktop app. Alias: /app.

/desktop                                 # continue in the app

/teleport

Pull a web session into this terminal. Alias: /tp.

/teleport                                # bring the web session into the terminal

/remote-control

Open the session for control from a phone or the web. Alias: /rc.

/remote-control                          # open the session up to a phone

/session

Show the remote session's address and a QR code for it. Alias: /remote.

/session                                 # session address and QR code

/remote-env

The default environment for web sessions and teleport.

/remote-env                              # default environment for the web

/web-setup

Connect GitHub to Claude Code on the web through your local gh.

/web-setup                               # connect GitHub to the web

Diagnostics and help

/help

Help and the list of available commands.

/help                                    # what's available at all

/status

Version, model, account, API connectivity and tool statuses. Works even while a response is streaming.

Opens the settings panel on the status tab. Besides version, model, account and connectivity, there's a line for the kind of session: interactive for a normal one, background job · attached or background job · unattended for a background one — depending on whether a terminal is attached to it. The line appeared in 2.1.221.

Plus, since 2.1.243, a line right there about skipped sources of enterprise settings: if an admin dropped in a policy file but a different, higher-priority one is in effect, you'll see here exactly which one was ignored. It's the first thing to look at when "the admin's setting didn't arrive".

/status                                  # version, model, account, connectivity

/doctor

Diagnose the installation and put the configuration in order. Alias: /checkup.

Since version 2.1.205 this isn't a report screen but a full skill that edits your configuration. What it does: clears out duplication between the local and the committed CLAUDE.md; trims the committed one, throwing out whatever the agent would infer from the code anyway; moves permanently loaded instructions into skills and nested files loaded on demand; offers to make auto mode the default and to pre-approve the safe commands you've denied most often. It shows the findings first, then makes the changes.

The terminal claude doctor is still diagnostics with no edits and no session start; it reads the settings files in the current folder without asking whether you trust it.

The command stays available even when bundled skills are switched off entirely: it's specially marked as surviving disableBundledSkills. You can hide it with the DISABLE_DOCTOR_COMMAND variable or a "doctor": "off" entry in skillOverrides.

/doctor                                  # check and fix the configuration

/feedback [report]

Send feedback about Claude Code.

/feedback                                # send feedback
/feedback edits get applied but don't show up in the diff

/bug [report]

Report a bug or share the conversation. Alias: /share.

/bug                                     # report a bug

/heapdump

Take a memory dump — for diagnosing high memory usage. Hidden.

Writes a memory snapshot and a usage breakdown to the desktop (to the home folder on Linux without a desktop). The command is hidden not by a server flag but by not being shown in the menu: type it out in full and it works. An important warning: when you contact support, attach only the breakdown file — the snapshot itself holds your entire conversation and your credentials, and must not be shared.

/heapdump                                # memory dump to the desktop

/insights

An analytical report on your sessions: areas of the project, work patterns, points of friction.

/insights                                # an analysis of my sessions

/skill-doctor

Which loaded skills go unused and take up context for nothing.

/skill-doctor                            # which skills hang in context for nothing

/explain-usage

Where this session's tokens went, in plain language. [Skill]

/explain-usage                           # where the tokens went

/version

[disabled] Doesn't work in build 2.1.251. /status shows the session's version.

/version                                 # disabled, /status will show the version

/update

[disabled] In build 2.1.251 it doesn't work and is hidden. Updating is done with the terminal claude update. Alias: /restart.

/update                                  # disabled, update via claude update

/install [version] [--force]

Install a native build straight from the session. The argument is the version: stable or a specific number; --force installs it over the current one.

/install stable                          # install the stable build
/install 2.1.236 --force                 # a specific version, over the current one

Information and documentation

/release-notes

A list of changes by version.

A nice detail: the notes are printed into the transcript but don't get into the model's context. That wasn't always so, and showing all the changes used to mix the whole changelog into every subsequent request.

/release-notes                           # what changed, by version

/powerup

Short interactive lessons on features.

/powerup                                 # a short lesson on features

/mobile

A QR code for installing the mobile app. Aliases: /ios, /android.

/mobile                                  # QR code for the mobile app

/radio

Claude FM lo-fi radio in the browser.

/radio                                   # background music

/passes

Share a free week with friends and get credits.

/passes                                  # share a free week

/upgrade

Move to Max: higher limits, more Opus.

/upgrade                                 # move to Max

/stickers

Order stickers.

/stickers                                # order stickers

/team-onboarding

Generate a team onboarding guide from your usage history.

/team-onboarding                         # a team guide from my history

Commands that no longer exist

A table of its own, because half the articles on the internet still recommend them.

Disabled specifically in build 2.1.251: /version, /update, /loops, /wellbeing, /pause-memory. They're registered, but they don't work and don't show up.

There are also commands that appear on state and that you won't see until that state arrives: /limit-reset and /low-priority — when you've hit the session limit, /rate-limit-options, /pro-trial-expired, /design-consent and /design-revoke, and /setup-cowork lives only in Cowork mode. Plus two entirely internal entry points, __remote-workflow and workflow-launch-exec, through which the server hands the session a ready-made workflow.

And a category of its own — model-only skills: keybindings-help, memory-types, cowork-plugin. The agent pulls them in itself; you can't type them. The mechanism is generic and available to you too — it's the user-invocable: false field in a skill's frontmatter.

Two stubborn myths to finish with. There is no /alias command: what sits under that name in the binary is a description of the system alias utility, used for autocompleting the commands you type through !. And there's no .claudeignore file either — to make the agent ignore files, use .gitignore, which is honored by default, or .ignore.

How the menu matches a command

A small thing that saves your nerves. Since 2.1.236 the menu highlights a command when the letters after / match its name or one of its aliases — from the start of the name or from the start of a word inside it, with the separators :, _ and - ignored during the comparison. So /adddir highlights /add-dir, and /new highlights /clear through its alias.

What changed at the same time and matters more: a typo is no longer guessed. Enter on a non-existent command used to run the closest one. Now a typo leaves nothing highlighted, near matches stay in the list and you pick one with the arrows or Tab, but Enter sends your text as-is and reports an unknown command.

Unavailable commands simply vanish from the menu — you'll see "no commands match your query". Some answer with their own unavailability message instead: /schedule on an API key, for instance, will tell you it needs an account. And a partial name won't pull a hidden command out — you have to type it in full.

Your own commands

Your own slash command is a SKILL.md file in a skill folder. There used to be a separate entity for this in .claude/commands/; commands and skills are now merged into one, and the old files keep working and give you exactly the same command.

Where to look and where to put things:

The command name comes from the folder name, not from the name field. For personal and project skills, name is only the label in the list. For plugin skills it's the other way round: name replaces the last segment, so my-plugin/skills/review/ with name: fancy gives you /my-plugin:fancy. The short form /fancy works too, as long as nobody else has taken that name.

The simplest example:

---
name: fix-issue
description: Look up an issue by number, find the cause and propose a fix
argument-hint: <issue number>
allowed-tools: Bash(gh issue view:*), Bash(gh pr create:*)
---

Take issue number $0 from this repository.

Current state of the branch:

!`git status --short`

Read the description, find the cause in the code, propose the smallest fix
and explain why it is the smallest one.

You call it as /fix-issue 4821. Here $0 is the first argument, that is 4821, and the line with ! runs before the text ever reaches the model and is replaced by its output. Both in detail below.

Frontmatter fields

There are twenty of them. It's worth knowing they exist at all — half of them solve problems people otherwise solve with hacks.

Three limitations people trip over. The frontmatter is read only if the opening --- is the very first line of the file. In the listing, description and when_to_use are truncated at fifteen hundred characters — anything longer is invisible to the model when it picks a skill. And the old files in .claude/commands/ support the same frontmatter, except name and paths — those are ignored there.

A word on allowed-tools specifically: it's a pre-approval for one turn, not a restriction. The permission drops with your next message, though the skill's content stays in the context. And it has an unpleasant property worth knowing about for anyone who runs the agent in someone else's repository: folder trust does not hold it back. A project skill applies its allowed-tools even in a folder you never marked as trusted, including a non-interactive run. Which means a skill sitting in a repository can grant itself broad rights — read that field in other people's repositories before you launch.

Arguments: numbering starts at zero

The most surprising spot in the whole topic, and one worth memorizing word for word.

Yes, $0 is the first argument, not the command name as it is in a shell. The off-by-one here is the most common mistake of all.

Indexed arguments are parsed with quoting in mind: in /my-skill "hello world" second the value of $0 is hello world as a whole. An indexed substitution that ran out of arguments stays in the text as-is; a named one turns into an empty string. An argument whose own value happens to contain $1 or $ARGUMENTS is inserted literally and not expanded a second time. Escaping is a single backslash: \$1.00. And if no substitution in the body received any arguments, the line ARGUMENTS: <value> is simply appended at the end.

Embedded shell commands

The form !`command` runs before the content reaches the model and is replaced by its output. That's how you feed a skill the current state: the branch, the diff, the list of failing tests. What actually runs it — bash or powershell — is set by the shell field in the frontmatter.

There are two rules that save you half an hour of bafflement. The form is recognized only if the ! sits at the start of a line or right after a space — in KEY=!`cmd` it stays text and never runs. And substitution passes over the file once: command output isn't rescanned, so a command can't print another substitution counting on a second pass.

For a multi-line script you open a code block with an exclamation mark after the three backticks.

All of it is switched off by the disableSkillShellExecution setting: every command is replaced with a stub saying policy forbids it. It applies to personal, project and plugin skills and to skills from added folders; built-in and enterprise ones are left alone. Skills synced from claude.ai never run such commands locally, whatever the setting says.

Path variables

Inside the skill body and inside allowed-tools rules you get ${CLAUDE_SKILL_DIR} — the skill's own folder, ${CLAUDE_PROJECT_DIR} — the project root, ${CLAUDE_SESSION_ID}, and in plugin skills also ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA}.

That they work in both places isn't a detail, it's a working technique: that's how a skill runs its own script without a single question about permissions.

---
name: render
description: Render a diagram from its source
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh $0` and show the result.

The rule allows exactly the command the body tells it to run — no wider, no narrower.

Small things worth knowing

Skills stack. You can put up to six commands at the start of one message: /write-tests /fix-issue 123 loads both skills and passes 123 to both as arguments. Before 2.1.199 only the first one loaded and the rest counted as text. The exception is /code-review, which takes the rest of the line for itself.

ultrathink in a skill body asks the model to think harder when the skill fires. It works as the bare word in the text.

Built-in command names are reserved, even when they're unavailable in your session: a skill arriving from sync with a colliding name will be skipped.

You can validate a skill without a plugin: claude plugin validate <path> works on a plain folder of skills and agents too. And to turn a folder of skills into a plugin, all you need is to drop a .claude-plugin/plugin.json into it.

Settings: settings.json

Next up are the keys of the settings file, including the experimental and enterprise ones, with types and examples. The list is merged from two sources: the official settings reference, which currently holds about two hundred and twenty entries, and the validation schema inside the CLI itself. They don't agree: the schema has keys the documentation doesn't, and the documentation has keys the schema knows nothing about, because those live in a different file. More on that separately below.

Notation: [exp] — an experimental or internal key, may change or disappear; [admin] — only takes effect from an enterprise source; [deprecated] — deprecated; [global] — lives not in settings.json but in ~/.claude.json.

Where the file lives

There aren't four levels, or five, but more than people usually write about. Let's start with the ordinary ones:

That last row is the one you'll find almost nowhere. Some settings live only in ~/.claude.json, and if you write them into settings.json they're silently ignored. That's also where Claude Code keeps your login session, the MCP server configuration and your folder trust decisions. The file normally writes itself and you rarely go in by hand — but you need to know it's there, because "I set the key and nothing happened" is most often explained by exactly this.

Enterprise policy isn't a single thing either. There are four sources, and they're ranked:

The OS policy and HKCU are re-read every half hour, the server-side settings once an hour. By default the sources don't add up: the highest-ranked one applies and the rest are discarded. You can change that with managedSourcesBehavior: "merge", but you have to set it in the highest of the deployed sources — a lower one can't invite itself into the merge, and HKCU never merges at all.

If an admin put something in and it "didn't arrive" — look at /status: since 2.1.243 there's a line about skipped sources that says outright which file was ignored.

Format: strict JSON

Here I have to correct myself, because I used to think otherwise and the internet repeats it often.

Settings files are strict JSON. A // comment or a trailing comma is a syntax error, and on the next launch the file is marked bad as a whole. No JSONC. (The confusion comes from JSONC genuinely existing elsewhere in the product — /terminal-setup, for instance, parses editor configuration with comments in it.)

The easiest way to check your file is to launch: settings errors are printed at startup. claude doctor will show them broken down.

A useful habit is the $schema line:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Your editor will start suggesting key names and underlining typos, and a typo in a key name is the most common reason a setting "doesn't work": unknown keys are silently ignored. One caveat: the schema sometimes lags behind the product. teammateDefaultModel is still in it, for instance, while Claude Code removed it in 2.1.234 and it affects nothing.

Who overrides whom

The order of levels is the one in the table above. But "overrides" isn't true for everything, and here are three exceptions that break your intuition.

Lists add up, they don't replace. If permissions.allow is set in both the user file and the project file, you get the union of the two. A higher level cannot remove an entry from a lower one — the only thing that can is the enterprise allowManagedPermissionRulesOnly. Any priority table that says "each level overrides the previous one" is wrong about lists.

Four lists behave differently: fallbackModel is taken whole from the highest file that defines it (it's an ordered chain, and mixing it makes no sense); modelPicker — whole from the highest among the enterprise source, --settings and the user file, and ignored in the project and local ones; availableModels from an admin applies as-is, without picking up your additions; modelSettings is resolved separately for each model.

For seven keys, a stricter value from below beats the enterprise one. Policy is normally absolute — not even --settings overrides it. But for these keys the stricter variant from any level wins, because nobody is going to stop you from forbidding yourself something extra: disableClaudeAiConnectors set to true, enableArtifact set to false (and disableArtifact: true), isolatePeerMachines set to true, remoteControlAtStartup set to false from a project or local file, crossSessionInbound with a stricter value on the accept — hold — reject scale, and useAutoModeDuringPlan and syncClaudeAiSkills set to false.

Project permissions wait for folder trust. permissions.allow and permissions.additionalDirectories from the project file only start working once you've confirmed trust in that folder. deny and ask take effect right away — they only restrict.

And what comes next is the important part, worth reading for anyone who runs claude -p in someone else's repository. In non-interactive mode the trust dialog is never shown, so the project's allow rules are discarded with a warning on stderr — but that repository's hooks do run, its env block does apply, its auth helper scripts do launch, the allowed-tools field of its skills does take effect, and the servers from its .mcp.json connect without a question. What gets discarded is the permissions, not the executable parts.

A safe launch in an unvetted folder means --setting-sources user, --bare, --restricted or --settings '{"disableAllHooks": true}'. Simply setting disableAllHooks in your own user file is not enough: the project file outranks it and will bring hooks back.

Environment variables aren't a level

Another thing usually drawn wrong. Environment variables don't sit "between" the settings levels: who overrides whom is decided separately for each variable-and-key pair.

• ANTHROPIC_MODEL from the shell overrides the model key from any file.
• ANTHROPIC_DEFAULT_MODEL only takes effect if model isn't set anywhere.
• --model and /model override ANTHROPIC_MODEL.
• And CLAUDE_CODE_EFFORT_LEVEL works the other way round and overrides --effort and /effort.

And separately: a value from the env block in the settings beats an export from the shell, not the other way round as people tend to assume. Claude Code writes every entry of the block into the process environment on top of the inherited value. You can't delete a variable from a settings file — you can set it to an empty string, which counts as "not set" when a provider is picked (though child processes will get the empty value). Shell variables are read once at startup, while values from env are re-read when the file changes — except for subsystems that are configured only at launch, like telemetry.

The skeleton of the file

Scalars like model, theme, numbers and flags go at the top level. Grouped settings — permissions, env, hooks, statusLine, worktree, voice, sandbox, sshConfigs — are nested objects.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "opus",
  "outputStyle": "default",
  "theme": "dark",
  "autoCompactEnabled": true,
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": false,
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Bash(npm run build)", "Edit(src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-lib"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 1
  },
  "worktree": {
    "symlinkDirectories": ["node_modules"],
    "baseRef": "fresh"
  },
  "enabledPlugins": {
    "formatter@anthropic-tools": true
  }
}

Authentication and providers

The gateway value of forceLoginMethod is honored only from a source that lives on the machine itself: the policy file, the macOS settings domain, or the HKLM branch. In user, project and local settings, and in HKCU, it counts as unset — otherwise corporate login could be redirected from a repository.

Model, thinking, effort

Three defaults that change behavior and that hardly anyone writes about.

switchModelsOnFlag is on. Which means that when the safety filter fires, the model is swapped silently so the conversation isn't interrupted. Turn it off and an interactive session will stop and ask you, while a non-interactive run will fail the request with an error — for scripts that's often the better behavior, because a silent model swap in CI looks like an unexplained change of behavior.

promptCacheTtl picks itself: an hour on a subscription, five minutes otherwise. The environment variable overrides it.

effortLevel refuses max on purpose, so the top level doesn't stay switched on forever; you set it for a session with a command or a flag.

Tool permissions

The most practically important part of the file — and the most underrated for the number of pitfalls it holds. The nested permissions object:

Alongside them sit top-level keys: skipDangerousModePermissionPrompt and skipAutoPermissionPrompt remember that you've already accepted the corresponding warning; allowManagedPermissionRulesOnly [admin] says to honor only the lists coming from policy; disableAutoMode turns auto mode off; useAutoModeDuringPlan allows using it in plan mode, and defaults to yes.

Modes

dontAsk doesn't mean "don't bother me with the small stuff". This is the most dangerous misunderstanding in the whole permissions topic, and I've repeated it myself. The mode doesn't loosen anything, it tightens it: everything that would raise a question in normal mode is denied automatically. Only what made it into allow, the built-in set of safe read commands, and whatever a hook approved will work. Your own ask rules don't ask in this mode, they refuse; a question from the agent to you is rejected too, even when it's allowed.

One more subtlety: the auto value has no effect from project and local settings — it has to be set in the user file. And sessions launched from the VS Code extension read only the user file, the managed one and --settings.

The shape of a rule

A rule is written as Tool(specifier): Bash(npm run build), Edit(src/**), Read(~/.zshrc).

{
  "permissions": {
    "allow": ["Bash(npm run:*)", "Edit(src/**)", "Read(~/.config/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./secrets/**)", "Read(./.env)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared", "/tmp/workspace"]
  }
}

Looks simple. What comes next is twelve behavioral rules, each of which explains some popular "why doesn't my rule work" question.

Evaluation order: deny first, then ask, then allow

Rules are checked in a fixed order — deny, then ask, then allow — and the first match wins, not the most precise one. Two consequences follow, and both break expectations.

A broad deny overrides a narrow allow: a deny of Bash(aws *) will block an allow of Bash(aws s3 ls). There are no exceptions to a deny — there's no "forbid everything except" mechanism here.

A matching ask asks even when a more precise allow exists. That's not a bug, it's the way to say "this command I always confirm by hand", and it works on top of any permission.

Between settings layers it's the same story: a deny from the user file beats an allow from the project file and vice versa, because every deny from every layer is checked before any allow.

One more small thing with large consequences: a bare tool name in deny removes the tool from the context entirely. An entry of "Bash" in the deny list means the agent never learns the tool exists at all. Whereas Bash(rm *) leaves the tool visible and forbids only the calls that match.

Protected paths are checked before your rules

There's a list of paths whose modification is checked before anything looks at allow. Which is why Edit(.claude/**) in any settings file buys you precisely nothing — and it's the most common source of "why is my permission being ignored" questions.

The protected directories: .git, .config/git, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn and all of .claude except .claude/worktrees. Among files: .gitconfig, .gitmodules, every shell profile and startup file, .envrc, .npmrc, .yarnrc*, .pnp.cjs, bunfig.toml, .bazelrc, .pre-commit-config.yaml, lefthook.*, gradle-wrapper.properties, .ripgreprc, pyrightconfig.json, .mcp.json and .claude.json.

The logic is clear: these are all files whose editing changes how your own machine behaves on the very next command, up to and including what gets executed instead of git commit. What happens when something tries depends on the mode: normal and acceptEdits ask, plan allows it only if a bypass is available, auto hands it to the classifier, dontAsk refuses, bypassPermissions allows. The dialog also carries a separate option — allow editing your own settings for this session.

The deletion safety catch

rm and rmdir aimed at critical paths are approved by nothing: not by a rule in allow, not by a hook that returned an approval.

Critical paths are the filesystem root and any of its immediate children, the home folder, drive roots on Windows and their first-level directories, the current working folder and its parents, plus patterns inside added directories.

The most interesting bit is the table by mode, because it isn't built the way everyone expects:

So the "skip every confirmation" mode is stricter here than auto mode: --dangerously-skip-permissions will still stop on a deletion like that.

Things that look harmless count too: rm -rf "$DIR"/* falls under the safety catch, because an empty variable turns it into a deletion starting at the root. Hiding the command inside a substitution, backticks or a process substitution won't help — the check sees through them.

The four path anchors

Read and Edit rules use .gitignore syntax, and it has four different ways to anchor a path. People mix them up constantly.

The third row is the trap. A single leading slash does not mean an absolute path: it anchors the rule to the settings file it's written in. A Read(/secrets/**) rule in ~/.claude/settings.json means ~/.claude/secrets/**, and not secrets in your project at all. In project settings the same slash counts from the main working folder, in --settings from the folder of the named file, and rules from local settings have since 2.1.211 been anchored to the session's working folder rather than the repository root — so in a separate working copy Edit(/src/**) lands in that copy's own src.

A bare file name behaves the way it does in .gitignore and matches at any depth: Read(.env) is the same thing as Read(**/.env). But Read(//**/.env) is anchored to the filesystem root.

On Windows paths are converted to POSIX form before comparison: C:\Users\alice becomes /c/Users/alice. So a rule covering every drive is written as //**/.env, and one for a specific drive as //c/**/.env.

The same rule catches different depths in allow and in deny

A single-segment relative folder pattern behaves asymmetrically, and that's deliberate.

Edit(src/**) in allow matches only the src folder at the root of the working directory. The very same rule in deny or ask matches a src folder at any depth — so it'll catch vendor/pkg/src/lib.js too.

The intent is clear: a permission should be narrow, a prohibition broad. Every other form behaves identically in any type of rule: Edit(/src/**) and Edit(src/components/**) match only where they're written, Edit(**/src/**) matches everywhere. The behavior changed in 2.1.214: before that, Edit(src/**) caught any depth in permissions as well.

A colon only at the end, and the space before the asterisk matters

The form Bash(ls:*) is exactly the same thing as Bash(ls *). But it's recognized only at the end of a pattern: in Bash(git:* push) the colon is an ordinary character, and the rule won't match anything at all.

The space before the asterisk is part of the rule. Bash(ls *) requires a space and therefore doesn't match lsof; Bash(ls*) does. A trailing asterisk also catches the bare command with no arguments, but only if it's the only one in the rule: Bash(ls *) will match ls, while Bash(* --help *) will match npm --help x and won't match npm --help.

Everything before the first asterisk is compared literally. Hence an unpleasant surprise: Bash(git * main) permits any git subcommand, including -c with arbitrary configuration. Since 2.1.246, allow rules with an asterisk before the subcommand print a warning at startup.

Compound commands

The separators Claude Code understands: &&, ||, ;, |, |&, & and a newline. Each part has to match a rule on its own — there's no blanket permission for the whole line.

A special case: if an operator ends up at the end with nothing after it — npm test &&, say — the command counts as unparseable and isn't split at all. At which point even Bash(npm *) won't approve it.

When you answer "yes, and don't ask again" to a compound command, a separate rule is saved for every part that needed one. A change into a subfolder will produce its own read rule. No more than five rules will be saved out of a single command.

Output redirections >, >>, 2> are checked as a write to a file — against your Edit rules, the protected-path list and the working directories. /dev/null is excluded from the check; a target starting with ~ or containing a pattern always requires confirmation.

Which wrappers get stripped and which don't

Before matching against rules, these are removed from the command: timeout, time, nice, nohup, stdbuf, the built-ins command and builtin, zsh's noglob and a bare xargs — that last one only without flags, since xargs -n1 grep is parsed as the command xargs.

A leading assignment to a known safe variable is stripped too, so Bash(npm test *) will match NODE_ENV=test npm test. An allow rule won't get past an assignment to any other variable, while a deny rule gets past all of them.

The list is fixed and not configurable. And there isn't a single environment launcher in it: npx, docker exec, direnv exec, devbox run, mise exec are not stripped. The practical conclusion: Bash(devbox run *) is a permission for devbox run rm -rf ., because as far as the check is concerned this is the command devbox, not rm.

Separately, there are commands that a prefix rule can never approve: watch, setsid, ionice, flock, and find with -exec or -delete. In normal mode they'll always ask.

Rules for Write, Glob, NotebookEdit and MultiEdit are accepted and don't work

File permissions are checked only against Edit(...) and Read(...) rules. A rule like Write(docs/**) or Glob(docs/**) will be parsed, saved, shown in /permissions — and never used. Since 2.1.210 that prints a warning at startup.

Write Edit(...) instead of Write, NotebookEdit and MultiEdit, and Read(...) instead of Glob. A bare tool name with no path does work, though: you can forbid Write outright.

A useful consequence: a Read deny rule on a path blocks editing and writing there as well — but not NotebookEdit.

Symbolic links

Every access to a file is checked against two paths at once: the link itself and wherever it leads. And the rules are asymmetric about it.

A permission applies only if both paths matched. Which is why a link inside an allowed folder that leads outside it will still ask.

A prohibition applies if at least one matched. Which is why a link to a forbidden file is forbidden itself.

In practice: if Read(./project/**) is allowed and Read(~/.ssh/**) is denied, then ./project/key pointing at ~/.ssh/id_rsa will be blocked.

Rules on tool parameters

A little-known family. Deny and ask rules can match on a scalar field of the tool's input:

{
  "permissions": {
    "deny": ["Agent(model:opus)", "Agent(isolation:worktree)", "Bash(run_in_background:true)"]
  }
}

One parameter per rule, nested fields aren't supported, * stands in for the value. A parameter the model didn't pass never matches — that is, Agent(model:opus) won't catch a call where no model was specified at all. The value is compared against what actually arrived, before normalization: the alias opus will match, the full identifier of the same model won't.

The tool's main field deliberately can't be matched this way: command, file_path, path, notebook_path, url are excluded. The rule Bash(command:rm *) is ignored with a warning — it would be far too easy to slip past with a compound command.

For MCP tools, parameter rules work only through the --disallowedTools flag: any rule with mcp__ and parentheses in a settings file is skipped and lands in the list of invalid settings and in the claude doctor output.

Patterns in the tool name

In deny and ask rules the tool name can be given as a pattern, and it has to cover the whole name: "*" is every tool, "mcp__*" is every MCP tool.

In allow rules a pattern is permitted only after the literal prefix mcp__<server>__, and the server name itself must contain no patterns. So mcp__github__get_* works, while "*", "B*" and "mcp__*" in allow are skipped with a warning and permit nothing.

And one more trap: the tool name on screen can differ from the canonical one. What's shown as "Stop Task" is canonically called TaskStop, and only the canonical name works in rules and in hook filters.

WebFetch — two different rules that look alike

A bare WebFetch and WebFetch(domain:*) are not the same thing, because the second form also edits the sandbox's domain list.

Patterns in a domain: *.example.com catches subdomains at any depth, but not example.com itself. In any other position an asterisk matches only the text between two dots — example.* will catch example.org and won't catch example.evil.com.

And a sober note: as long as the agent has shell access, WebFetch permissions don't restrict network access in any way whatsoever.

The built-in set of safe commands

Some commands run without a question in any mode, and that list is hard-wired: ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd and read-only forms of git. You can't extend it, only override it with your own ask or deny rule.

But even it will ask if: an unquoted pattern shows up in a command that has write or execute flags (find, sort, sed, git — the pattern could expand into -delete); docker has -H, --context, --url or --connection; file has -m, --magic-file, -f or --files-from; the arguments contain a Windows network path; the command is longer than ten thousand characters or doesn't parse. Plus cd together with git will ask if the folder really does change — the new folder may have git hooks of its own.

PowerShell

Rules for PowerShell are built the same way, are compared case-insensitively and normalize the popular aliases: PowerShell(Get-ChildItem *) will match gci, ls and dir alike. The command is parsed into a syntax tree and split on |, ;, and on version seven also on && and ||; each part is checked separately.

Remove-Item has a check of its own, stricter than the one for rm: system paths and targets with a pattern — a bare *, anything ending in /* or \*, $dir/* included — are forbidden in every mode without asking, before the classifier even gets a look. Only the "working folder or its parent, recursively" case goes through the mode's normal rules, and that one is lifted by bypassing confirmations.

And separately about Windows: any command with a network path of the form \\server\share\file among its arguments will ask for confirmation even if it's harmless in every other respect — a path like that can steal Windows credentials.

Auto mode

Since 14 August 2026 this is the default mode for new sessions on Pro, Max and Team. Every action is decided by a classifier rather than by a list of rules, and it's configured through a separate autoMode object.

Three things here matter more than the table itself.

The string "$defaults" is required almost always. In any of the four lists it mixes in the stock set of rules. Leave it out and the entire built-in list for that section silently disappears — along with the soft blocks on force-push, on curl | bash, on deploying to production and on bypassing auto mode itself, and with the hard block on data exfiltration. Your rules are meant to extend the set, not replace it.

Narrow permissions bypass the classifier. A rule like Bash(npm test) keeps working in auto mode and is resolved before the classifier. Only broad permissions for arbitrary execution get suspended — Bash(*), interpreters with a wildcard — along with every rule that names a monitoring tool. Which means a narrow rule can let through a destructive argument nobody ever looked at. The fix is classifyAllShell: true, which disables every shell-allow rule for the duration of auto mode.

The classifier doesn't read project settings. It takes autoMode only from the user file, the enterprise one and --settings. Otherwise a repository could hand itself permissions; local settings were read up to version 2.1.207, but not any more.

You can inspect and pick apart the configuration from the terminal:

claude auto-mode config                       # what's in effect and where it came from
claude auto-mode defaults                     # the stock rules of all four lists
claude auto-mode defaults --label 'Git Destructive'   # the full text of a single rule
claude auto-mode critique                     # a model's critique of your rules
claude auto-mode reset --yes                  # reset to stock without asking

The critique subcommand is underrated: it asks the model to go through your own rules and point out the ones that are ambiguous, redundant, or bound to fire falsely.

The mode is turned off with the disableAutoMode key, and there's a trap here: the value has to be the string "disable". An array or true passes the schema without an error, but the code compares against exactly that string, and the mode quietly stays on. You can hide the setup wizard with "auto-mode-setup": "off" in skillOverrides; disableBundledSkills doesn't turn it off, because it's a built-in command, not a skill.

MCP servers

That last row corrects a widespread claim I used to repeat myself: "servers are defined only in .mcp.json, and settings only carry the permissions for them". True for you, but not for an administrator: managedMcpServers in enterprise settings holds actual server configurations and is rolled out to everyone through the policy file or a device management system.

Ordinary servers, meanwhile, are defined in .mcp.json or through claude mcp add.

Hooks

Hooks deserve an article of their own, and I have one: it goes through every event, the exchange formats and working examples. Here — the settings keys and the things that break most often.

hooks is an object of the shape "event → array of matchers". A matcher has a matcher filter and a list of handlers.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint" },
          { "type": "command", "command": "echo", "args": ["done"] }
        ]
      }
    ]
  }
}

There are thirty-three events. For tools: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch. For the conversation: UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, Notification, MessageDisplay. For the session: SessionStart, SessionEnd, Setup, InstructionsLoaded, ConfigChange. For compaction and model switching: PreCompact, PostCompact, PreModelSwitch, PostModelSwitch. For permissions: PermissionRequest, PermissionDenied. For subagents and tasks: SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted. For files and directories: FileChanged, CwdChanged, DirectoryAdded, WorktreeCreate, WorktreeRemove. And two for MCP forms: Elicitation, ElicitationResult.

A handler comes in five kinds, set by the type field: command runs a program or a shell string, prompt asks a small fast model, agent dispatches a full-blown agent, http hits a URL, mcp_tool calls a tool on an MCP server. The shared optional fields are if with a condition, timeout, statusMessage for the spinner, once for a single run per session, and async with its relative asyncRewake.

Three reasons a hook "runs but does nothing"

Exit code 1 blocks nothing. Only code 2 blocks, and only on about a third of the events. A 1, or any other non-zero code, is on most events just a non-blocking error in the log. And a 2 outranks your own JSON: even if you returned an "allow" decision, the 2 denies.

Where a 2 blocks: PreToolUse, UserPromptSubmit (erasing the prompt), UserPromptExpansion, Stop, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted, ConfigChange, PostToolBatch, PreModelSwitch. Where it's ignored: PermissionRequest and PermissionDenied — there the JSON fields decide — and StopFailure. On PostToolUse a 2 doesn't block, it gets shown to the model. On WorktreeCreate any non-zero code aborts. And one more asymmetry: a timeout on PreToolUse doesn't block, while on PreModelSwitch it does.

The model almost never sees a hook's output. Plain text on standard output with exit code 0 lands in the debug log, not in the conversation. It's shown to the model on exactly four events: UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch. The error stream is never shown anywhere, ever. On the other events the only way to get something to the model is a structured response — the additional-context field or a system message. And the JSON is parsed only if the output starts with { and ends with }.

The filter is sometimes ignored entirely, and sometimes a regular expression. "*", an empty string, or a missing field all mean "everything". A filter made up only of letters, digits, _, -, spaces, commas and | is an exact match or a list of alternatives. Any other character turns it into a regular expression, which is matched unanchored unless you write the anchors yourself. Case matters.

And the filter isn't always about a tool name. On SessionStart it's compared against how the session started, on SessionEnd against the reason it ended, on compaction against manual or auto, on ConfigChange against which settings file changed, on FileChanged against the file name, on a model switch against the canonical model name. While UserPromptSubmit, PostToolBatch, Stop, CwdChanged, TeammateIdle, the task events, the worktree ones and MessageDisplay take no filter at all and silently ignore whatever you wrote.

The default timeouts aren't uniform: command, http and mcp_tool get ten minutes, except thirty seconds on UserPromptSubmit and on the model-switch events, and ten on MessageDisplay; prompt gets thirty seconds, agent gets a minute; all the SessionEnd hooks together get a second and a half. Async ones aren't limited at all.

On Windows it's worth remembering the form with a separate argument list: it runs without a shell and needs a real executable — .cmd and .bat wrappers require either the string form or launching through an interpreter.

Git: commits, pull requests, attribution

{
  "attribution": { "commit": "", "pr": "" },
  "includeGitInstructions": true
}

Interface and terminal

Values for theme: auto (from the terminal background), dark, light, light-daltonized, dark-daltonized, light-ansi, dark-ansi, plus custom:<name> for a theme from ~/.claude/themes/ and custom:<plugin>:<name> for one from a plugin.

Some keys are read only from the user file, --settings and policy: spinnerTipsOverride with a tips file, footerLinksRegexes and spellcheck. A project file can't override them — otherwise a repository could paint an arbitrary link into your interface.

Settings that live in ~/.claude.json

These keys are silently ignored in settings.json. Usually Claude Code or /config writes them itself, but they're worth knowing about.

The first key is worth learning about: Ctrl+E on a prompt asking whether to run a command gives you a human explanation of what that command does — without running it. On an unfamiliar command from someone else's repository that's exactly the button you've been missing.

Status line

Fields of statusLine: type with the value "command", command with the script, padding, refreshInterval — recompute once every so many seconds — and hideVimModeIndicator if the script draws the vim mode itself.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 1,
    "refreshInterval": 5
  }
}

The script receives JSON on its input with the session context: model, directory, cost, context fill. It prints one line. This is probably the most underrated setting of the lot: permanently visible spend figures change behavior far more than any instruction about being frugal. Just keep in mind that disableAllHooks turns it off too.

Context, memory, sessions

Two things are worth knowing about autoContinueAtUsageLimit: it's on by default, and it's read only from the user file, --settings and policy — meaning a project or local file that sets it isn't ignored, it turns the feature off.

Skills

skillOverrides is worth knowing for anyone with a lot of skills: their descriptions sit in the context permanently, and name-only on the rarely needed ones frees up a noticeable chunk. That same key is also how you stop the agent from running a particular command on its own while keeping it available to you: the value user-invocable-only.

Plugins and marketplaces

Workflows, agents, teammates

The auto value of teammateMode is precisely defined: split panes if the session is running inside tmux, or inside iTerm2 with its command line utility available, or if tmux is installed; otherwise everything runs inside the process. The iterm2 value means iTerm2's native split panes, and it arrived in 2.1.186.

The teammateDefaultModel key is still in the schema, but it was removed from the product in 2.1.234 and affects nothing.

Worktrees

The nested worktree object controls how separate working copies are created for sessions and background agents.

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/app", "packages/shared"],
    "baseRef": "fresh",
    "bgIsolation": "worktree"
  }
}

Remote control, SSH, environments

Three of these keys accept only a real boolean true: the string "true" or a 1 will be ignored, with a warning in the log. They are disableDesktopLocalSessions, disableBrowserExternalNavigation and disableMobileSimulatorTools. The terminal CLI doesn't read them at all — they're about the desktop app.

requireCoworkFullVmSandbox has an important side effect: inside a full virtual machine there is neither a device policy nor an enterprise settings file — you'll have to deliver those some other way.

{
  "remote": { "defaultEnvironmentId": "env-123" },
  "sshConfigs": [
    {
      "id": "prod-box",
      "name": "Prod",
      "sshHost": "[email protected]",
      "sshPort": 22,
      "startDirectory": "~/app"
    }
  ]
}

Notifications, voice, breaks

{
  "voice": { "enabled": true, "mode": "hold", "autoSubmit": true },
  "breakReminder": { "enabled": true, "intervalMinutes": 120 },
  "quietHours": { "enabled": true, "start": "22:00", "end": "07:00" }
}

Sandbox and network

The sandbox object controls what processes inside the isolation are allowed to do. It's the longest section of the schema and the least used one — but if you let the agent run in a mode where it doesn't ask for permissions, this is exactly the section to read.

Let me correct a common structural mistake right away: read and write paths live not directly in sandbox, but in sandbox.filesystem. A rule like "sandbox": {"denyRead": [...]} won't do anything.

Three things are worth calling out.

allowUnsandboxedCommands is on by default. Meaning the agent can retry a sandbox-blocked command outside the sandbox through a special parameter. If you turned the sandbox on for isolation, that's most likely not what you wanted — switch it off with an explicit false.

enabledPlatforms makes the configuration inert as a whole. On a system that isn't in the list there is no sandbox, no automatic permissions, no warning at startup, and no failure from failIfUnavailable. Silently, as if the section weren't there.

Secret masking doesn't work everywhere. On macOS and Windows the mask mode degrades into deny: there's nothing there to substitute the value on the fly. Masking entries also have an onExtractNoMatch field — what to do when the regular expression found nothing: warn (the default) lets the variable through unmasked, deny strips it inside the sandbox, error stops the run.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": ["api.example.com", "*.githubusercontent.com"],
      "deniedDomains": ["telemetry.example.com"]
    },
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws"],
      "denyWrite": ["~/.config"]
    }
  }
}

Updates and everything else

The schema accepts a few more housekeeping keys: modelProposedGoals, totalTokensReminder with its relatives, and disableDeepLinkRegistration. They're internal, never surface in the interface, and aren't documented anywhere.

Environment variables

The env block in the settings is a "name → value" object. Every value is a string: numbers and flags go in quotes, "PORT": "3000", a flag is "1".

An honest caveat about completeness: the official documentation lists three hundred and forty-nine variables by name, including per-region ones for every model at every provider plus the whole telemetry set. Retelling them here would be pointless. Below are the ones actually used, plus the behavior of the env block, which isn't collected in one place anywhere.

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "ANTHROPIC_MODEL": "claude-opus-5",
    "BASH_DEFAULT_TIMEOUT_MS": "120000",
    "DISABLE_TELEMETRY": "1"
  }
}

How the env block behaves

It beats an export from the shell. The value from the settings file is written into the process environment on top of the inherited one. That's exactly the opposite of what people usually expect.

A variable can't be deleted — only set to an empty string. When a provider is picked an empty value counts as unset, but child processes get exactly that empty string.

Values are re-read on the fly when the file changes — except for subsystems configured only at startup, such as telemetry. And since 2.1.246, /cd layers the new folder's env over the old one.

Project and local settings aren't allowed everything. Three groups are dropped: variables that set file locations (CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR, TMP, TEMP, XDG_*); variables that turn on dumping session contents (OTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED, BETA_TRACING_ENDPOINT); and variables affecting startup and syncing (CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, the plugin cache and seed folder). The list grew in 2.1.251, as it happens. The warning about it is only visible under debug.

A few more variables are ignored in any file and read only from the launch environment: CLAUDE_CODE_REMOTE, CLAUDE_CODE_ACCOUNT_UUID, the cross-session exchange socket and token, CLAUDE_CODE_PROJECT_DIR_NAME and CLAUDE_CODE_RESTRICTED.

And the other direction, which hardly anyone writes about: Claude Code sets variables for child processes itself. They're visible from hooks and from any script it launches: CLAUDECODE=1, CLAUDE_CODE_CHILD_SESSION=1, CLAUDE_CODE_SESSION_ID, CLAUDE_PID — its own process id, CLAUDE_EFFORT with the current effort level (the ultracode mode shows up as xhigh), and in cloud sessions CLAUDE_CODE_REMOTE=true plus the remote session id. A hook that needs the effort level, or needs to tell a child session from the main one, takes it from here instead of guessing.

Providers and authentication

There are more than two or three providers, by the way: besides the Anthropic API, Amazon Bedrock and Google Cloud, there's support for Microsoft Foundry and Claude Platform on AWS, and each has its own set of variables and its own mapping of aliases to models.

Models, context, limits

Behavior and environment

Three traps in this table are worth spelling out.

MCP timeouts differ by five orders of magnitude. Server startup is thirty seconds. But a tool call defaults to roughly twenty-eight hours — effectively no limit at all. On top of that, HTTP servers and cloud connectors cap every request at a minute, and that's a separate limit.

CLAUDE_CODE_PROJECT_DIR_NAME does nothing on its own — only together with CLAUDE_CONFIG_DIR, and only from the environment, not from a settings file.

Safe mode takes away more than it looks like. CLAUDE_CODE_SAFE_MODE isn't just instructions and skills: it also skips plugins, hooks, MCP servers, your own commands and agents, output styles, workflows, themes, keybindings, the status line, the file suggestion source, language servers and auto-memory. All that's left is corporate policy, including the hooks and status line it defines. It's a "turn off everything I configured" debugging mode, and for tracking down a broken configuration it's perfect.

Rendering and accessibility

In one line, because there are many variables and you need them rarely. The classic renderer comes back with CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN, and it's stronger than both CLAUDE_CODE_NO_FLICKER and the tui setting. There are separate switches for the mouse and clicks, scroll speed, virtual scrolling, full redraw, the native cursor, syntax highlighting, hyperlinks and truecolor in tmux. For accessibility there's CLAUDE_AX_SCREEN_READER and its relatives.

Privacy, telemetry, updates

Three things here catch people out.

DISABLE_BUG_COMMAND isn't a separate switch. It's the old name of DISABLE_FEEDBACK_COMMAND, and the one variable turns off /feedback, the feedback drafts, and /bug with /share as well, because they all go through the same channel.

A value of 0 doesn't turn it back on. For CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC any presence of the variable, including 0 and false, disables the traffic. To get it back you have to remove the variable entirely.

Turning telemetry off also turns features off. Along with the feature flags, these stop working: auto mode by default, /auto-mode-setup, remote control, /import, /schedule, the advisor, artifact comments, the new MCP client and the PowerShell tool being the default on Windows. It's a deliberate trade-off rather than a side-effect bug, but it's worth knowing before you spend half an hour hunting for where remote control went.

Here's what "all non-essential traffic" actually covers: auto-updates, telemetry, error reports, feedback submission, release notes, refreshing the model list from a gateway, and availability checks. Plus — unexpectedly — background execution of local plugin source commands, because those can drag a dependency install along with them. What it doesn't cover is the auto-install of the official marketplace; that has its own variable.

Terminal commands and flags

Everything you type outside a session, in your regular shell. Each subcommand below gathers everything in one place: its own subcommands and flags, the quirks and the examples.

First things first, and this is the official wording, not my own observation: claude --help does not list every flag. A flag missing from the help doesn't mean it doesn't exist. Below I mark what the help leaves out — there are at least a dozen such flags, and among them perfectly usable things like capping the number of turns.

Get a subcommand name wrong and you'll be offered the closest match and dropped out without a session starting: claude udpate gets you a question about whether you meant claude update.

Subcommands

claude [prompt]

Start an interactive session. With a prompt — start straight from it.

claude                                    # interactive session
claude "fix the failing test in orders"   # a session that starts with the task

claude -p "<prompt>"

A non-interactive run: print the answer and exit. The main mode for scripts.

claude -p "what does this script do?"     # answer and exit

claude auth login|logout|status

Log in, log out, and check authorization status. Status is printed as JSON.

claude auth login --console               # log in through Console billing
claude auth logout                        # log out
claude auth status                        # authorization status as JSON

claude setup-token

Issue a long-lived authorization token. Requires a subscription.

claude setup-token                        # long-lived token for CI

claude agents

The management screen for background agents; it's also how you launch them.

claude agents                             # the background agents screen

claude attach <id>

Open a background session in this terminal.

claude attach a1b2c3                      # attach to a background session

claude logs <id>

Print the latest output of a background session.

claude logs a1b2c3                        # latest output of a background session