Claude Code: Commands, Configuration, and Hooks¶

Claude Code has two command surfaces. The claude executable starts or resumes a process from the shell; commands beginning with / operate inside an active session. Around those commands sit settings files, permission rules, hooks, skills, subagents, and MCP servers. This chapter is a map of that surface: what each control changes, where its state is stored, and how the pieces connect.

The command set changes fairly often. /help shows what is present in the installed version, while Anthropic's commands reference and CLI reference describe the current release. Some commands also depend on platform, account plan, or an enabled experimental feature.

Starting from the shell¶

With no prompt, claude opens an interactive session in the current directory:

claude

A positional argument becomes the first prompt:

claude "explain how authentication reaches the database"

-p or --print runs non-interactively, prints the result, and exits. It is the form used in pipes and scripts:

claude -p "summarize the changes under src/"
git diff | claude -p "describe this diff"

--output-format controls the representation returned by print mode. text is the default, json returns one result object, and stream-json emits a stream of events. --input-format stream-json accepts a corresponding event stream on standard input. --json-schema asks for a result conforming to a supplied JSON Schema.

claude -p --output-format json "list the public modules"
claude -p --json-schema '{"type":"object","properties":{"modules":{"type":"array","items":{"type":"string"}}},"required":["modules"]}' \
  "list the public modules"

-c or --continue reopens the most recent conversation for the current project. -r or --resume accepts a session id or name; without a value it opens a picker.

claude --continue
claude --resume auth-investigation
claude --resume 550e8400-e29b-41d4-a716-446655440000

--fork-session combines with --continue or --resume. It copies the loaded history into a new session id instead of appending to the original session.

claude --continue --fork-session
claude --resume auth-investigation --fork-session

--worktree [name] starts Claude in a Git worktree. --add-dir path grants the session access to an additional directory, and --cwd path chooses the initial working directory. Model and permission state can be selected at launch with flags such as --model, --effort, --permission-mode, --allowedTools, and --disallowedTools.

How slash commands are parsed¶

A slash command is recognized only at the beginning of a submitted message. Text after its name is passed as arguments:

/compact retain the API decisions and failing test output

Typing / opens the command menu. A command submitted while Claude is responding is normally queued until the response finishes. Status-like commands such as /status, /tasks, and /usage can run immediately. Skills are a special case: several can be placed at the beginning of one message, followed by the text passed to them.

/security-check /release-check version 2.4.0

Sessions and conversation copies¶

Claude Code stores session transcripts locally and associates them with a project directory. A session has an id and may also have a name.

/rename [name]¶

/rename release-debugging assigns a name to the current session. With no argument Claude Code generates a name from the conversation. Names can be used with /resume and appear in the session picker.

/resume [session]¶

/resume opens the session picker. /resume <id-or-name> loads a particular conversation. /continue is an alias. Resuming retains the session id and adds new messages to the existing transcript.

/clear [name]¶

/clear starts a new conversation with empty conversational context while remaining in the project. An optional name labels the conversation being left behind. /reset and /new are aliases. The previous conversation remains available through /resume.

/branch [name]¶

/branch copies the conversation through the current message to a new session id, switches the terminal into that copy, and leaves the original unchanged. The optional name labels the new session.

/branch try-streaming-parser

The command copies conversation history, not the working directory. Both sessions see whatever files exist in the checkout in which they run. It also does not execute git branch.

/fork [prompt]¶

/fork copies the current conversation into a background session while the current session remains active. An optional prompt is immediately submitted to the copy; without one, the copy waits for input in agent view.

/fork trace the legacy authentication path and report the entry points

This differs from /branch in which copy the terminal continues to control. /branch switches into the copy. /fork leaves the terminal in the original and starts the copy in the background. Current releases instruct a background copy to create a worktree before editing unless it is configured to edit in place.

/rewind¶

/rewind opens the checkpoint interface. A selected checkpoint can restore the conversation, restore code, restore both, or replace a section of the conversation with a summary. /checkpoint and /undo are aliases. The exact file operations are shown before restoration.

/btw [question]¶

/btw asks a side question about the current session without adding the question and answer to the main conversation history. Running it without a new question shows the most recent side question and allows earlier answers to be browsed.

/background and /exit¶

