hidekazu-konishi.com

Claude Code Features and Settings Reference 2026

First Published: 2026-05-16
Last Updated: 2026-11-13

* The contents of this article reflect the state as of the Last Updated date shown above. Claude Code ships fast; rows are revised in place as features GA or are deprecated.

This article is a single-page reference of the user-visible surface of Claude Code: distribution channels, built-in tools, plan mode, subagents, skills, hooks, slash commands, MCP integration, settings keys, and keybindings.

It is designed to be consulted, not read end-to-end. Every section is structured as a flat table so that one fetch resolves many separate questions. The first review of this snapshot was completed on 2026-05; subsequent refreshes within the publication year overwrite this page in place at the same URL.

If you have not used Claude Code before, the companion getting-started article walks through installation and a first session. If you are responsible for configuring Claude Code for a team, the harness and environment engineering article covers the operational design that this reference page only catalogs.

• Companion entry point: Claude Code Getting Started - Why Knowing About Local AI Agents Changes Everything
• Companion design guide: Claude Code Harness and Environment Engineering: Designing the Frontline Where Local AI Agents Actually Live

1. How This Snapshot Was Compiled

This page is an annual snapshot refreshed in place as needed. Its goal is to let an engineer (or an AI agent acting on their behalf) answer "what does Claude Code currently expose?" in a single fetch, with each row linking back to the official documentation for verification.

1.1 Scope of the Snapshot

The reference covers the user-visible surface of the official Anthropic distribution of Claude Code:

• The main channels through which Claude Code is shipped (CLI, IDE extensions, desktop, web, SDK, CI integrations).
• The settings.json keys most users touch at user, project, and local scope (the official settings reference lists every key).
• Every lifecycle event that can be intercepted with hooks.
• The built-in slash commands used day to day (the official commands reference lists all of them).
• The client-side MCP settings that determine how external tool servers are wired in.
• Default keybindings for terminal and IDE surfaces.

It does not cover:

• Step-by-step installation, authentication, or first-session guidance. See Claude Code Getting Started.
• Worked examples of hooks, permission rule design, sandbox patterns, or CLAUDE.md templates. See Claude Code Harness and Environment Engineering.
• Pricing, plan tiers, or per-token economics. Those change too quickly to belong in a year-stable reference.

1.2 Sources and Verification

The primary source for every row is the official Claude Code documentation at https://code.claude.com/docs/en/overview, supplemented by Anthropic engineering posts that announce new features. Every catalog row links to a docs anchor wherever a stable anchor exists.

Items whose presence is observable in the CLI but whose documentation page may shift between minor releases are flagged [Tracking] so you re-check the canonical page on the next review. Features that are present only in a preview or experimental channel are flagged [Preview]. Features announced for removal are flagged [Deprecating].

1.3 Refresh Cadence

This snapshot is refreshed as needed within the publication year. Last reviewed: 2026-11. The URL is intentionally stable across refreshes; new entries are added to the appropriate catalog and removed entries are moved to Recent Deprecations for one cycle before being retired.

1.4 How to Read the Catalogs

Every catalog in this article follows the same shape:

• One row per entity.
• Identical columns across rows so the table can be scanned vertically.
• A short rationale or behavior summary in plain English.
• A link to the canonical documentation page.

Where a feature has multiple aliases, the row uses the name that appears in the CLI prompt or settings file, with the documentation name in parentheses.

2. Distribution Channels

Claude Code is the same engine reached through several surfaces. Each surface exposes a subset of the full feature catalog. This table answers "where can I use Claude Code, and what do I gain or lose by choosing a particular channel?"

* You can sort the table by clicking on the column name.

