Launch with claude, resume with -c or --resume, isolate a branch with -w, and automate with -p. Inside a session, use /context before the window gets crowded, /compact to preserve one workstream, /clear between unrelated tasks, /plan before a large change, and /usage to inspect tokens and limits. Configuration is split across CLAUDE.md, settings files, skills, hooks, MCP server definitions, and permission rules; each solves a different problem.
claude -w nameis the fastest safe start for parallel work;claude -pis the automation surface./clear,/compact, and/resumedo different jobs. Do not use them interchangeably.- Use CLAUDE.md for facts, skills for procedures, hooks for invariants, and settings for policy.
- Permission modes set the baseline;
allow,ask, anddenyrules handle exceptions. - MCP credentials define the real reach of an MCP server. A read-only prompt does not make a write credential read-only.
- On subscriptions, token cost maps to usage limits rather than an invoice. On API billing, JSON output reports invocation cost.
Start, stop, resume, and branch
The launch form decides the session history, working directory, isolation, and whether a human interface exists. These are the forms worth memorising.
Core CLI forms. Checked against the Claude Code CLI reference, August 2026.
| Command | What it does | Use it when |
|---|---|---|
claude | Start an interactive session in the current directory | Ordinary work |
claude "task" | Start interactively with an initial prompt | You know the first instruction |
claude -c | Continue the most recent session associated with this directory | Returning to the last workstream |
claude --resume | Open the local session picker | Several sessions exist |
claude --resume auth-refactor | Resume a named session directly | Stable, named workstreams |
claude -n auth-refactor | Name the session at launch | You intend to resume it |
claude --continue --fork-session | Copy the latest conversation to a new session ID | Trying another approach without changing the original transcript |
claude -w feature-auth | Create an isolated checkout and branch under .claude/worktrees/ | Parallel or risky code changes |
claude --bg "task" | Start a supervised background session and return immediately | Work that should continue without occupying the terminal |
claude agents | Open agent view for background sessions | Dispatching and monitoring several sessions |
claude -p "task" | Run non-interactively, print the result, and exit | Scripts and CI |
claude --cloud "task" | Create a Claude Code web session | The task should outlive the local process |
claude --teleport | Pull a web session and its branch into the terminal | Continuing cloud work locally |
claude remote-control | Expose a local agent through outbound HTTPS to Claude.ai or mobile | Steering your own machine remotely |
CLI flags by job
Flags below are grouped by the decision they change. The official reference includes plan-, platform-, and version-specific options beyond this operational set; claude --help also does not list every supported flag.
Session, model, context, and tool flags.
| Flag | Effect | Example |
|---|---|---|
--model | Select an alias or full model ID for this session | claude --model sonnet |
--effort | Set reasoning effort for the session | claude --effort high |
--permission-mode | Start in default, acceptEdits, plan, auto, dontAsk, or bypassPermissions | claude --permission-mode plan |
--add-dir | Grant access to more working directories; most configuration there is not discovered | claude --add-dir ../shared |
--worktree, -w | Start in an isolated git worktree; accepts a name, PR number, or PR URL | claude -w #418 |
--name, -n | Set a resumable display name | claude -n payments-fix |
--continue, -c | Resume the latest session for this directory | claude -c |
--resume | Resume by picker, name, or session ID | claude --resume payments-fix |
--fork-session | Create a new transcript from resumed history | claude -c --fork-session |
--autocompact | Override the auto-compact window for one session | claude --autocompact 500k |
--bare | Skip CLAUDE.md, auto memory, hooks, skills, plugins, and MCP discovery | claude --bare -p "summarise README.md" |
--settings | Overlay a settings file or inline JSON for this invocation | claude --settings ./ci-settings.json |
--allowedTools | Pre-approve matching tools; does not remove other tools | --allowedTools "Read" "Bash(git diff *)" |
--disallowedTools | Deny matching tools for this invocation | --disallowedTools "Write" "Edit" |
--tools | Restrict the built-in tool set Claude can see | --tools "Read,Grep,Glob" |
--dangerously-skip-permissions | Enter bypass mode; intended only for an isolated container or VM | claude --dangerously-skip-permissions |
--allow-dangerously-skip-permissions | Add bypass mode to the mode cycle without selecting it | --permission-mode plan --allow-dangerously-skip-permissions |
--mcp-config | Load MCP definitions from JSON files or strings | claude --mcp-config ./mcp.json |
--strict-mcp-config | Ignore every MCP source except the supplied config | --strict-mcp-config --mcp-config ./ci-mcp.json |
--agent / --agents | Select a custom subagent or define subagents inline as JSON | claude --agent reviewer |
--chrome / --no-chrome | Enable or disable the Chrome integration | claude --chrome |
--append-system-prompt | Keep the default prompt and add instructions | --append-system-prompt "Return file:line evidence" |
--system-prompt | Replace the default prompt, including its tool guidance | --system-prompt "You are a release-note writer" |
Non-interactive and CI flags.
| Flag | Effect | Example |
|---|---|---|
--print, -p | Print a response without the interactive UI | claude -p "review this diff" |
--output-format | Return text, json, or newline-delimited stream-json | --output-format json |
--input-format | Read text or stream-json input | --input-format stream-json |
--json-schema | Validate the final structured output against JSON Schema | --json-schema "{...}" |
--max-turns | Stop after a bounded number of agent turns | --max-turns 6 |
--max-budget-usd | Cap API spend, including subagents, in print mode | --max-budget-usd 3.00 |
--no-session-persistence | Do not save this print-mode transcript | --no-session-persistence |
--verbose | Show full turn-by-turn output; required for partial stream events | --output-format stream-json --verbose |
--include-partial-messages | Include streaming token deltas | --verbose --include-partial-messages |
--include-hook-events | Include hook lifecycle events in stream JSON | --include-hook-events |
git diff main...HEAD | claude -p "Report only correctness bugs as JSON." --permission-mode dontAsk --allowedTools "Read" "Grep" "Glob" --output-format json --max-turns 8 --max-budget-usd 2.00
Slash commands that change the session
Type / to filter everything available in your installed version. The menu includes built-ins, bundled skills, your own skills, plugins, and MCP prompts, so the exact list is configuration-dependent.
Context, session, and navigation commands.
| Command | Use |
|---|---|
/context [all] | Show what consumes the context window and where it is overloaded |
/compact [focus] | Replace history with a focused summary and continue the same conversation |
/clear [name] | Start empty context while preserving the old session for resume |
/resume [name] | Switch to a saved local conversation |
/rename name | Give the current session a stable, resumable name |
/branch [name] | Copy the conversation into a new session and leave the original unchanged |
/rewind | Restore conversation, code checkpoints, or both |
/export [file] | Save the conversation as readable plain text |
/cd path | Move the session and load the new directory context |
/add-dir path | Grant another working directory without moving |
/desktop | Save and continue this session in the desktop app |
/remote-control | Make the local session reachable from Claude.ai or mobile |
/teleport | Pull a web session and branch into this terminal |
/tasks | Inspect background Bash calls and subagents in this session |
/btw question | Ask a side question without adding it to the main conversation |
Configuration, inspection, and work commands.
| Command | Use |
|---|---|
/plan [task] | Enter read-only plan mode and optionally start the task |
/permissions | Inspect or edit allow, ask, deny, and directory rules |
/model [model] | Switch model; use arrow keys in the picker to adjust effort |
/effort [level] | Set reasoning effort or reset it to auto |
/usage | Show session tokens or cost, subscription windows, and activity |
/memory | List and edit CLAUDE.md files and auto memory |
/hooks | Inspect hooks by lifecycle event |
/mcp | Inspect, authenticate, reconnect, enable, or disable MCP servers |
/skills | List skills and inspect their token footprint |
/reload-skills | Re-scan skills added or changed during the session |
/config key=value | Change supported settings without opening the UI |
/doctor | Diagnose installation, config, hook, MCP, plugin, and memory problems |
/diff | Review the current git diff and per-turn diffs |
/code-review [level] [--fix] | Run a fresh review subagent against a diff, branch, path, or PR |
/sandbox | Inspect or toggle the OS-level Bash sandbox |
/run / /verify | Build and exercise the app instead of stopping at static checks |
/init | Generate an initial CLAUDE.md from the repository |
/help | Show commands available in this installation |
Keyboard shortcuts
General controls. Terminal mappings can override these.
| Shortcut | Action | Detail |
|---|---|---|
Esc | Interrupt | Stops the current response or tool call; completed work stays |
Esc Esc | Rewind or summarise | Opens the checkpoint selector |
Ctrl+C | Cancel input or generation | Standard interrupt |
Ctrl+D | Exit | EOF from an empty prompt |
Ctrl+O | Toggle transcript viewer | Expands detailed tool and MCP activity |
Ctrl+R | Reverse history search | Use Ctrl+S inside search to change scope |
Ctrl+B | Background a task | Press twice under tmux |
Ctrl+T | Toggle task list | Shows work in the terminal status area |
Ctrl+G | Open external editor | Edits the prompt or proposed plan |
Ctrl+L | Redraw | Repairs a garbled terminal without clearing input |
Ctrl+V / Cmd+V | Paste image | Terminal-dependent clipboard support |
Shift+Tab | Cycle permission modes | Default cycle is Manual, Accept Edits, Plan |
Option+P / Alt+P | Switch model | Does not clear the typed prompt |
Option+T / Alt+T | Toggle extended thinking | Availability depends on model and version |
Option+O / Alt+O | Toggle fast mode | Where the account and model support it |
Ctrl+X Ctrl+K | Kill background subagents | Press twice within three seconds to confirm |
Prompt editing and multiline input.
| Shortcut | Action |
|---|---|
Ctrl+A / Ctrl+E | Move to start / end of the current line |
Ctrl+K / Ctrl+U | Delete to end / start of line |
Ctrl+W | Delete the previous word |
Ctrl+Y | Paste text deleted by the readline controls |
Alt+B / Alt+F | Move backward / forward one word |
\ then Enter | Insert a newline in every terminal |
Shift+Enter | Insert a newline in supported terminals; run /terminal-setup elsewhere |
Ctrl+J | Insert a newline without terminal configuration |
! at an empty prompt | Enter direct shell mode; command and output enter context |
@ | Reference files and directories with autocomplete |
/ | Open and filter commands and skills |
Permission modes and rules
The six modes as of August 2026.
| Mode | Runs without asking | Use for |
|---|---|---|
default / manual | Reads and the built-in read-only command set | Sensitive or unfamiliar work |
acceptEdits | Reads, file edits, and common local filesystem commands | Normal implementation in a reviewed branch |
plan | Read-only exploration | Architecture and large changes before editing |
auto | Actions approved by a background safety classifier | Long interactive tasks with fewer prompts |
dontAsk | Only read-only operations and explicitly allowed tools | Locked-down CI |
bypassPermissions | Everything | Isolated containers and VMs only |
Rules use Tool(specifier). Claude Code evaluates deny, then ask, then allow; a more specific allow never overrides a broad deny.
{
"permissions": {
"defaultMode": "plan",
"allow": [
"Bash(npm test *)",
"Bash(npm run lint *)",
"Bash(git diff *)",
"Read(src/**)",
"Edit(src/**)"
],
"ask": ["Bash(git push *)"],
"deny": [
"Read(.env)",
"Read(.env.*)",
"Read(~/.ssh/**)",
"Bash(rm -rf *)",
"Bash(git reset --hard *)"
]
}
}
CLAUDE.md, settings, rules, skills, and auto memory
Put each instruction in the mechanism that matches its lifetime.
| Mechanism | Location | Loads | Use for |
|---|---|---|---|
| Project memory | ./CLAUDE.md or ./.claude/CLAUDE.md | Every session in the project | Commands, conventions, traps |
| Personal project memory | ./CLAUDE.local.md | Every local session; gitignore it | Your non-shared notes |
| User memory | ~/.claude/CLAUDE.md | Every project | Preferences that are genuinely universal |
| Path rules | .claude/rules/*.md | At launch or when a paths: glob matches | Part-of-tree constraints |
| Skills | .claude/skills/name/SKILL.md | Only when invoked or selected | Procedures, checklists, long reference material |
| Auto memory | ~/.claude/projects/.../memory/ | Index at launch, topic files on demand | Learnings Claude records from corrections |
| Team settings | .claude/settings.json | Configuration layer; commit it | Permissions, hooks, model, sandbox, environment |
| Local settings | .claude/settings.local.json | Higher precedence; gitignore it | Personal overrides |
| MCP project config | .mcp.json | After workspace approval | Shared external tools |
# Commands
- `pnpm test path/to/file.test.ts` runs one test file.
- `pnpm lint --fix` must pass before handoff.
# Conventions
- Named exports only.
- Store money as integer minor units.
- Never edit `src/generated/`.
# Traps
- Integration tests require `docker compose up -d db`.
Hooks: events and a working formatter hook
Hooks run deterministic code at lifecycle events. Use them for an invariant that must hold regardless of whether the model remembers the instruction.
The hook events used most often.
| Event | When | Typical use |
|---|---|---|
SessionStart | A session starts or resumes | Load environment or context |
UserPromptSubmit | Before Claude receives a prompt | Validate or enrich input |
PreToolUse | Before a matching tool executes | Block dangerous commands |
PermissionRequest | A call needs a decision | External approval policy |
PostToolUse | After a tool succeeds | Format edited files |
PostToolUseFailure | After a tool fails | Collect diagnostics |
SubagentStart / SubagentStop | A delegated worker starts or finishes | Audit parallel work |
Stop | Claude is about to finish a turn | Run a final verification gate |
PreCompact / PostCompact | Around context compaction | Persist and restore state |
InstructionsLoaded | A CLAUDE.md or rule enters context | Debug memory discovery |
WorktreeCreate / WorktreeRemove | Worktree lifecycle | Replace git setup or cleanup |
SessionEnd | The session terminates | Cleanup and telemetry |
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r .tool_input.file_path | xargs npx prettier --write"
}
]
}
]
}
}
MCP server commands and scopes
Add and manage MCP servers without hand-editing JSON.
| Command | Result |
|---|---|
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp | Add a remote HTTP server at local scope |
claude mcp add --transport http shared --scope project https://example.com/mcp | Write a shared server to .mcp.json |
claude mcp add --transport http hub --scope user https://example.com/mcp | Add a private server for every project |
claude mcp add --env KEY=value --transport stdio local -- npx -y server | Add a local process; -- separates Claude flags from server args |
claude mcp add-json events "{...}" | Add a server from a JSON definition |
claude mcp list | List servers and connection health |
claude mcp get name | Show one server, scope, status, and failure detail |
claude mcp remove name | Remove the server from the selected scope |
/mcp | Authenticate, reconnect, enable, or disable from a session |
MCP scopes.
| Scope | Stored in | Shared? |
|---|---|---|
local (default) | ~/.claude.json, keyed to this project | No |
project | .mcp.json at the repo root | Yes; commit it |
user | ~/.claude.json | No; available to all your projects |
Worktrees, subagents, and parallel work
Three kinds of parallelism, three different boundaries.
| Mechanism | Context | Files | Use when |
|---|---|---|---|
| Subagent | Fresh window; returns a summary | Same checkout unless isolated | Research or review would flood the main context |
| Background session | Independent conversation | Should use its own worktree for edits | You want to inspect and steer it separately |
| Worktree session | Independent conversation | Separate checkout and branch | Two code-changing sessions must not collide |
claude -w feature-auth
claude -w fix-timeout
git worktree list
git worktree remove .claude/worktrees/ci-review
git worktree prune
A worktree shares git history, refs, remotes, and objects with the main checkout. It does not share tracked file contents, untracked files, staged changes, or dependency installs. Put required gitignored setup files in .worktreeinclude; tracked files are never copied by that mechanism.
---
name: reviewer
description: Review the current branch for correctness bugs.
tools: Read, Grep, Glob, Bash
model: sonnet
isolation: worktree
---
Review the diff against the merge base. Report only reproducible correctness or security findings with file and line evidence.
Context, tokens, usage, and cost
The controls that affect context and spend.
| Control | What it changes | Rule of thumb |
|---|---|---|
/context | Shows the current context composition | Run it when Claude rereads files or forgets constraints |
/compact focus | Summarises one continuing workstream | Use before forced automatic compaction |
/clear | Starts an empty conversation | Use between unrelated tasks and after repeated failed corrections |
| Subagent | Keeps noisy exploration in another window | Delegate searches, logs, and independent review |
/model | Changes capability, latency, and limit burn | Use the least expensive model reliable for the task |
/effort | Changes reasoning depth on supported models | Raise for architecture; lower for mechanical work |
/usage | Shows tokens or API cost, subscription windows, and activity | Check before another large parallel run |
--max-turns | Bounds automation length | Every CI call should have one |
--max-budget-usd | Caps API spend in print mode | Pair it with max turns |
--output-format json | Returns usage metadata and total_cost_usd | Record it per CI invocation |
Input is not paid once. Each turn includes the conversation, instructions, tools, relevant files, and recent output again, with prompt caching reducing the price of stable prefixes. Large MCP catalogs, verbose memory files, unbounded logs, and long correction chains therefore have a recurring cost.
Questions people ask
/context is the best diagnostic command because it shows why a session is becoming slow or forgetful. For daily navigation, name sessions with /rename and return with claude --resume <name>.
Run claude --permission-mode plan, press Shift+Tab until Plan appears, or prefix one task with /plan. Claude can read and explore but does not edit source until you approve the plan or change mode.
Use claude -p "task". Add --output-format json, --permission-mode dontAsk with explicit allowed tools, and --max-turns plus --max-budget-usd to bound the run.
Press Escape to interrupt the current response or tool call while preserving completed work. Ctrl+C cancels input or generation, and Ctrl+D exits from an empty prompt.
/clear starts a new empty conversation and preserves the old one for resume. /compact keeps the current conversation but replaces earlier history with a summary.
Project instructions live in CLAUDE.md, policy in .claude/settings.json, personal overrides in settings.local.json, shared MCP servers in .mcp.json, procedures in .claude/skills/, and lifecycle actions in hooks.
Start each code-changing session with claude --worktree <name> or claude -w <name>. Every session gets a separate checkout and branch under .claude/worktrees/.
Run /usage (/cost is an alias). API users see estimated session cost and can collect total_cost_usd from JSON output. Subscription users primarily see rolling usage windows and activity.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.