/background detaches the entire current session so it can continue as a background agent; /bg is an alias. claude agents lists background sessions. /exit terminates an ordinary interactive process, but detaches from an attached background session without stopping that session. /quit is an alias.

The four similarly named mechanisms therefore change different state:

Goals, plans, and background tasks¶

/goal [condition|clear]¶

/goal gives the session a persistent completion condition. Claude Code keeps starting continuation turns until the condition is met. With no argument it shows the current goal, or the most recently achieved one.

/goal all tests in tests/payments pass and the implementation is committed

/goal clear removes the active goal. stop, off, reset, none, and cancel are accepted as clearing synonyms. A goal differs from an ordinary prompt because reaching the end of one response does not by itself end the run.

/plan [description]¶

/plan enters plan mode. An optional argument becomes the task to plan:

/plan replace the file cache with SQLite

In plan mode Claude can inspect the project but does not perform ordinary file edits. Leaving plan mode presents the plan for approval and can include the permissions the plan expects to require.

/tasks, /subtask, and /batch¶

/tasks lists background work associated with the session. /subtask sends a bounded piece of work to a subagent whose result returns to the current conversation. /batch <instruction> is a bundled workflow that decomposes a large change, presents the decomposition, and, after approval, runs units in separate Git worktrees.

Context, model, and display¶

/context displays context-window use as a grid broken down by source. /context all expands the item list. /compact [instructions] replaces older conversation content with a summary; the optional text directs what the summary retains. /autocompact displays or changes the threshold at which automatic compaction occurs.

/model opens a model picker or accepts a model name. /effort sets the reasoning-effort level supported by that model. /fast toggles the fast service mode when it is available. /status prints session, model, account, and configuration information. /usage shows usage data; /cost is its alias.

/diff opens an interactive viewer for the current Git diff and for changes grouped by Claude turn. /copy [N] copies a recent assistant response or an individual code block. /export [filename] writes the conversation as plain text or opens a destination picker.

Project instructions and working directories¶

/init creates a starter CLAUDE.md in the project. /memory opens the interfaces for CLAUDE.md files and Claude Code's automatic memory. A project can contain nested instruction files; Claude Code loads them according to the files it traverses. User instructions live under ~/.claude/, while checked-in project instructions travel with the repository.

/add-dir <path> grants file access to another directory for the current session. /cd <path> moves the session's working directory while keeping its conversation and prompt cache. Adding a directory does not make all of that directory's .claude/ configuration active; it primarily changes file access.

Permission rules¶

/permissions opens the permission editor. /allowed-tools is an alias. Rules are grouped into allow, ask, and deny, and may be stored at user, project, local-project, or managed-policy scope.

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(git reset --hard *)"
    ]
  }
}

A rule begins with a tool name and may contain a parenthesized argument pattern. Bash(git diff *) applies to matching shell subcommands; Read(./.env) applies to a file read. MCP tools use their complete generated tool names. Deny rules are checked before ask rules, and ask rules before allow rules. A matching allow rule skips the interactive prompt; it does not override a matching deny or ask rule.

Settings locations determine scope:

/sandbox toggles operating-system sandboxing on supported platforms. Sandboxing and permission rules are separate: the sandbox limits what a process can reach, while a permission rule determines whether Claude Code asks, allows, or rejects a tool invocation.

Hooks¶

Hooks attach handlers to events in the Claude Code lifecycle. A handler can be a command, HTTP endpoint, MCP tool, prompt evaluated by a model, or agent-based check. /hooks displays the hooks active in the current session.

The configuration has three levels: event, matcher group, and handler.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

matcher selects the tool or event subtype. For tool events it receives names such as Bash, Edit, Write, or mcp__server__tool. A plain value is an exact match, Edit|Write selects either name, and values containing regular expression syntax are treated as JavaScript regular expressions. The optional handler-level if field uses permission-rule syntax to inspect both tool name and arguments.

Blocking a shell command¶

The handler below reads the pending Bash tool call from standard input and returns a denial for two Git commands:

#!/usr/bin/env bash

input=$(cat)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')

case "$command" in
  *"git reset --hard"*|*"git clean -fd"*)
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "Command disabled by project hook"
      }
    }'
    ;;
esac