Channel	Form Factor	Primary Install	Auth	Tools Surface	IDE Integration	Notable Channel-Only Features	Status
CLI	Terminal program (claude)	Native installer (macOS/Linux/Windows) or npm install -g @anthropic-ai/claude-code	Browser OAuth (Claude.ai) or API key	Full	Indirect (works alongside any editor)	The reference surface; everything else mirrors it	GA
VS Code Extension	Editor sidebar and inline chat	VS Code Marketplace ("Claude Code")	Inherits CLI auth	Full, plus IDE-aware diff preview	Native (VS Code, Cursor, Devin Desktop (formerly Windsurf), etc.)	Live diff overlay, native selection context	GA
JetBrains Plugin	IDE tool window	JetBrains Marketplace ("Claude Code [Beta]")	Inherits CLI auth	Full	Native (IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, GoLand, etc.)	IDE selection context bridging, refactor preview	Beta
Desktop App	Standalone GUI (macOS and Windows; Linux in beta)	Claude Desktop installer	Anthropic account	Full, plus session manager and project switcher	None	Multi-project session list, GUI-managed environments	GA
Web (claude.ai/code)	Browser surface on claude.ai	None (open https://claude.ai/code)	Anthropic account	Reduced (no local file system; cloud sandbox only)	None	Shareable conversation links, zero install	GA
Claude Agent SDK	TypeScript and Python libraries	npm install @anthropic-ai/claude-agent-sdk / pip install claude-agent-sdk	API key	Programmable; you compose tools yourself	None	Embed Claude Code as a building block in your own product	GA
GitHub Action	CI step	Marketplace action anthropics/claude-code-action	API key in repo secrets	Full, scoped to checked-out workspace	None	Pull-request reviews, automated diffs in CI	GA
GitHub App	App installed on the repository	Install via /install-github-app from the CLI	OAuth plus GitHub	Same as Action, scoped per repository	None	Used by the GitHub Action and Code Review	GA

For a feature-by-channel matrix that distinguishes "supported", "partial", and "absent" at the individual tool level, see Section 3 below. The summary version: the CLI is the reference channel, the IDE extensions and Desktop app surface the full toolset, the Web surface is intentionally read-only against your local machine, and the SDK is for embedding rather than direct use.

3. Core Features

The core features below are the units that show up as either a built-in tool, an internal mode, or an explicit user-visible mechanism. Each row is independent and self-contained.

3.1 Built-in Tools

These are the built-in tools a Claude Code session uses most (subject to per-tool permission rules); the official tools reference lists the full set. They are the building blocks that every higher-level feature composes against. On macOS, Linux, and WSL, Glob and Grep are absent from the default tool set, and Claude searches with find and grep through the Bash tool instead.

The Permission column shows whether a tool prompts in Manual mode. In Auto mode, a background classifier decides most of these calls; in Accept Edits mode, file edits inside the working directories run without prompting.

* You can sort the table by clicking on the column name.

Tool	Purpose	Side Effect	Permission (Manual Mode)	Common Uses
Read	Read a file from the local filesystem	None	Read-only by default; no permission needed	Source code review, log inspection, configuration auditing
Edit	Exact string replacement in an existing file	Modifies file	Prompts for approval unless allowed	Targeted bug fixes, rename, refactor lines
Write	Create or overwrite a file	Modifies file	Prompts for approval unless allowed	New files, full rewrites
Bash	Run a shell command	Anything the shell can do	Prompts per command pattern	Test runs, builds, git, package managers
Glob	Match file paths by pattern	None	Read-only	Locate files by pattern
Grep	Search file contents with ripgrep	None	Read-only	Find symbol or string across repo
NotebookEdit	Modify cells in a Jupyter notebook	Modifies file	Prompts for approval	Notebook authoring
WebFetch	Fetch a URL and process it	Network request	Per-domain permission	Read public docs, fetch a known URL
WebSearch	Issue a web search	Network request	Permission-controlled	Look up unknown topics
Agent (formerly Task)	Launch a subagent	Spawns a child session	Inherits subagent permissions	Parallel research, scoped editing
TaskCreate / TaskGet / TaskList / TaskUpdate	Create and track the session task list (TodoWrite is disabled by default in favor of these)	Updates internal state	None	Track multi-step work
TaskStop	Stop a running background task by ID	Stops a process	None	Cancel a stuck process
EnterPlanMode	Enter plan mode mid-session to think before acting	Switches mode	None	Plan mode workflow
ExitPlanMode	Leave plan mode after presenting a plan	Switches mode	Prompts for approval	Plan mode workflow
Skill	Invoke a registered skill	Depends on the skill	Prompts for approval	Domain-specific helpers

Tools surfaced by MCP servers extend this list dynamically and are addressed in Section 7.

3.2 Plan Mode

Plan mode is the mode that Claude Code uses to think through a multi-step change before any file is touched. It is entered by cycling Shift+Tab to it (two presses from Manual, through Accept Edits; a session that starts in Auto needs a third, since the first press goes to Manual), by launching the CLI with --permission-mode plan, by typing /plan [description], or by pinning it as the session default with permissions.defaultMode: "plan" in settings.json.

Aspect	Behavior
Tools allowed	Reading and searching files, read-only shell commands, web tools, and research subagents such as Plan; Claude then writes the plan
Tools blocked	Edit, Write, NotebookEdit until you approve the plan. Bash commands go to the auto mode classifier when auto mode is available; otherwise, commands outside the built-in read-only set prompt. In interactive terminal sessions where bypass permissions are available, these blocks aren't enforced
Exit	ExitPlanMode tool presents the plan; user approves or rejects
Persistence	The plan is written to a plan file (default ~/.claude/plans, configurable with plansDirectory) and kept in conversation context
Use case	Large refactors, ambiguous tasks, anything reversible only with effort

The full operational rationale is in the companion harness and environment article. The point of including plan mode here is that it is an officially supported mode rather than a workflow convention.

3.3 Subagents (Agent Tool)

Subagents are independent Claude sessions launched from the parent via the Agent tool (named Task before v2.1.63; Task(...) references still work as an alias). They have their own context window, their own tool list, and an optional isolation strategy. They are useful for parallelizing independent work, protecting the parent context from large search results, and giving narrowly scoped tasks a fresh start.

Aspect	Behavior
Definition	.claude/agents/<name>.md with YAML frontmatter (name, description, tools, model)
Built-in subagents	Explore, Plan, general-purpose, plus helpers such as claude, statusline-setup, and claude-code-guide
Invocation	Parent calls the Agent tool with subagent_type: "<name>"
Context isolation	Yes by default (a subagent does not see the parent transcript); a fork inherits the whole conversation
Filesystem isolation	Optional via isolation: "worktree" to spawn the subagent in a git worktree
Output	Subagent returns a single final message; intermediate steps are not visible to the parent
Permissions	Subagents respect the same settings.json permission tree as the parent

Note: Foreground subagents show the same permission prompts you would see in the main conversation, and background subagents surface their prompts in the main session. Restricting subagents to read-only tool sets (omit Edit, Write, and NotebookEdit from the frontmatter tools: list) and leaving Edit / Write / NotebookEdit / Bash work to the parent agent still keeps approvals in one place. Built-in subagents whose job is to edit files (for example, statusline-setup) are the exception because their edit scope is narrow and predictable.

3.4 Skills

Skills are reusable, named bundles of instructions, scripts, and optional sub-tools that the harness can load on demand. A skill is defined by a SKILL.md file (with frontmatter) plus any supporting files, all stored under .claude/skills/<name>/.

Aspect	Behavior
Definition	.claude/skills/<name>/SKILL.md plus supporting files in the same directory
Frontmatter	name, description, optional model, optional tool list
Activation	The harness lists available skills; Claude invokes one via the Skill tool when its description matches the user request, or you invoke it directly as /<name>
Scoping	User-level, project-level, or plugin-bundled
Relation to custom slash commands	Custom commands have been merged into skills: a file at .claude/commands/<name>.md and a skill at .claude/skills/<name>/SKILL.md both create /<name>; the skill directory adds supporting files and scripts
Distinction from a subagent	A skill runs in the same session and context as the parent; a subagent does not

A single-file custom command is enough when the workflow is essentially "insert this prompt template." Use a skill directory when there is real domain logic, structured input parameters, or shipped helper files. Use a subagent when context isolation is the point.

3.5 Output Styles

Output styles configure how Claude formats its responses (verbosity, code-comment density, prose register). They are selected with /output-style [style], through the /config settings interface, or by setting outputStyle directly in settings.json, and ship with a small set of built-in choices alongside any user-defined styles.

Aspect	Behavior
Built-in styles	Default (Claude Code's standard instructions, with no style added), Proactive (starts work right away and makes reasonable assumptions), Concise (leads with the result, without preamble or recaps), Explanatory (adds short Insight blocks about the choices behind the code), Learning (explains choices and leaves small pieces of code for you to write). Additional named styles may appear in newer releases — /output-style or /config shows the canonical list for your installed version
Custom styles	Defined under .claude/output-styles/<name>.md
Settings key	outputStyle: "<name>"
How to switch	/output-style [style], /config (interactive), or edit the outputStyle setting
Scope	Per session, applied to every assistant turn

3.6 Memory (auto-memory)

Memory is the file-based personal note system that Claude Code maintains across sessions when enabled. It is intentionally a flat directory of small Markdown files indexed by a top-level MEMORY.md. The user can ask Claude to remember or forget specific items.

Aspect	Behavior
Location	~/.claude/projects/<workspace-slug>/memory/
Index	MEMORY.md (one line per entry, loaded into context)
Memory types	user, feedback, project, reference
Add	Ask Claude in plain language to remember something, or open /memory to view the entries
Remove	Ask Claude to forget the relevant entry
Scope	Per workspace

Memory is for context that should persist across conversations. Anything specific to the current conversation belongs in the todo list, not memory.

3.7 Compaction

When the conversation approaches the model's context window, the harness compacts older turns into a summary so that work can continue. Compaction can be automatic (driven by the harness) or manual (via /compact).

Aspect	Behavior
Trigger	Automatic when context window pressure is high, or when a long conversation sits idle until its prompt cache is about to expire (turn this off with idleCompaction: false); manual via /compact
Effect	Older turns are summarized; project CLAUDE.md, auto memory, the plan, and recently read or edited files are re-injected after the summary
Recovery point	The summary becomes part of the new conversation prefix
User control	/compact accepts an optional instruction (for example, "focus on what changed in the auth module")
Hooks	PreCompact fires before compaction (pre-summary side effects); PostCompact fires after with an auto / manual matcher to filter by trigger

3.8 Accept Edits and Permission Modes

Claude Code runs in one of six permission modes that change how often it prompts the user before tool execution. Each row gives a descriptive name and, in parentheses, the configuration value; Manual is the UI label of default (since v2.1.200).

Mode	Behavior	How to Enter
Manual (default)	Standard ask / allow / deny evaluation per call; anything not pre-approved prompts	--permission-mode default (or manual), permissions.defaultMode: "default", or Shift+Tab (the first press from Auto); the built-in start for claude -p and the Agent SDK
Accept Edits (acceptEdits)	File edits and common filesystem commands (mkdir, mv, rm, and similar) inside the working directories proceed without prompting, except rm and rmdir removals that target a critical path such as the working directory itself; other tools still respect rules	Shift+Tab (one press from Manual) or --permission-mode acceptEdits
Plan Mode (plan)	Reads and explores, and edits stay blocked until you approve the plan; shell commands go to the auto mode classifier when auto mode is available and otherwise prompt unless read-only	Shift+Tab (two presses from Manual), --permission-mode plan, or permissions.defaultMode: "plan"
Auto (auto)	Runs without routine prompts; a background classifier checks actions such as shell commands and network requests before they run	The built-in start for interactive terminal and VS Code sessions (see below); also Shift+Tab when auto mode is available, --permission-mode auto, or permissions.defaultMode: "auto" in user or managed settings
Don't Ask (dontAsk)	Pre-approved tools and reads inside the working directories run; calls that would otherwise prompt are denied, with narrow exceptions in the official documentation	--permission-mode dontAsk or permissions.defaultMode: "dontAsk"; never in the Shift+Tab cycle
Bypass Permissions (bypassPermissions)	Prompts and safety checks are skipped, but deny rules, explicit ask rules, and a few other checks still apply (isolated containers and VMs only)	--dangerously-skip-permissions, --permission-mode bypassPermissions, or permissions.defaultMode: "bypassPermissions" in user, --settings, or managed settings

Modes are session state, not persisted in settings.json (the defaultMode key sets the initial mode; the user changes it dynamically with Shift+Tab).

In the documentation checked on 2026-11-12, when nothing sets a mode, the built-in default applies: auto for interactive terminal and VS Code sessions on Claude Code v2.1.283 or later, and default (Manual) for claude -p and the Agent SDK (v2.1.302 or later; before that, such runs could start in auto when they didn't fetch feature flags, for example on third-party providers or with telemetry off). A session that would start in auto starts in Manual instead when auto mode isn't available to it, for example when disableAutoMode is set or the model doesn't support it; sessions in organizations with the HIPAA configuration applied also start in Manual (v2.1.285 or later), with auto mode still available to switch to. The version depends on the source: the permission modes documentation gives v2.1.283, while the CHANGELOG records the change in two entries — 2.1.283 (third-party providers and telemetry off; published to npm on 2026-09-25) and 2.1.284 (every plan and provider; published to npm on 2026-09-28). Before that, auto mode had been the default for new sessions on Pro, Max, Ultra, and Team plans since 2026-08-14 (What's New, week 32). permissions.defaultMode overrides the built-in default, within the project and local limits noted in Section 4.3.

3.9 Status Line

The status line is a customizable bar at the bottom of the CLI that shows whatever your script prints, such as the model in use, the cwd, and context usage. It is configured by statusLine in settings.json and can be customized to run an external script that emits the line.

Aspect	Behavior
Default	None until you configure statusLine (or run /statusline)
Custom	statusLine: { type: "command", command: "<path-to-script>" }
Script contract	Reads context JSON on stdin and writes the status text to stdout; each printed line becomes a row
Setup helper	The statusline-setup built-in subagent edits settings.json for you

3.10 Background Tasks

Long-running shell commands can be backgrounded with the run_in_background flag on the Bash tool. Claude receives notifications when each task completes and can read the task's output file without blocking the conversation.

Aspect	Behavior
Trigger	Bash tool call with run_in_background: true
Tracking	The harness assigns a task ID and surfaces completion notifications; /tasks lists background work
Read output	Claude reads the task's output file with the Read tool
Cancel	TaskStop tool, or /tasks
Use case	Dev servers, watchers, long test suites

3.11 Plugins

A plugin is a versioned bundle that can ship one or more skills, subagents, slash commands, hooks, output styles, and MCP server definitions together as a single installable unit. Plugins are the canonical way to share reusable Claude Code extensions across teams and the public marketplace.

Aspect	Behavior
What a plugin can bundle	Skills, subagents, slash commands, hooks, output styles, MCP server definitions
Install scope	User, project, or local scope, recorded under enabledPlugins in the matching settings file (a project shares plugins by listing them in .claude/settings.json); fetched plugin files are cached under ~/.claude/plugins/, and a project's .claude/plugins/ directory is not scanned
Discovery	The /plugin slash command browses installed plugins and configured marketplaces
Naming inside Claude Code	Plugin-namespaced items appear with a plugin:name qualifier (for example, a skill becomes plugin:skill when invoked)
Updates	Managed through /plugin; a plugin's version comes from its manifest, and a marketplace entry can pin a git ref or sha
Trust boundary	Plugin code runs inside the harness; treat third-party plugins like any other dependency in your supply chain

Plugins compose well with the rest of the catalog: a team plugin can pin a security-review skill, a PreToolUse hook that scans for secrets, a custom statusLine renderer, and an MCP server definition for the internal API — all installed with one /plugin command.

3.12 Headless / Non-Interactive Mode

Claude Code can run as a one-shot CLI process without a TTY, which is what makes the GitHub Action, scheduled jobs, and pre-commit integrations possible. Headless mode reuses the same settings, hooks, and permission rules as the interactive CLI.

Aspect	Behavior
Invocation	claude -p "<prompt>" (alias: --print) runs the prompt non-interactively and writes the final response to stdout
Prompt source	Argument string or stdin (echo "..." | claude -p)
Auth	Use apiKeyHelper in settings.json or set ANTHROPIC_API_KEY in the environment so no browser OAuth is required
Output format	--output-format text (default) or --output-format json / stream-json for machine-readable transcripts
Session continuity	--resume <id> or --continue to keep building on a prior conversation across invocations
Permission posture	Combine --permission-mode with explicit allow/deny rules in a project settings.json; avoid --dangerously-skip-permissions outside fully sandboxed CI runners
Use case	CI review jobs, code-fix bots, scripted refactors, scheduled audits

4. Configuration Reference

This section catalogs the settings keys most users touch, organized by file; the official settings reference lists every key. The companion harness and environment article covers the reasoning behind each value; here only the schema lives.

4.1 The settings.json Precedence Tree

settings.json is read from multiple locations and merged. The table is ordered from lowest precedence (read first, easily overridden) to highest precedence (read last, always wins). For scalar keys, higher-precedence layers override lower ones; for arrays, layers generally concatenate. The enterprise managed layer is the absolute policy floor — it overrides every lower layer and CLI flags cannot relax it.

Order	Path	Scope	Typical Use
1 (lowest)	~/.claude/settings.json	User (all projects)	Personal defaults
2	<project>/.claude/settings.json	Project (checked into VCS)	Team defaults
3	<project>/.claude/settings.local.json	Project (gitignored)	Personal overrides per project
4	CLI flags	Single invocation	Ad-hoc overrides
5 (highest)	Managed (enterprise)	Org-wide	Policy floor that cannot be relaxed by lower layers or CLI flags

The enterprise managed file path differs by OS: /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows. A drop-in directory (managed-settings.d/*.json) is supported on each platform; files are merged alphabetically, with later files overriding earlier ones and arrays concatenated. On macOS, the MDM plist domain com.anthropic.claudecode and on Windows the registry key HKLM\SOFTWARE\Policies\ClaudeCode provide equivalent admin-controlled configuration.

4.2 Top-Level Keys

* You can sort the table by clicking on the column name.

Key	Type	Purpose
model	string	Default model, as an alias or a full model ID (for example, "opus", "sonnet", "fable", or "claude-opus-5-5")
permissions	object	allow, deny, ask, additionalDirectories, blockReadsOutsideWorkingDirectories, blockWritesOutsideWorkingDirectories, denyInsteadOfPrompting, defaultMode, disableBypassPermissionsMode, disableAutoMode
hooks	object	Per-event hook configuration (see Section 5)
env	object	Environment variables exposed to tools
apiKeyHelper	string	Shell command that prints the credential sent with model requests (for rotating or short-lived tokens)
attribution	object or false	Customize or hide the attribution added to git commits and pull requests (commit, pr, sessionUrl); replaces includeCoAuthoredBy, deprecated since v2.0.62
statusLine	object	Status line renderer (see Section 3.9)
outputStyle	string	Active output style name
theme	string	Color theme for the CLI (for example, "auto", "dark", "light", "dark-daltonized", "light-daltonized", "dark-ansi", "light-ansi", or a "custom:<slug>" theme)
cleanupPeriodDays	number	How long locally stored chat transcripts are retained before cleanup; baseline 30 days
autoUpdatesChannel	string	Release channel that background auto-updates and claude update follow: "latest" (default) or "stable"; the DISABLE_AUTOUPDATER environment variable turns background updates off
forceLoginMethod	string	Restrict sign-in to "claudeai", "console", or "gateway" (a cloud gateway); useful in shared environments
enableAllProjectMcpServers	boolean	Auto-approve project-defined MCP servers
enabledMcpjsonServers	string[]	Explicit allow-list of project MCP server names
disabledMcpjsonServers	string[]	Explicit deny-list of project MCP server names

MCP servers themselves are not defined in settings.json; they live in .mcp.json or ~/.claude.json (see Section 7.1), and the three MCP keys above only approve them.

Observability is configured through environment variables rather than top-level settings keys; see Section 4.4 for the relevant CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_*, and audit-related variables. There is no enableAuditLog key in settings.json: persistent auditing is achieved either via OpenTelemetry exporters or via a PostToolUse hook that writes structured records to your own pipeline.

4.3 The permissions Block

The permissions block governs the harness's per-tool-call evaluation.

Subkey	Type	Behavior
allow	string[]	Patterns that auto-approve a tool call
deny	string[]	Patterns that hard-deny a tool call (no prompt)
ask	string[]	Patterns that always prompt, even if matched by allow
defaultMode	string	Initial mode at session start; unset means the built-in default for the surface (Section 3.8). Supported values: "default" (alias "manual"), "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions". "auto" and "bypassPermissions" don't take effect from project or local settings (for "bypassPermissions", since v2.1.257)
additionalDirectories	string[]	Extra directories Claude may read/write outside the project root
blockReadsOutsideWorkingDirectories	boolean	Make the file tools refuse reads outside the working directories in every permission mode
blockWritesOutsideWorkingDirectories	boolean	Make Write, Edit, and NotebookEdit refuse paths outside the working directories in every permission mode (v2.1.314 or later)
denyInsteadOfPrompting	boolean	Deny tool calls that would wait on a permission prompt, so a session nobody is watching keeps going (v2.1.319 or later)
disableBypassPermissionsMode	string	Set to "disable" to prevent anyone from entering bypassPermissions mode; takes precedence over --dangerously-skip-permissions (typically set in managed settings)
disableAutoMode	string	Set to "disable" to remove auto mode from the Shift+Tab cycle; sessions that would start in auto start in default (also accepted as a top-level key)

Patterns use tool-specific syntax. For Bash, a * matches any text, including spaces, so "Bash(npm test *)" covers a family of commands; a rule with no * matches one exact command. For Read, Edit, Write, a pattern is a glob path (for example, "Read(~/Documents/**)"). Evaluation order is deny → ask → allow; the first match in that order wins.

The companion harness and environment article walks through worked examples of how each pattern composes with the others; the table above is the schema only.

4.4 The env Block

Environment variables defined here are exported to every tool the harness launches.

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "180000",
    "BASH_MAX_TIMEOUT_MS": "600000",
    "HTTP_PROXY": "http://proxy.example.com:3128",
    "MCP_TIMEOUT": "30000"
  }
}

Recognized harness-level variables include ANTHROPIC_MODEL, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_DISABLE_THINKING, CLAUDE_CODE_DISABLE_AUTO_MEMORY, CLAUDE_CODE_SKIP_PROMPT_HISTORY, CLAUDE_CODE_EFFORT_LEVEL, CLAUDE_CODE_MAX_OUTPUT_TOKENS, BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_TIMEOUT_MS, DISABLE_AUTOUPDATER, MCP_TIMEOUT, MAX_MCP_OUTPUT_TOKENS, plus the standard OpenTelemetry exporters (OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOG_TOOL_DETAILS for extended tool span attributes such as file_path and full_command).

BASH_DEFAULT_TIMEOUT_MS overrides the per-command default timeout for the Bash tool (two minutes baseline); BASH_MAX_TIMEOUT_MS caps the value Claude may request (ten minutes baseline). Setting both to the same value makes it both the default and the ceiling for foreground commands; a command that reaches the limit is moved to the background rather than stopped.

4.5 The ~/.claude/ Directory Layout

~/.claude/ is the per-user home for everything stateful that Claude Code maintains.

~/.claude/
  settings.json              # User-level settings
  CLAUDE.md                  # User-level instructions loaded into every session
  keybindings.json           # User-level keybinding overrides
  agents/                    # User-level subagent definitions
  commands/                  # User-level custom commands (single-file form of skills)
  skills/                    # User-level skills
  output-styles/             # User-level output styles
  hooks/                     # A conventional place for hook scripts referenced from settings.json
  plans/                     # Plan files written in plan mode
  plugins/                   # Cached plugin files
  projects/<workspace>/      # Per-project state
    <session>.jsonl         # Session transcripts
    memory/                  # Auto-memory files
  sessions/                  # One small file per running session
  debug/                     # Per-session debug logs (when debug logging is on)

The project-scoped equivalents (<project>/.claude/...) cover the configuration entries such as settings, agents, commands, skills, and output styles; the state directories (plans/, plugins/, projects/, sessions/, debug/) exist only under ~/.claude/.

4.6 CLAUDE.md Tiers

CLAUDE.md is the file Claude reads on session start; its content is delivered as a user message after the system prompt, not as part of the system prompt itself. It exists at several levels, and every level that applies is loaded rather than one replacing another.

Tier	Path	Scope	When to use
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	All users on the machine	Organization-wide instructions
User	~/.claude/CLAUDE.md	All sessions, all projects	Personal preferences that apply everywhere
Project	<project>/CLAUDE.md or <project>/.claude/CLAUDE.md	All sessions in this project	Codebase-specific conventions, build commands, layout
Local	<project>/CLAUDE.local.md (add it to .gitignore)	Only you, in this project	Personal project-specific preferences
Subdirectory	<project>/path/CLAUDE.md	Loaded on demand when Claude reads or edits files in that subdirectory	Subsystem-specific rules

CLAUDE.md instructs Claude's behavior at conversation start. It does not enforce anything; for enforcement, use permissions and hooks.

4.7 keybindings.json

The user-level keybinding override file lives at ~/.claude/keybindings.json. It is a JSON object with a bindings array; each block names a context (for example, Chat) and maps keystrokes to actions, and setting an action to null unbinds a default. Run /keybindings to create or open it. The default keybindings are documented in Section 8; only deltas need to appear in this file.

5. Hooks Catalog

Hooks are user-defined handlers (shell commands, HTTP endpoints, MCP tools, or prompt and agent evaluations) that the harness runs at fixed points in the session lifecycle. They are the primary enforcement mechanism: a hook can block a tool call, add context to a prompt, log an event, or trigger external automation.

5.1 Hook Events

Every hook receives a JSON object on stdin with common fields such as session_id, transcript_path, cwd, and hook_event_name, plus fields specific to the event (for example, tool_name and tool_input for tool events). The Can Block column shows whether exit code 2 stops the action.

* You can sort the table by clicking on the column name.

Event	Fires	Can Block	Effect of Exit Code 2
SessionStart	When a session begins or resumes (matcher: startup, resume, clear, compact, or fork)	No	Stderr is shown to the user only
Setup	When Claude Code starts with --init-only, or with --init or --maintenance in -p mode	No	Exit code and stderr are ignored
UserPromptSubmit	When a prompt is submitted, before Claude processes it	Yes	Blocks the prompt; the hook can add context but cannot replace the prompt
UserPromptExpansion	When a typed command expands into a prompt, before it reaches Claude	Yes	Blocks the expansion
PreToolUse	Before a tool call executes	Yes	Blocks the tool call
PermissionRequest	When a tool call needs a permission decision	No	Ignored; deny through the hook's JSON decision instead
PermissionDenied	When auto mode denies a tool call	No	Ignored; the denial already happened
PostToolUse	After a tool call succeeds	No	Stderr is shown to Claude; the tool already ran
PostToolUseFailure	After a tool call fails	No	Stderr is shown to Claude; the tool already failed
PostToolBatch	After a full batch of parallel tool calls resolves, before the next model call	Yes	Stops the agentic loop before the next model call
Notification	When Claude Code sends a notification	No	Exit code and stderr are ignored
MessageDisplay	While assistant message text is displayed	No	The original text is displayed
SubagentStart	When a subagent is spawned	No	Stderr is shown to the user only
SubagentStop	When a subagent finishes	Yes	Prevents the subagent from stopping
TaskCreated	When a task is being created via TaskCreate	Yes	Rolls back the task creation
TaskCompleted	When a task is being marked as completed	Yes	Prevents the task from being marked as completed
Stop	When Claude finishes responding	Yes	Prevents Claude from stopping; the conversation continues
StopFailure	When the turn ends due to an API error	No	Output and exit code are ignored
TeammateIdle	When an agent team teammate is about to go idle	Yes	The teammate keeps working
InstructionsLoaded	When a CLAUDE.md or .claude/rules/*.md file is loaded into context	No	Exit code is ignored
ConfigChange	When a configuration file changes during a session	Yes	Blocks the change from taking effect (except managed policy settings)
CwdChanged	When the working directory changes	No	Stderr is shown to the user only
DirectoryAdded	When a working directory is added mid-session, for example with /add-dir	No	Stderr goes to the debug log; the directory is already added
FileChanged	When a watched file changes on disk (the matcher names the files to watch)	No	Stderr is shown to the user only
WorktreeCreate	When a worktree is being created; replaces the default git behavior	Yes	Any non-zero exit code makes worktree creation fail
WorktreeRemove	When a worktree that a WorktreeCreate hook created is being removed	Yes	Any non-zero exit code makes removal fail if the directory still exists
PreCompact	Before context compaction	Yes	Blocks compaction
PostCompact	After context compaction completes (matcher: auto or manual)	No	Stderr is shown to the user only
PreModelSwitch	Before Claude Code applies a model switch that you or a client requested	Yes	Blocks the model switch
PostModelSwitch	After the session's model changes	No	Stderr is shown to the user only; the model already switched
Elicitation	When an MCP server requests user input during a tool call	Yes	Declines the request, and no dialog appears
ElicitationResult	After a user responds to an MCP elicitation, before the response is sent back to the server	Yes	Blocks the response (it becomes a decline)
SessionEnd	When a session terminates	No	Stderr is shown to the user only

The table lists the 33 events in the hooks reference checked on 2026-11-12. New events are occasionally added between releases; check the upstream Hooks reference for the current canonical list before wiring up a new automation.

5.2 Hook Configuration Shape

Each hook event takes a list of matchers; each matcher carries one or more commands to run. The matcher syntax is event-specific (for example, PreToolUse matchers select by tool name plus an optional input pattern).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/guard-bash.sh" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/scan-secrets.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/format-on-write.sh" }]
      }
    ]
  }
}

5.3 Hook Exit Code Semantics

Exit code	Meaning
0	Success; the action continues normally
1	Non-blocking error: the action proceeds, and a hook error notice appears in the transcript
2	Blocking error on events that can block (see Section 5.1); on other events the action is unchanged
other	Same as 1. A command or HTTP hook set to onFailure: "block" blocks the action instead (v2.1.295 or later)

Worked examples (a PreToolUse hook that vetoes rm -rf, a PostToolUse hook that runs prettier, a UserPromptSubmit hook that prepends global rules) are in Claude Code Harness and Environment Engineering. This page only catalogs which events exist.

6. Built-in Slash Commands

Slash commands are typed shortcuts that either reach into harness state (/permissions, /model) or run a skill (custom commands under .claude/commands/ are now a form of skill). The tables below list the built-in commands used day to day; the official commands reference lists all of them (more than a hundred).

6.1 Session and Conversation Control

* You can sort the table by clicking on the column name.

Command	Effect
/clear	Reset the conversation; keep cwd and settings
/compact [instruction]	Manually compact the conversation, optionally biasing what is preserved
/resume [session]	Resume a conversation by ID or name, or open the session picker (alias: /continue)
/usage	Show session cost, plan usage limits, and activity stats
/cost	Alias for /usage
/status	Open the Status tab of the settings interface (version, model, account, connectivity)
/context [all]	Visualize current context usage as a colored grid, with optimization suggestions
/rewind	Rewind the conversation and/or code to a previous point (aliases: /checkpoint, /undo)
/branch [name]	Branch the conversation at this point and switch into the branch; the original stays available through /resume
/fork [prompt]	Copy the conversation into a new background session and keep working here
/btw [question]	Ask a side question about the session without adding it to the conversation
/goal [condition|clear]	Keep Claude working across turns until a condition is met
/plan [description]	Enter plan mode, optionally starting on a task
/cd <path>	Move the session to a new working directory, keeping the conversation
/help	List available slash commands

6.2 Configuration

Command	Effect
/config	Open the settings interface; covers model, output style, theme, and other top-level settings
/model [model]	Switch the model and save it as the default for new sessions (in the picker, press s to switch for this session only)
/effort [level]	Set the effort level (low to xhigh, max, or auto)
/output-style [style]	List output styles or switch to one (v2.1.269 or later)
/permissions	Manage allow, ask, and deny rules by scope, manage working directories, and review recent auto mode denials
/hooks	Inspect current hook configuration
/add-dir <path>	Add a directory to additionalDirectories for this session
/memory	Edit CLAUDE.md files, turn auto memory on or off, and view auto memory entries

6.3 Tools and Extensions

Command	Effect
/mcp	List MCP servers and their connection state
/agents	Print a reminder to ask Claude to create or manage subagents, or to edit .claude/agents/ directly
/tasks	View and manage background work in the session (alias: /bashes)
/skills	List installed skills (built-in and user-defined) and their availability in the current session
/plugin	Browse, install, enable, or disable plugins (see Section 3.11)
/ide	Connect the running CLI session to a detected IDE (VS Code, JetBrains) so selections and diffs flow through
/init	Initialize a project CLAUDE.md
/install-github-app	Install the Claude Code GitHub App for the current repo
/login	Re-authenticate
/logout	Sign out

6.4 Diagnostics

Command	Effect
/doctor	Run a setup checkup that diagnoses installation, settings, extension, and CLAUDE.md problems; Claude applies the proposed fixes after you confirm (alias: /checkup)
/bug	Report a bug or share your conversation after a consent screen (alias: /share; /feedback is a separate command)
/release-notes	View the changelog in an interactive version picker
/terminal-setup	Install a Shift+Enter keybinding for newlines in supported terminals
/upgrade	Open the upgrade page to switch to a higher plan tier

6.5 Editor and Productivity

Command	Effect
/fast [on|off]	Toggle fast mode (faster but more expensive output) on models that support it: Fable 5.2, Opus 5.5, and Opus 5 (research preview for Opus 5). Fast mode for Opus 4.8 was deprecated on 2026-10-30, with removal on 2026-11-30.
/code-review [target]	Review the current diff, or a PR, branch, or path, for correctness bugs
/review	Alias of /code-review
/diff	Review the changes in the working tree, including the edits Claude has made
/loop [interval] [prompt]	Run a prompt repeatedly while the session stays open
/schedule [description]	Create, update, list, or run cloud scheduled tasks, formerly routines (alias: /routines)
/export [filename]	Export the conversation as plain text, to a file or the clipboard

6.6 Custom Slash Commands

Custom commands have been merged into skills: a file at .claude/commands/<name>.md and a skill at .claude/skills/<name>/SKILL.md both create /<name>. The single-file form lives under .claude/commands/<name>.md (user-level under ~/.claude/commands/). The Markdown body is the prompt template; an optional YAML frontmatter block sets the description, allowed tools, and default model.

---
description: Run a security review of the staging branch
allowed-tools: Read, Grep, Glob, Bash, WebFetch
model: opus
---
Audit the diff between `main` and `HEAD` for security issues. Focus on:
- Authentication / authorization changes
- Input handling boundaries
- Secrets in logs
- New dependencies
Report findings as a punch list.

Commands so defined are invoked as /<name>.

7. MCP Integration (Client Side)

Claude Code is an MCP client. It connects to MCP servers (separately authored tool servers) and exposes their tools, resources, and prompts to the model as if they were native. The catalog below describes the client-side knobs; it does not catalog individual MCP servers themselves (that survey is a separate snapshot).

7.1 Where MCP Servers Are Defined

Source	Path	Scope	Notes
Local scope (default)	~/.claude.json, under the project's path	One project, private to you	Added with claude mcp add
User scope	~/.claude.json	All your projects, private to you	Added with claude mcp add --scope user
Project scope	<project>/.mcp.json	Project, shared via version control	Project-distributed MCP servers; controlled by enabledMcpjsonServers / disabledMcpjsonServers
CLI flag	--mcp-config <file>	One session	Ad-hoc
Managed	managed-mcp.json, or the managedMcpServers managed setting	Organization	Administrators deploy a fixed server set or provide servers alongside users' own

7.2 Transport Types

* You can sort the table by clicking on the column name.

Transport	When to Use	How Defined
stdio	Local binary or script; default for most servers	command plus optional args and env
http (alias: streamable-http)	Remote MCP server over HTTP with streamable responses; preferred transport for remote servers	url, optional headers
sse	Remote server using Server-Sent Events; deprecated — existing configs continue to work but new servers should use http	url, optional headers
ws (WebSocket)	Remote server that pushes events to Claude over a persistent connection; authentication is header-only	url, optional headers; configured in .mcp.json or with claude mcp add-json

Use http (a.k.a. streamable-http) for ordinary remote servers, ws only when the server needs to push events, and stdio for local processes.

7.3 MCP Server Definition Shape

The example below is the content of a project .mcp.json file.

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "company-api": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/v1",
      "headers": {
        "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
      }
    }
  }
}

Environment variables in ${VAR} or ${VAR:-default} form are expanded from the environment when the configuration is loaded.

7.4 Permissions for MCP Tools

MCP-provided tools are named mcp__<server>__<tool> in the permission system. To allow a single tool, use "allow": ["mcp__filesystem__read_file"]. To allow every tool from one server, use "allow": ["mcp__filesystem"]. The same wildcards work in deny and ask.

The enableAllProjectMcpServers, enabledMcpjsonServers, and disabledMcpjsonServers keys gate which project-defined MCP servers are even attempted. They are a separate layer above the per-tool permission rules.

7.5 MCP Connection State

The /mcp slash command lists every configured server with its connection state and the tools, resources, and prompts each one exposes. Claude Code retries an HTTP or SSE server's first connection after a transient error, and reconnects a remote server that drops mid-session up to five times with exponential backoff; for a server that stays down, reconnect it from /mcp.

8. Keybindings

The keybindings below are the default chords across the CLI and IDE channels. Override them by editing ~/.claude/keybindings.json for the CLI or via the standard IDE keybinding settings for the extension channels.

8.1 Prompt Input (CLI)

* You can sort the table by clicking on the column name.

Chord	Action
Enter	Submit the prompt
Shift+Enter	Insert a newline within the prompt
Up / Down	Recall previous / next prompts in history
Ctrl+R	Search prompt history
Tab	Autocomplete file paths, slash commands, or @ references
Shift+Tab	Cycle through permission modes (Manual → Accept Edits → Plan, then Auto when auto mode is available, and back to Manual; from Auto, the first press goes to Manual)
Esc	Interrupt the current model response
Esc Esc	Clear the draft when the input has text, or open the rewind menu when it is empty
Ctrl+C	Interrupt a running operation; when nothing is running, the first press clears the input and a second press exits
Ctrl+D	Exit the CLI (press twice within 800 ms); with text in the prompt, deletes the character after the cursor
@<file>	Attach a file reference (autocomplete-driven)
!<command>	Bash mode: run shell command without invoking the model
/<command>	Slash command

8.2 IDE Extensions (VS Code and JetBrains)

The IDE extensions expose a Claude Code panel and a small set of editor-level keybindings. The defaults vary slightly between VS Code and JetBrains, but the common actions are:

Action	VS Code (default)	JetBrains (default)
Open or focus Claude	Cmd+Esc (macOS) / Ctrl+Esc (Win/Linux) toggles focus between the editor and Claude	Cmd+Esc (macOS) / Ctrl+Esc (Win/Linux) quick launch
Share the current selection	Claude sees the selected text automatically; Option+K / Alt+K also inserts an @-mention	Cmd+Option+K (macOS) / Alt+Ctrl+K inserts a file reference
Open the active prompt input	Panel-specific input area	Panel-specific input area

Both extensions read the same settings.json tree as the CLI, so permissions, hooks, and MCP server approvals apply uniformly.

8.3 Desktop App

The Desktop app's Code tab has its own shortcuts, such as Cmd+N / Ctrl+N for a new session, Cmd+/ / Ctrl+/ for the full shortcut list, and Cmd+Shift+M / Ctrl+Shift+M for the permission mode menu. Shift+Tab does not cycle permission modes there as it does in the CLI.

9. Recent Additions

Significant additions in the three months ending 2026-11 (rows checked through Claude Code v2.1.322, published to npm on 2026-11-10). Each row is dated by the npm release of the version that added it; see the CHANGELOG for details.

* You can sort the table by clicking on the column name.

Date	Area	Addition
2026-09-03	CLI	Diff panel beside the conversation in fullscreen mode, toggled with /diff (v2.1.260)
2026-09-11	Output styles	/output-style [name] to list and switch output styles (v2.1.269)
2026-09-22	Models	Claude Opus 5.5 (claude-opus-5-5) becomes the default Opus model (v2.1.280)
2026-09-28	Models	Claude Sonnet 5.5 (claude-sonnet-5-5) becomes the default Sonnet model on the Anthropic API (v2.1.284)
2026-09-28	Permissions	Interactive terminal and VS Code sessions start in auto mode when no permission mode is configured, on every plan and provider (v2.1.284)
2026-10-01	Plugins	Claude Mods: plugins may modify deeper behavior (v2.1.287)
2026-10-07	Models	Claude Haiku 5.5 (claude-haiku-5-5) becomes the default Haiku model on the Anthropic API (v2.1.293)
2026-10-08	Hooks	onFailure: "block" for command and HTTP hooks: a hook that can't start, times out, or exits with an unexpected code blocks the action (v2.1.295)
2026-10-14	Compaction	Idle compaction in the terminal: a long conversation left idle is compacted before its prompt cache expires (v2.1.299)
2026-10-30	Permissions	permissions.blockWritesOutsideWorkingDirectories (v2.1.314)
2026-11-06	Permissions	permissions.denyInsteadOfPrompting (v2.1.319)
2026-11-09	Models	Claude Fable 5.2 (claude-fable-5-2) becomes the default Fable model (v2.1.321)

Rows older than three months drop out at the next refresh.

10. Recent Deprecations

Items that the documentation or release notes have marked for removal. Each is paired with its replacement. Entries remain in this section for one full refresh cycle after the announced removal date.

* You can sort the table by clicking on the column name.

Area	Deprecated	Replacement	Status
MCP transports	sse (older Server-Sent Events transport, deprecated)	streamable-http (alias: http)	Deprecated in the MCP documentation; existing sse configs still work, but new remote servers should use http
Settings	Older <project>/.mcp.json auto-trust behavior	Explicit allow-list via enabledMcpjsonServers	Behavior changed; legacy auto-trust is no longer the default
Models	Fast mode on Opus 4.8	Opus 5.5 with fast mode, or fast mode turned off	Deprecated on 2026-10-30; removal on 2026-11-30, after which fast mode requests on Opus 4.8 return an error
Settings	includeCoAuthoredBy	attribution	Deprecated since v2.0.62; still read, but new configurations should set attribution
Tools	TodoWrite	TaskCreate, TaskGet, TaskList, TaskUpdate	Disabled by default in favor of the task tools
Tools	Task tool name	Agent	Renamed in v2.1.63; existing Task(...) references still work as aliases

Items that have been removed entirely (no current alias) are not listed here; consult the upstream changelog for the full purge list.

11. Frequently Asked Questions

Short, direct answers to the questions that come up most often when teams adopt Claude Code. The questions are phrased to match how AI search engines retrieve Q and A blocks.

Q1. Through which channels can I use Claude Code as of 2026?

Claude Code is available as a CLI, a VS Code extension, a JetBrains plugin, a Desktop app for macOS and Windows (Linux in beta), a Web surface at claude.ai/code, an embeddable Claude Agent SDK for TypeScript and Python, a GitHub Action, and a GitHub App. The CLI is the reference surface; every other channel mirrors a subset of its tools. The Web surface is the only channel that does not touch your local file system.

Q2. What is the difference between a subagent, a skill, and a slash command?

A slash command is typed as /<name>; built-in commands reach into harness state, and custom commands, now merged into skills, insert a prompt. A skill is a named bundle of instructions plus optional helper files that Claude runs through the Skill tool or you invoke as /<name>; it carries domain logic and parameterized inputs. A subagent is a separate Claude session launched via the Agent tool (formerly Task); it has its own context window and is the right choice when context isolation or parallelism is the point.

Q3. Which hook event runs before a tool executes, and can it block the call?

PreToolUse runs before every tool execution. It receives the tool name and tool input on stdin. Exit code 2 from the hook blocks the call; exit code 0 lets it continue; exit code 1 or any other code is a non-blocking error, so the call proceeds and the user sees a hook error notice (unless the hook sets onFailure: "block"). This is the recommended location for guardrails (vetoing dangerous Bash patterns, scanning Write content for secrets, etc.).

Q4. Where does Claude Code read settings from, and which file wins?

Claude Code reads from five layers and merges them from lowest to highest precedence: user ~/.claude/settings.json, project <project>/.claude/settings.json, project <project>/.claude/settings.local.json, CLI flags, then the enterprise managed settings file. Higher-precedence layers override lower ones for scalar keys; arrays generally concatenate. The enterprise managed layer is the absolute policy floor — CLI flags and lower layers cannot relax it. For permissions, rules are evaluated deny, then ask, then allow across the merged layers, so a deny rule from any layer wins.

Q5. How do I add a custom MCP server to a single project without exposing it to other projects?

Add it at the default local scope with claude mcp add (for example, claude mcp add --transport http <name> <url>); Claude Code stores it in ~/.claude.json under the current project only. To share it with the team instead, use --scope project, which writes <project>/.mcp.json; teammates approve it (or list it in enabledMcpjsonServers) before it loads. For credentials, reference an environment variable in the headers block and inject the variable via env or a wrapper script. Use /mcp to verify the server connected before relying on it.

Q6. What is the difference between /compact and /clear?

/clear resets the conversation to an empty state, keeping cwd and settings. /compact summarizes the conversation so far and continues from that summary; older turns are condensed but the conceptual thread is preserved. Use /compact when you are running into context window pressure but the work is not yet done; use /clear when starting a fresh task.

Q7. How do I make a hook script that always runs after Claude writes a file?

Register a PostToolUse hook with a matcher of "Write|Edit". The hook script receives the tool name and result JSON on stdin. Use the path it reports (tool_input.file_path) to format, lint, or commit the file. Worked examples are in Claude Code Harness and Environment Engineering.

Q8. What is Shift+Tab for?

Shift+Tab cycles through the permission modes in its default cycle: Manual (default, prompt per call), Accept Edits (acceptEdits, file edits and common filesystem commands proceed without prompting; other tools still respect rules), Plan Mode (plan, explores and plans; edits stay blocked until you approve the plan), and Auto (auto, a background classifier reviews actions; in the cycle when auto mode is available). bypassPermissions joins the cycle only in a session started with it, and dontAsk never does. The current mode is shown in the status line. The companion getting-started article walks through when to use each.

Q9. Can I run Claude Code without an interactive terminal, for example in CI?

Yes. The CLI's -p (--print) flag runs non-interactively and takes the prompt as an argument or from stdin; the GitHub Action wraps this for pull-request review. For API-key authentication in unattended environments, point apiKeyHelper at a script that retrieves the key from a secret manager rather than committing it to disk.

Q10. How do I see exactly what Claude Code is doing in a session?

/status shows the version, model, and account. /usage (alias /cost) shows session usage. /mcp shows MCP connection state. For full transcripts and tool invocations, enable OpenTelemetry by setting CLAUDE_CODE_ENABLE_TELEMETRY=1 together with the standard OTel exporters (OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER) and, if you need extended span attributes such as file_path and full_command, OTEL_LOG_TOOL_DETAILS=1. For ad-hoc auditing without a collector, register a PostToolUse hook that appends structured events to your own pipeline.

12. References

External documentation and adjacent internal articles. Internal links point to other pages on this site; external links open in a new tab.

12.1 Official Documentation

• Claude Code documentation home
• CLI installation and quickstart
• Settings and settings reference
• Hooks reference
• Slash commands reference
• MCP integration
• Subagents
• Skills
• Tools reference
• Plan mode and permission modes

12.2 Related Internal Articles

• Claude Code Getting Started - Why Knowing About Local AI Agents Changes Everything - install walkthroughs, first session, beginner pitfalls.
• Claude Code Harness and Environment Engineering: Designing the Frontline Where Local AI Agents Actually Live - operational design, permission patterns, hook examples, three reference profiles.
• Code Review Checklist and Anti-Pattern Catalog: A Reviewer's Reference for Modern and AI-Augmented Codebases - what to check when an AI-augmented workflow produced the diff under review.

This snapshot is refreshed as needed within the publication year. Last reviewed: 2026-11.

References:
Tech Blog with curated related content