For rm -rf /tmp/build, the data delivered to a Bash hook contains fields of this form:

{
  "session_id": "abc123",
  "cwd": "/home/me/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build"
  }
}

The event fires before the tool runs. A matching handler prints its structured decision to standard output. permissionDecision: "deny" cancels the tool call and returns permissionDecisionReason to Claude as the tool error. An exit code of 2 with the explanation on standard error is the shorter blocking form:

printf '%s\n' "Command disabled by project hook" >&2
exit 2

Exit code 0 with no output makes no decision and passes the call into the ordinary permission flow. It does not itself approve the call. Other nonzero exit codes report a hook failure but normally allow processing to continue.

PreToolUse can return allow, deny, ask, or defer in permissionDecision. It can also return updatedInput to replace the tool arguments and additionalContext to add text to Claude's context. If several hooks make decisions, the order is deny, then defer, then ask, then allow.

Hook events¶

The full hooks reference defines the input and permitted output for each event. The main event groups are:

The effect of exit code 2 depends on the event. It blocks PreToolUse, denies PermissionRequest, and prevents Stop; for events that occur after an action, it can only affect subsequent processing.

Hooks from user, project, local-project, managed, and plugin settings are merged. Hooks can also be placed in skill or subagent frontmatter and remain active while that component runs. Tool hooks configured for the main session also run for subagent tool calls, whose input includes agent-identifying fields.

Skills and custom commands¶

Custom slash commands are now represented by skills. A skill is a directory containing SKILL.md; it may also contain scripts, templates, and reference files. Project skills live under .claude/skills/, personal skills under ~/.claude/skills/, and plugins can supply more.

---
name: check-release
description: Check whether a release is ready and report missing items.
argument-hint: <version>
disable-model-invocation: true
---

Check release `$ARGUMENTS` against the repository's release files.

The frontmatter controls the name shown in the command menu, description, argument hint, permitted tools, model, context mode, and whether Claude may invoke the skill automatically. $ARGUMENTS expands to all arguments; $ARGUMENTS[0] and $0 address individual arguments. A leading ! command in skill content can run shell context gathering before the resulting prompt is sent to Claude.

/reload-skills re-scans skill and command directories during a running session. /plugin manages installed plugins, and /reload-plugins applies plugin changes without restarting when possible.

The separate Agent Skills chapter covers the file format and sharing one skill directory between agent products.

Subagents¶

Subagents have their own context window, system prompt, tool selection, and optional model. Definitions are Markdown files in .claude/agents/ for a project or ~/.claude/agents/ for a user:

---
name: dependency-tracer
description: Trace dependency edges and report the files involved.
tools: Read, Grep, Glob
model: sonnet
---

Trace the requested dependency. Return file paths and the call chain.

Claude selects subagents from their descriptions or they can be named in a prompt. /subtask explicitly starts a side task whose result returns to the conversation. /tasks shows background work, and /list-agents lists agents and sessions available for cross-session messaging when that feature is enabled. In current releases /agents points to conversational or file-based management of definitions rather than opening the older editor interface.

An isolation: worktree field gives a subagent a Git worktree. Hooks may be declared in the agent frontmatter and apply only while it runs. The subagent reference lists the complete frontmatter schema and built-in agent types.

MCP servers¶

claude mcp manages Model Context Protocol servers from the shell:

claude mcp list
claude mcp get github
claude mcp add --transport stdio local-tools -- ./bin/local-mcp
claude mcp add --transport http docs https://example.com/mcp
claude mcp remove docs

Inside a session, /mcp shows connection and authentication state. /mcp reconnect <server>, /mcp enable <server>, and /mcp disable <server> change it without opening the menu.

Servers can be configured at local, project, or user scope. Their tools appear to Claude with names of the form mcp__<server>__<tool>, which is also the name used by permission rules and hook matchers. MCP servers may additionally expose resources and prompts; server prompts appear as commands in the form /mcp__server__prompt.

A compact command index¶

This is the subset of commands that control the agent itself rather than launching a particular bundled workflow:

Commands implemented as bundled skills or workflows—including /code-review, /security-review, /deep-research, /run, and /verify—use the same command menu but are prompts and orchestration packages rather than primitive session controls. The command reference marks which entries are built-ins, skills, or dynamic workflows.