# Claude Code — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Claude Code KB — Master Index" type: index updated: 2026-06-10 claude_code_version: "2.1.172" --- # Claude Code KB — Master Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. **Latest verified Claude Code version:** 2.1.172 (2026-06-10) **KB pages:** 32 (13 concepts + 8 entities + 4 summaries + 5 syntheses + 2 system) ## Concepts (13) ### Getting started & daily use - [[concepts/installation-setup]] — install per platform, first run, login flows, credential storage - [[concepts/configuration]] — settings.json hierarchy (user/project/local/managed), env vars, config debugging - [[concepts/cli-reference]] — commands, flags, print mode for CI, structured output, session resume - [[concepts/interactive-mode]] — slash commands, keyboard shortcuts, vim mode, keybindings.json, fullscreen TUI - [[concepts/memory-context]] — CLAUDE.md load order, imports, auto memory, context window & compaction - [[concepts/checkpointing]] — /rewind, restore vs summarize, what checkpoints do and don't track - [[concepts/permissions-security]] — six permission modes, rule syntax, auto mode, sandboxing, security model ### Extending & automating - [[concepts/skills-system]] — SKILL.md anatomy, locations/precedence, context costs, when to use a skill - [[concepts/subagents-orchestration]] — subagents, agent view, background sessions, teams, parallel patterns - [[concepts/hooks-system]] — lifecycle events, hook types, exit-code/JSON contract, recipes, pitfalls - [[concepts/mcp-integration]] — adding servers, scopes, OAuth, tool search at scale, org-level control - [[concepts/agent-sdk]] — the Claude Agent SDK: when to use vs CLI, sessions, streaming, hosting - [[concepts/enterprise-deployment]] — Bedrock/Vertex/gateways, managed settings, analytics, OTel, compliance ## Entities (8) - [[entities/desktop-app]] — sessions, cowork, scheduled tasks, shortcuts, launch.json - [[entities/ide-extensions]] — VS Code + JetBrains: install, features, WSL2 notes - [[entities/claude-code-web]] — cloud sessions, teleport, deep links, channels, Chrome beta - [[entities/github-actions]] — the @v1 action, managed code review, GHES support - [[entities/gitlab-cicd]] — GitLab CI/CD integration (beta, GitLab-maintained) - [[entities/plugin-marketplaces]] — marketplaces, the Claude directory, bundled plugins, /plugin commands - [[entities/agent-sdk-typescript]] — TS SDK reference: query(), tools, sessions, v2 API removal note - [[entities/agent-sdk-python]] — Python SDK reference: query() vs ClaudeSDKClient, @tool, options ## Summaries (4) - [[summaries/changelog-digest]] — version digest 2.1.156 → 2.1.172 with notable features per release - [[summaries/casebook-install-auth]] — solved cases: 529s, credential restrictions, usage-drain incident, Node-18 false positive - [[summaries/casebook-runtime]] — solved cases: compaction failures, permission loops, Windows/WSL, Cowork blockers - [[summaries/best-practices]] — the official best-practices guide + common workflows, distilled ## Syntheses (5) - [[syntheses/surface-picker]] — CLI vs desktop vs IDE vs web: pick by use case - [[syntheses/extension-decision-guide]] — skill vs hook vs MCP vs subagent vs plugin vs SDK - [[syntheses/permission-mode-picker]] — modes + sandboxing compared by risk profile - [[syntheses/cost-management]] — model/effort/fast-mode/caching levers and usage tracking - [[syntheses/troubleshooting-checklist]] — the 8-step ordered check sequence ## Gaps / TODO - `raw/` lacks the dedicated VS Code extension doc (`vs-code.md` listed in llms.txt but not fetched) — [[entities/ide-extensions]] is medium-confidence on the VS Code half; fetch and upgrade on next ingest. - Dedicated routines (remote scheduled tasks) doc and standalone skills/sub-agents pages not in raw/ — covered via adjacent pages. - Claude Code releases multiple times per week — re-verify [[summaries/changelog-digest]] and bump `claude_code_version` on each ingest. ## Statistics - **Total pages**: 32 - **Concepts**: 13 - **Entities**: 8 - **Summaries**: 4 - **Syntheses**: 5 --- title: "Claude Agent SDK" type: concept tags: [agent-sdk, programmatic, hosting, sessions, streaming, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-agent-sdk-overview.md", "raw/llms_txt_doc-hosting-the-agent-sdk.md", "raw/llms_txt_doc-migrate-to-claude-agent-sdk.md", "raw/llms_txt_doc-work-with-sessions.md", "raw/llms_txt_doc-stream-responses-in-real-time.md", "raw/llms_txt_doc-streaming-input.md", "raw/llms_txt_doc-todo-lists.md"] --- ## Definition The Claude Agent SDK is Claude Code as a library: the same tools, agent loop, and context management that power the CLI, programmable from Python (`pip install claude-agent-sdk`, Python 3.10+) and TypeScript (`npm install @anthropic-ai/claude-agent-sdk`, Node 18+). One `query()` call gives you an agent that reads files, runs commands, edits code, and searches the web autonomously — you iterate over messages instead of implementing a tool loop. ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Find and fix the bug in auth.ts", options: { allowedTools: ["Read", "Edit", "Bash"] } })) { console.log(message); } ``` ## How It Works ### The subprocess model `query()` spawns a separate `claude` CLI subprocess and talks to it over stdio. Both SDK packages bundle a native Claude Code binary pinned to the package version, so no separate install — updating the SDK updates the CLI. One session = one subprocess that owns a shell, a working directory (`cwd` option), and JSONL transcripts under `~/.claude/projects//` (or `$CLAUDE_CONFIG_DIR/projects/`). Authentication is by API key (`ANTHROPIC_API_KEY`) or a third-party provider: `CLAUDE_CODE_USE_BEDROCK=1`, `CLAUDE_CODE_USE_VERTEX=1`, `CLAUDE_CODE_USE_FOUNDRY=1` (Azure), or `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` + `ANTHROPIC_AWS_WORKSPACE_ID`. Third-party developers may not offer claude.ai login/rate limits to their users. Note: starting June 15, 2026, SDK and `claude -p` usage on subscription plans draws from a separate monthly Agent SDK credit. Capabilities mirror the CLI: built-in tools (Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion), in-process hook callbacks ([[concepts/hooks-system]]), programmatic subagents via the `agents` option ([[concepts/subagents-orchestration]]), MCP servers and custom in-process tools ([[concepts/mcp-integration]]), and permission control via `allowedTools`/`permissionMode` ([[concepts/permissions-security]]). With default options, filesystem configuration also loads — skills from `.claude/skills/`, CLAUDE.md, settings — controlled by `settingSources` (TypeScript) / `setting_sources` (Python); pass `[]` to isolate. The SDK also auto-creates task lists for multi-step work (structured `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` tools since v2.1.142, replacing `TodoWrite`). ### When to use SDK vs CLI vs other options | Use case | Best choice | |---|---| | Interactive development, one-off tasks | CLI ([[concepts/cli-reference]]) | | CI/CD pipelines, custom applications, production automation | Agent SDK | | Raw API access where you implement tools yourself | Anthropic Client SDK | | Hosted agents with no infrastructure to operate | Managed Agents (Anthropic-run REST API) | A common path: prototype with the Agent SDK locally, move to Managed Agents for production. Branding note for products: "Claude Agent" is permitted; "Claude Code" branding is not. ### Sessions: continue, resume, fork A session persists the *conversation* (not the filesystem — that's [[concepts/checkpointing]]). Options on `query()`: * **Continue** (`continue: true` TS / `continue_conversation=True` Python): resumes the most recent session in the current directory, no ID tracking. Python's `ClaudeSDKClient` holds a session open across `client.query()` calls automatically. * **Resume** (`resume: sessionId`): return to a specific session. Capture the ID from the result message's `session_id` field. Required for multi-user apps. * **Fork** (`resume` + `forkSession: true` / `fork_session=True`): new session seeded with a copy of the history; the original is untouched. Branches conversation, not files. If `resume` returns a fresh session, the usual cause is a mismatched `cwd` — sessions live under the encoded working-directory path. To resume across hosts, mirror transcripts with a `SessionStore` adapter (S3, Redis, Postgres reference implementations), or carry forward results as application state instead. `listSessions()`/`getSessionMessages()` (and Python equivalents) enumerate sessions on disk. TypeScript-only: `persistSession: false` keeps a session memory-only. ### Streaming Two independent axes: * **Input modes**: streaming input (default and recommended — pass an AsyncGenerator of user messages; supports image attachments, queued messages, interruption) vs single-message input (one-shot string prompt; simpler, suits stateless environments like Lambda, but no images or mid-session control). * **Output streaming**: set `includePartialMessages: true` (TS) / `include_partial_messages=True` (Python) to receive raw API `StreamEvent`s alongside complete messages. Extract text from `content_block_delta` events with `delta.type === "text_delta"`; tool calls stream via `content_block_start` → `input_json_delta` chunks → `content_block_stop`. Structured output appears only in the final `ResultMessage.structured_output`, never as deltas. ### Hosting in production Hosting is not stateless-API hosting: every agent is a long-lived process tied to local state. Patterns: **ephemeral** (container per task), **long-running** (persistent containers, multiple subprocesses; pre-warm with `startup()`, add turns with `streamInput()`), **hybrid** (ephemeral containers that hydrate from a `SessionStore` — the store is mandatory here), **multi-agent container**. Sandbox providers to evaluate: Modal, Cloudflare Sandboxes, Daytona, E2B, Fly Machines, Vercel Sandbox. Operational facts (verbatim values): start at 1 GiB RAM / 5 GiB disk / 1 CPU per agent; `agents per host = (host RAM - overhead) / per-session RAM ceiling`; outbound HTTPS to `api.anthropic.com` (or provider endpoint) required; token cost dominates infra cost by ~10x. Observability: OTEL env vars are inherited — `CLAUDE_CODE_ENABLE_TELEMETRY=1`, plus `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` for traces (see [[concepts/enterprise-deployment]]). Multi-tenant isolation: `settingSources: []`, `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, per-tenant `CLAUDE_CONFIG_DIR` and `cwd`, per-tenant egress rules. No built-in session timeout — bound work with `maxTurns`. ### Migration note The Claude Code SDK was renamed: `@anthropic-ai/claude-code` → `@anthropic-ai/claude-agent-sdk`, `claude-code-sdk` → `claude-agent-sdk`, and Python's `ClaudeCodeOptions` → `ClaudeAgentOptions`. Two behavioral changes to review: the SDK no longer uses Claude Code's system prompt by default (request it with `systemPrompt: { type: "preset", preset: "claude_code" }`), and `settingSources` defaults to loading user/project/local settings like the CLI (briefly changed in v0.1.0, then reverted; pass `[]` for isolation). The experimental TypeScript V2 session API (`createSession()`) was removed in 0.3.142 — use `query()` with session options. ## Key Parameters * `allowedTools` / `permissionMode` — `query()` options gating which tools run and how permissions resolve ([[concepts/permissions-security]]). * `cwd` — working directory the subprocess owns; also determines where session transcripts live (mismatched `cwd` breaks `resume`). * `settingSources` (TS) / `setting_sources` (Python) — which filesystem config loads (skills, CLAUDE.md, settings); pass `[]` to isolate multi-tenant or CI runs. * `continue` / `resume` / `forkSession` (`continue_conversation` / `fork_session` in Python) — session continuation, resumption by ID, and history-copying forks. * `includePartialMessages: true` / `include_partial_messages=True` — emit raw API `StreamEvent`s for output streaming. * `systemPrompt: { type: "preset", preset: "claude_code" }` — restore the Claude Code system prompt (no longer default post-rename). * `agents` / `mcpServers` — programmatic subagent definitions and MCP/in-process custom tool servers. * `maxTurns` — the only built-in bound on a session; there is no session timeout. * `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_USE_BEDROCK=1` / `CLAUDE_CODE_USE_VERTEX=1` / `CLAUDE_CODE_USE_FOUNDRY=1` / `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` + `ANTHROPIC_AWS_WORKSPACE_ID` — authentication env vars. * `CLAUDE_CONFIG_DIR` and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` — per-tenant config/transcript isolation in hosting. * `CLAUDE_CODE_ENABLE_TELEMETRY=1` (+ `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` for traces) — OTEL observability, inherited from the environment. * `persistSession: false` (TypeScript-only) — keep a session memory-only; `env` replaces the subprocess environment in TS (spread `...process.env`) but merges in Python. ## When To Use Reach for the SDK when Claude Code needs to run without a human at the terminal: CI bots, email/support agents, SRE automation, research pipelines, or any product embedding an agent. Stay with the CLI for interactive work; the workflows translate directly between them. See [[entities/agent-sdk-typescript]] and [[entities/agent-sdk-python]] for per-language references. ## Risks & Pitfalls * **State loss**: transcripts, CLAUDE.md, and working-directory artifacts live on local disk and die with the container; `SessionStore` mirrors transcripts only (watch for `mirror_error` system messages), so memory files need separate storage. * **Generator errors are obscured**: a throwing TypeScript input generator surfaces as `Claude Code process aborted by user`; in Python the session stalls silently — enable debug logging. * **Error results raise**: a single-message `query()` ending in `error_max_turns` raises after yielding the result; wrap in try/catch to continue. * **Settings leakage**: defaults load filesystem settings — a hazard in multi-tenant or CI environments; isolate explicitly. * **Rate limits on fanout**: large parallel-subagent dispatches can hit API limits; batch the work. * **TS `env` replaces the subprocess environment** (spread `...process.env`); Python `env` merges. ## Related Concepts [[concepts/subagents-orchestration]] · [[concepts/hooks-system]] · [[concepts/mcp-integration]] · [[concepts/permissions-security]] · [[concepts/checkpointing]] · [[concepts/cli-reference]] · [[concepts/enterprise-deployment]] · [[entities/agent-sdk-typescript]] · [[entities/agent-sdk-python]] ## Sources SDK overview, hosting guide, migration guide, sessions guide, output-streaming and input-mode pages, and the SDK todo-tracking doc. The full per-language API references (raw/llms_txt_doc-agent-sdk-reference-*.md) back the entity pages rather than this concept page. --- title: "Checkpointing: Rewind File Changes and Conversation" type: concept tags: [checkpointing, rewind, undo, safety, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-checkpointing.md", "raw/llms_txt_doc-rewind-file-changes-with-checkpointing.md"] --- # Checkpointing: Rewind File Changes and Conversation ## Definition Checkpointing automatically snapshots files before Claude edits them, so you can undo changes and rewind code, conversation, or both to a previous point. It's session-level "local undo" that complements — and does not replace — git. ## How It Works ### Automatic tracking - Every user prompt creates a new checkpoint; before each edit, the affected file's current contents are captured. - Checkpoints persist across sessions, so resumed conversations can still rewind. - They're cleaned up along with sessions after 30 days (configurable). - Only edits made through Claude's file-editing tools (Write, Edit, NotebookEdit) are tracked. ### The rewind menu Run `/rewind` (aliases `/checkpoint`, `/undo`), or press `Esc` twice **when the prompt input is empty** (with text in the input, double-`Esc` clears it instead — press `Up` to recall the cleared draft). The menu lists each prompt you sent; pick a point, then choose: - **Restore code and conversation** — revert both to that point - **Restore conversation** — rewind messages, keep current code - **Restore code** — revert files, keep the conversation - **Summarize from here** — replace the selected message and everything after with an AI summary (keep early context in full) - **Summarize up to here** — replace everything before the selected message with a summary (keep recent work in full) - **Never mind** — back out After restoring the conversation or choosing Summarize from here, the original prompt from the selected message lands back in your input field for re-sending or editing. ### Restore vs. summarize Restore reverts state; summarize compresses part of the conversation **without touching files on disk**, freeing context window space. The original messages remain in the session transcript, so Claude can still reference details. It's `/compact` with aim: you choose which side of a message to compress, and can type instructions to guide the summary. To branch off and try a different approach while preserving the original session instead, fork: `claude --continue --fork-session`. ### Checkpointing in the Agent SDK The same machinery is exposed programmatically. Enable with `enable_file_checkpointing=True` (Python) / `enableFileCheckpointing: true` (TypeScript), and add `extra_args={"replay-user-messages": None}` / `extraArgs: { "replay-user-messages": null }` — required to receive checkpoint UUIDs on user messages in the stream. Capture a user message `uuid` as the restore point (and `session_id` if rewinding later), then call `rewind_files(checkpoint_id)` / `rewindFiles(checkpointId)`. Rewinding after the stream completes requires resuming the session with an empty prompt first; calling rewind after iteration ends otherwise raises "ProcessTransport is not ready for writing". From the CLI: ```bash claude -p --resume --rewind-files ``` SDK rewinds restore files only — conversation history and context remain intact. Common patterns: keep just the latest checkpoint UUID and rewind on error ("checkpoint before risky operations"), or store all UUIDs with metadata for multiple restore points (e.g. keep turn one's refactor, undo turn two's tests). ## Key Parameters - `/rewind` or empty-prompt `Esc Esc` — interactive entry points - `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1` — disables file checkpointing; `/rewind` can no longer restore code changes - SDK: `enable_file_checkpointing` / `enableFileCheckpointing`, `replay-user-messages`, `rewind_files()` / `rewindFiles()`, `--rewind-files` CLI flag - Retention: 30 days with session cleanup (configurable) ## When To Use - **Exploring alternatives**: try an implementation, rewind, try another — without git branch ceremony. - **Recovering from mistakes**: undo a change that broke functionality in seconds. - **Freeing context**: summarize a verbose debugging stretch from its midpoint while keeping initial instructions intact (see [[concepts/memory-context]] for the broader compaction picture). - **SDK guardrails**: snapshot before risky autonomous operations and auto-rewind on validation failure (see [[concepts/agent-sdk]]). ## Risks & Pitfalls - **Bash-command changes are not tracked.** `rm file.txt`, `mv old.txt new.txt`, `echo > file.txt`, `sed -i` — none of these can be undone through rewind. Only the file-editing tools are covered. - **External changes are not tracked**: manual edits outside Claude Code and edits from concurrent sessions are normally not captured. - File content only: creating, moving, or deleting directories is not undone; remote/network files aren't tracked; checkpoints are tied to the session that created them. - Not version control: keep using git for commits, branches, and permanent history. Checkpoints are the local undo; git is the durable record. - Actions with external side effects (databases, APIs, deployments) can't be checkpointed at all — that's the job of permission prompts ([[concepts/permissions-security]]). - SDK: missing `message.uuid` values mean `replay-user-messages` isn't set; "No file checkpoint found for message" usually means checkpointing wasn't enabled on the original session. ## Related Concepts - [[concepts/interactive-mode]] — the `Esc Esc` shortcut and rewind menu navigation - [[concepts/memory-context]] — `/compact` and what survives summarization - [[concepts/permissions-security]] — the complementary safety layer for irreversible actions - [[concepts/agent-sdk]] — programmatic checkpoint/rewind APIs - [[summaries/casebook-runtime]] — observed checkpoint/rewind issues in the field ## Sources - `raw/llms_txt_doc-checkpointing.md` — rewind menu, restore vs. summarize, limitations - `raw/llms_txt_doc-rewind-file-changes-with-checkpointing.md` — SDK options, UUID capture, rewind patterns, troubleshooting --- title: "CLI Reference: Commands, Flags, and Print Mode" type: concept tags: [cli, automation, headless, scripting, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-cli-reference.md", "raw/llms_txt_doc-run-claude-code-programmatically.md"] --- # CLI Reference: Commands, Flags, and Print Mode ## Definition The `claude` binary is both an interactive REPL launcher and a scriptable non-interactive tool. This page covers the CLI commands and flags, non-interactive ("print") mode with `-p`, session resume, and structured JSON output for pipelines. ## How It Works ### Core commands | Command | What it does | | --- | --- | | `claude` | Start interactive session | | `claude "query"` | Start interactive session with initial prompt | | `claude -p "query"` | Query non-interactively, print result, exit | | `cat file | claude -p "query"` | Process piped content (stdin capped at 10MB as of v2.1.128) | | `claude -c` | Continue most recent conversation in current directory | | `claude -r "" "query"` | Resume session by ID or name | | `claude update` / `claude install [version]` | Update or install/reinstall (`stable`, `latest`, or e.g. `2.1.118`) | | `claude auth login` / `logout` / `status` | Authentication management | | `claude mcp` | Configure MCP servers | | `claude plugin` | Manage plugins (e.g. `claude plugin install code-review@claude-plugins-official`) | | `claude setup-token` | Generate a long-lived OAuth token for CI | | `claude agents` / `attach ` / `logs ` / `stop ` / `respawn ` / `rm ` | Background-session management | | `claude project purge [path]` | Delete local state for a project (`--dry-run` to preview) | | `claude auto-mode defaults` / `config` / `critique` | Inspect auto-mode classifier rules | Mistyped subcommands get a suggestion (`claude udpate` → `Did you mean claude update?`). `claude --help` does not list every flag. ### Essential flags - **Sessions**: `--continue`/`-c`, `--resume`/`-r` (ID, name, or interactive picker), `--fork-session` (new session ID when resuming), `--session-id `, `--name`/`-n` (display name, resumable by name), `--from-pr 123` (resume sessions linked to a PR) - **Models**: `--model` (alias `sonnet`/`opus`/`haiku`/`fable` or full name), `--effort low|medium|high|xhigh|max`, `--fallback-model sonnet,haiku` - **Permissions**: `--permission-mode` (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`), `--allowedTools`, `--disallowedTools`, `--tools "Bash,Edit,Read"` (restrict available built-ins), `--dangerously-skip-permissions` - **Context/config**: `--add-dir`, `--settings `, `--setting-sources user,project,local`, `--mcp-config ./mcp.json`, `--strict-mcp-config`, `--agents ''`, `--plugin-dir ./my-plugin` - **System prompt**: `--system-prompt` / `--system-prompt-file` (replace; mutually exclusive with each other) and `--append-system-prompt` / `--append-system-prompt-file` (append; combinable with either). Append when Claude should stay a coding assistant with extra rules; replace only when you take responsibility for tool guidance and safety instructions yourself. - **Diagnostics**: `--debug "api,mcp"`, `--debug-file /tmp/claude-debug.log`, `--safe-mode` (v2.1.169+, all customizations off), `--verbose`, `--version`/`-v` - **Isolation**: `--worktree`/`-w` (git worktree at `/.claude/worktrees/`), `--bg` (start as background agent) ### Print mode (`-p`) for scripts and CI All CLI options work with `-p`. The recommended pattern for scripted calls is **bare mode**: ```bash claude --bare -p "Summarize this file" --allowedTools "Read" ``` `--bare` skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md, so runs are fast and reproducible across machines; pass any context you need explicitly (`--settings`, `--mcp-config`, `--agents`, `--plugin-dir`, `--append-system-prompt`). Bare mode skips OAuth/keychain reads — authenticate with `ANTHROPIC_API_KEY` or an `apiKeyHelper`. Print-mode-only guardrails: `--max-turns 3`, `--max-budget-usd 5.00`, `--no-session-persistence`. ### Structured output `--output-format` accepts `text` (default), `json` (result, session ID, metadata including `total_cost_usd`), and `stream-json` (newline-delimited events). For schema-validated output: ```bash claude -p "Extract the main function names from auth.py" \ --output-format json \ --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' ``` The validated payload lands in the `structured_output` field; extract with `jq '.structured_output'` or the text result with `jq -r '.result'`. For token-level streaming, combine `--output-format stream-json --verbose --include-partial-messages`. The stream includes `system/init` (model, tools, plugins, `plugin_errors`) and `system/api_retry` events for CI failure handling. ### Resume in pipelines ```bash session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id') claude -p "Continue that review" --resume "$session_id" ``` Or chain with `--continue`: `claude -p "Now focus on the database queries" --continue`. ## Key Parameters Permission rule syntax in `--allowedTools` uses prefix matching with a trailing ` *`: ```bash claude -p "Look at my staged changes and create an appropriate commit" \ --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)" ``` **The space before `*` matters**: `Bash(git diff*)` would also match `git diff-index`. `acceptEdits` mode auto-approves file writes plus common filesystem commands (`mkdir`, `touch`, `mv`, `cp`); `dontAsk` denies anything not pre-approved — useful for locked-down CI, where an unapproved tool call aborts the run. ## When To Use - Interactive development: plain `claude`; see [[concepts/interactive-mode]]. - One-shot queries, lint bots, commit generators, CI checks: `claude --bare -p` with explicit `--allowedTools` and `--output-format json`. - Long-lived programmatic control (callbacks, message objects, structured streaming): use the [[concepts/agent-sdk]] instead of shelling out. - Parallel/background work: `--bg`, `claude agents`, `--worktree` (see [[concepts/subagents-orchestration]]). ## Risks & Pitfalls - Without `--bare`, `claude -p` loads the same context an interactive session would — a teammate's `~/.claude` hook or a project `.mcp.json` can change script behavior between machines. - Interactive-dialog commands (`/config`, `/login`) are unavailable in `-p` mode; user-invoked skills do work by including `/skill-name` in the prompt string. - Piped stdin over 10MB exits non-zero; write large inputs to a file and reference the path. - Background bash tasks started during a `-p` run are terminated ~5 seconds after the final result (v2.1.163+). - Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans draws from a separate monthly Agent SDK credit — relevant for [[syntheses/cost-management]]. ## Related Concepts - [[concepts/interactive-mode]] — the REPL side: slash commands and shortcuts - [[concepts/agent-sdk]] — Python/TypeScript packages built on the same engine - [[concepts/permissions-security]] — full permission rule and mode semantics - [[concepts/configuration]] — `--settings` interplay with settings files - [[entities/github-actions]] and [[entities/gitlab-cicd]] — CI integrations using print mode ## Sources - `raw/llms_txt_doc-cli-reference.md` — complete command and flag tables, system-prompt flag guidance - `raw/llms_txt_doc-run-claude-code-programmatically.md` — `-p` patterns, bare mode, structured output, streaming events, resume --- title: "Configuration: settings.json Hierarchy and Environment Variables" type: concept tags: [configuration, settings, environment-variables, debugging, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-environment-variables.md", "raw/llms_txt_doc-debug-your-configuration.md", "raw/github_doc-examples-settings-readme-md.md", "raw/llms_txt_doc-configure-auto-mode.md"] --- # Configuration: settings.json Hierarchy and Environment Variables ## Definition Claude Code is configured through layered `settings.json` files (user, project, local, managed), environment variables, CLI flags, and in-session commands. Knowing which layer wins — and how to inspect what actually loaded — is the difference between a setting that works and one that's silently overridden. ## How It Works ### The settings file hierarchy | File | Applies to | | --- | --- | | `~/.claude/settings.json` | You, in every project | | `.claude/settings.json` | Everyone working in the project, checked into source control | | `.claude/settings.local.json` | You, in this project only (add to your gitignore) | | Managed settings | Everyone in your organization, deployed by an admin | **Precedence**: managed settings always win when present. Among the rest, the closer scope overrides the broader one — local, then project, then user. CLI flags and environment variables act as another override layer; e.g. `--settings ` overrides the same keys in your settings files for one session. A critical gotcha: `~/.claude.json` holds app state and UI toggles. **`permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`** — these are two different files, and configuration placed in `~/.claude.json` is ignored. ### Environment variables Set in your shell before launching (`export API_TIMEOUT_MS="1200000"` then `claude`; PowerShell: `$env:API_TIMEOUT_MS = "1200000"`), or persistently under the `env` key in a settings file: ```json { "env": { "API_TIMEOUT_MS": "1200000", "BASH_DEFAULT_TIMEOUT_MS": "300000" } } ``` Where a behavior has both an env var and a settings field, **the environment variable takes precedence** (e.g. `ANTHROPIC_MODEL` overrides the `model` setting). Interaction with flags varies per feature: `--model` and `/model` override `ANTHROPIC_MODEL`, while `CLAUDE_CODE_EFFORT_LEVEL` overrides `/effort`. Env vars are read at startup; changes take effect on the next launch. Note: variables in `settings.json` `env` do **not** propagate to MCP child processes — set per-server `env` inside `.mcp.json` instead. ### Debugging your configuration Run these in-session commands to see what actually loaded: | Command | Shows | | --- | --- | | `/context` | Everything occupying the context window, by category | | `/memory` | Which CLAUDE.md and rules files loaded, plus auto-memory | | `/doctor` | Invalid keys, schema errors, installation health (press `f` to have Claude fix issues) | | `/status` | Active settings sources, including whether managed settings are in effect | | `/permissions` | Resolved allow/deny rules in effect | | `/hooks`, `/mcp`, `/skills`, `/agents` | Each extension surface's loaded state | | `/debug [issue]` | Enables debug logging and prompts Claude to diagnose | Two isolation techniques: - `claude --safe-mode` (v2.1.169+) launches with all customizations disabled — CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands — while auth, model, built-in tools, and permissions work normally. If the problem disappears, a customization is the cause. - A fully clean config: `cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude` bypasses everything under `~/.claude`. Managed settings still apply (they live at a system path), and on Linux/Windows you'll re-login since credentials live under the config dir. ## Key Parameters High-leverage environment variables (verbatim names): - `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` — auth and request routing (see [[concepts/installation-setup]]) - `ANTHROPIC_MODEL` — model selection (overridden by `--model` / `/model`) - `API_TIMEOUT_MS` — API request timeout (default 600000) - `BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` — bash command timeouts (defaults 120000 / 600000) - `CLAUDE_CONFIG_DIR` — override the config directory (default `~/.claude`); useful for running multiple accounts side by side - `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` — context percentage (1-100) at which auto-compaction triggers (default ~95%) - `DISABLE_AUTOUPDATER`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` — update/telemetry controls - `CLAUDE_CODE_ENABLE_TELEMETRY` — set to `1` to enable OpenTelemetry collection - `CLAUDE_CODE_DISABLE_CLAUDE_MDS` — set to `1` to prevent loading any CLAUDE.md memory files - `DEBUG`, `CLAUDE_CODE_DEBUG_LOGS_DIR`, `CLAUDE_CODE_DEBUG_LOG_LEVEL` — debug logging (logs default to `~/.claude/debug/.txt`) For organizations, Anthropic publishes example managed settings files (`settings-lax.json`, `settings-strict.json`, `settings-bash-sandbox.json`) covering: disabling `--dangerously-skip-permissions`, blocking plugin marketplaces, blocking user/project permission rules and hooks, denying web tools, and forcing Bash into a sandbox. Certain properties only take effect in enterprise settings: `strictKnownMarketplaces`, `allowManagedHooksOnly`, `allowManagedPermissionRulesOnly`. The `autoMode` settings block (trusted repos, buckets, domains for the auto-mode classifier) is covered in [[concepts/permissions-security]]. ## When To Use - Personal defaults (model, env vars, permission allowlist): `~/.claude/settings.json`. - Team conventions to commit: `.claude/settings.json`. - Machine-specific or private overrides: `.claude/settings.local.json`. - Org policy that users can't override: managed settings, tested locally first by applying to `managed-settings.json`, `settings.json` or `settings.local.json`. - Per-invocation automation overrides: `--settings` flag (see [[concepts/cli-reference]]). ## Risks & Pitfalls - **"My setting is ignored"** is almost always scope shadowing: the same key set in `settings.local.json` overrides `settings.json`, and both override `~/.claude/settings.json`. Check `/status` and `/doctor` before assuming a bug. - Hooks defined in a standalone file never fire — they must live under the `"hooks"` key in `settings.json` (only plugins use a separate `hooks/hooks.json`). See [[concepts/hooks-system]]. - An `mcpServers` key in `settings.json` is not read; project MCP servers go in `.mcp.json` at the repository root. See [[concepts/mcp-integration]]. - Settings files must be valid JSON; `/doctor` reports schema failures, and invalid entries (e.g. an array `matcher`) are dropped. - CLAUDE.md and settings solve different problems: CLAUDE.md is guidance, permissions/hooks are enforcement. Use `permissions.deny` for anything that must never happen. ## Related Concepts - [[concepts/permissions-security]] — permission rules, modes, and the `autoMode` block - [[concepts/memory-context]] — CLAUDE.md loading and the `/memory` view - [[concepts/cli-reference]] — `--settings`, `--setting-sources`, `--safe-mode` - [[concepts/enterprise-deployment]] — managed settings and MDM deployment - [[syntheses/troubleshooting-checklist]] — symptom-to-fix table for config surprises ## Sources - `raw/llms_txt_doc-environment-variables.md` — full env var reference, settings `env` key, precedence - `raw/llms_txt_doc-debug-your-configuration.md` — `/context`, `/doctor`, `--safe-mode`, clean-config test, common-cause table - `raw/github_doc-examples-settings-readme-md.md` — example managed settings, enterprise-only keys, sandbox note - `raw/llms_txt_doc-configure-auto-mode.md` — `autoMode` settings scopes and merge behavior --- title: "Enterprise Deployment" type: concept tags: [enterprise, managed-settings, bedrock, vertex, observability, compliance, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-set-up-claude-code-for-your-organization.md", "raw/llms_txt_doc-claude-code-on-amazon-bedrock.md", "raw/llms_txt_doc-claude-code-on-google-vertex-ai.md", "raw/llms_txt_doc-llm-gateway-configuration.md", "raw/llms_txt_doc-development-containers.md", "raw/llms_txt_doc-track-team-usage-with-analytics.md", "raw/llms_txt_doc-observability-with-opentelemetry.md", "raw/llms_txt_doc-data-usage.md", "raw/llms_txt_doc-legal-and-compliance.md", "raw/llms_txt_doc-securely-deploying-ai-agents.md", "raw/github_doc-examples-mdm-readme-md.md"] --- ## Definition Deploying Claude Code across an organization means making five decisions in order: which API provider it authenticates against, how managed policy reaches developer machines, what that policy enforces, how usage is monitored, and what the data-handling posture is. Managed settings always take precedence over local developer configuration; arrays like `permissions.allow`/`permissions.deny` merge from all sources, so developers can extend managed lists but never remove from them. ## How It Works ### Choose an API provider | Provider | Choose when | |---|---| | Claude for Teams / Enterprise | Per-seat subscription, no infrastructure (default recommendation) | | Claude Console | API-first, pay-as-you-go | | Amazon Bedrock | Inherit AWS compliance and billing | | Google Vertex AI | Inherit GCP compliance and billing | | Microsoft Foundry | Inherit Azure compliance and billing | Some features require a Claude.ai account regardless: [[entities/claude-code-web]], Routines, Code Review, Remote Control, and the Chrome extension are unavailable through Console keys or cloud-provider credentials alone — plan whether Bedrock/Vertex users also need seats. **Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` and `AWS_REGION` (required — not read from `.aws` config); credentials via the standard AWS chain or `AWS_BEARER_TOKEN_BEDROCK`. `/setup-bedrock` provides an interactive wizard. Pin models for fleets, e.g. `ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'` — aliases otherwise resolve to built-in defaults that can lag. `awsAuthRefresh` (e.g. `aws sso login --profile myprofile`) handles SSO refresh; `modelOverrides` in settings maps versions to application inference profile ARNs. IAM needs `bedrock:InvokeModel`, `InvokeModelWithResponseStream`, `ListInferenceProfiles`, `GetInferenceProfile`. The Mantle endpoint (`CLAUDE_CODE_USE_MANTLE=1`) serves the native Anthropic API shape over Bedrock. WebSearch is unavailable on Bedrock; `/logout` is disabled (auth is AWS's job). **Vertex**: set `CLAUDE_CODE_USE_VERTEX=1`, `CLOUD_ML_REGION` (supports `global`, multi-region `eu`/`us`, or regional like `us-east5`), and `ANTHROPIC_VERTEX_PROJECT_ID`. `/setup-vertex` is the wizard; `gcpAuthRefresh` handles credential refresh. Same model-pinning pattern with Vertex IDs (`claude-haiku-4-5@20251001`); IAM role `roles/aiplatform.user`. MCP tool search is off by default on Vertex (see [[concepts/mcp-integration]]). On both clouds, append `[1m]` to a model ID for the 1M-token context window, and set `ANTHROPIC_DEFAULT_HAIKU_MODEL` so background tasks don't run on the (more expensive) primary model. **LLM gateway**: a proxy layer for centralized auth, usage tracking, budgets, and audit logging. The gateway must expose Anthropic Messages (`/v1/messages`), Bedrock InvokeModel, or Vertex rawPredict format and forward `anthropic-beta`/`anthropic-version` headers. Point Claude Code at it with `ANTHROPIC_BASE_URL` (unified) or provider-specific pairs like `ANTHROPIC_BEDROCK_BASE_URL` + `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1`. Auth via `ANTHROPIC_AUTH_TOKEN` (static) or an `apiKeyHelper` script with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` for rotation. Requests carry `X-Claude-Code-Session-Id` and agent-ID headers for per-session/per-subagent cost attribution. ### Deliver managed settings Claude Code checks four sources in priority order and applies the first non-empty one: | Mechanism | Location | Priority | |---|---|---| | Server-managed | Claude.ai admin console (refreshes hourly; Teams/Enterprise only) | Highest | | plist / registry policy | macOS `com.anthropic.claudecode` plist; Windows `HKLM\SOFTWARE\Policies\ClaudeCode` | High | | File-based | macOS `/Library/Application Support/ClaudeCode/managed-settings.json`; Linux/WSL `/etc/claude-code/managed-settings.json`; Windows `C:\Program Files\ClaudeCode\managed-settings.json` | Medium | | Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` (writable without elevation — convenience, not enforcement) | Lowest | Anthropic publishes MDM templates (Jamf/Kandji custom settings, `.mobileconfig`, Intune platform script, Group Policy ADMX) in the claude-code repo's `examples/mdm/`. Verify rollout by having a developer run `/status` and checking the `Enterprise managed settings` line shows `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. WSL reads only `/etc/claude-code` unless `wslInheritsWindowsSettings: true` is set in an admin-only Windows source. ### Decide what to enforce Key control surfaces and their setting keys: permission rules (`permissions.allow`/`deny` — see [[concepts/permissions-security]]); lockdown (`allowManagedPermissionRulesOnly`, `permissions.disableBypassPermissionsMode`); sandboxing (`sandbox.enabled`, `sandbox.network.allowedDomains`); org-wide CLAUDE.md at the managed policy path; MCP restrictions (`allowedMcpServers`, `deniedMcpServers`, `managed-mcp.json` — detailed in [[concepts/mcp-integration]]); marketplace control (`strictKnownMarketplaces`, `blockedMarketplaces` — see [[entities/plugin-marketplaces]]); customization lockdown (`strictPluginOnlyCustomization`); hook restrictions (`allowManagedHooksOnly`, `allowedHttpHookUrls` — see [[concepts/hooks-system]]); `disableAgentView`; version controls (`minimumVersion`, `requiredMinimumVersion`/`requiredMaximumVersion`). Note the layering insight: denying WebFetch doesn't stop `curl` via Bash — sandboxing's OS-level domain allowlist closes that gap. For hardened deployments, the secure-deployment guidance adds isolation (sandbox runtime, Docker, gVisor, VMs — ascending strength/overhead), least privilege (read-only mounts, proxy-injected credentials so the agent never sees keys), and defense in depth against prompt injection. ### Dev containers The Claude Code Dev Container Feature (`ghcr.io/anthropics/devcontainer-features/claude-code:1.0`) installs the CLI into any devcontainer. Persist auth across rebuilds with a volume at `~/.claude` (`source=claude-code-config,target=/home/node/.claude,type=volume`). Bake policy via `COPY managed-settings.json /etc/claude-code/managed-settings.json` in the Dockerfile — but anyone with repo write access can change that, so use server-managed settings or MDM for unbypassable policy. The reference container adds an `init-firewall.sh` egress allowlist (requires `NET_ADMIN`/`NET_RAW`). Containers make `--dangerously-skip-permissions` tolerable for unattended work (rejected when running as root), but a malicious repo can still exfiltrate anything inside the container, including `~/.claude` credentials — don't mount host secrets like `~/.ssh`. ### Usage visibility * **Analytics dashboard** (Anthropic plans only): claude.ai/analytics/claude-code (Teams/Enterprise) shows lines accepted, suggestion accept rate, DAU/sessions, leaderboard, and — with the GitHub app installed — contribution metrics (PRs labeled `claude-code-assisted`, conservative attribution over a 21-days-before/2-after window). Not available with Zero Data Retention. API customers use platform.claude.com/claude-code (spend, team insights). * **OpenTelemetry** (all providers): enable with `CLAUDE_CODE_ENABLE_TELEMETRY=1` plus per-signal exporters `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER` / `OTEL_TRACES_EXPORTER` (traces also need `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`), transported via `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` and `OTEL_EXPORTER_OTLP_ENDPOINT`. Span hierarchy: `claude_code.interaction` > `claude_code.llm_request` / `claude_code.tool` (with `blocked_on_user` and `execution` children) / `claude_code.hook`. Content is excluded by default; opt-in via `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1`, `OTEL_LOG_TOOL_CONTENT=1`, `OTEL_LOG_RAW_API_BODIES`. Tag deployments with `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` (e.g. `enduser.id` for per-user SIEM audit trails). The [[concepts/agent-sdk]] inherits all of this from the environment. ### Data usage and compliance Commercial users (Team, Enterprise, API, Bedrock/Vertex, Claude Gov): Anthropic does **not** train on code or prompts unless explicitly opted in (Development Partner Program, first-party API only). Consumer Free/Pro/Max accounts choose; training-on means 5-year retention, off means 30-day. Commercial standard retention is 30 days; **Zero Data Retention** is available to qualified Enterprise accounts (per-org, enabled by your account team) and is required for BAA (HIPAA) coverage. Local transcripts live in plaintext under `~/.claude/projects/` for 30 days (`cleanupPeriodDays`). `/feedback` transcripts are retained 5 years; opt-in session-transcript shares 6 months. Telemetry knobs: `DISABLE_TELEMETRY`, `DISABLE_ERROR_REPORTING` (Sentry), `DISABLE_FEEDBACK_COMMAND`, `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` for everything at once. On Bedrock/Vertex/Foundry these are off by default already. Exception: the WebFetch domain safety check (hostname-only, sent to `api.anthropic.com`) runs on every provider; disable with `skipWebFetchPreflight: true` in settings. Compliance: OAuth login is exclusively for subscription holders — third-party products must use API keys; vulnerability reports go through HackerOne; certifications live in the Anthropic Trust Center. ## Key Parameters * `CLAUDE_CODE_USE_BEDROCK=1` + `AWS_REGION` (required, not read from `.aws` config) — Bedrock provider; `CLAUDE_CODE_USE_VERTEX=1` + `CLOUD_ML_REGION` + `ANTHROPIC_VERTEX_PROJECT_ID` — Vertex. * `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` — pin fleet models on Bedrock/Vertex so aliases don't drift; append `[1m]` for the 1M-token context window. * `ANTHROPIC_BASE_URL` (or `ANTHROPIC_BEDROCK_BASE_URL` + `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1`) — point at an LLM gateway; auth via `ANTHROPIC_AUTH_TOKEN` or an `apiKeyHelper` script with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`. * `awsAuthRefresh` / `gcpAuthRefresh` — settings keys for SSO/credential refresh commands. * `permissions.allow` / `permissions.deny`, `allowManagedPermissionRulesOnly`, `permissions.disableBypassPermissionsMode` — managed permission policy and lockdown. * `sandbox.enabled`, `sandbox.network.allowedDomains` — OS-level sandboxing that closes the "deny WebFetch but allow `curl`" gap. * `allowedMcpServers` / `deniedMcpServers` and `managed-mcp.json` — MCP restriction surface ([[concepts/mcp-integration]]). * `strictKnownMarketplaces`, `blockedMarketplaces`, `strictPluginOnlyCustomization`, `allowManagedHooksOnly`, `allowedHttpHookUrls` — marketplace, customization, and hook lockdown. * `minimumVersion`, `requiredMinimumVersion` / `requiredMaximumVersion` — fleet version controls; `wslInheritsWindowsSettings: true` lets WSL read Windows managed settings. * `CLAUDE_CODE_ENABLE_TELEMETRY=1` + `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER` / `OTEL_TRACES_EXPORTER` (traces also need `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`), `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES` — OpenTelemetry export and SIEM tagging. * `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1`, `OTEL_LOG_TOOL_CONTENT=1` — opt-in content capture (excluded by default). * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` (or granular `DISABLE_TELEMETRY`, `DISABLE_ERROR_REPORTING`, `DISABLE_FEEDBACK_COMMAND`), `skipWebFetchPreflight: true`, `cleanupPeriodDays` — privacy and retention knobs. ## When To Use Follow the decision order at the top for any rollout beyond a handful of seats. Mixed-provider orgs should configure server-managed settings for Claude.ai users *plus* a file/plist/registry fallback so Bedrock/Vertex users still receive policy. ## Risks & Pitfalls * **Unpinned models on Bedrock/Vertex** drift or fail when defaults change — pin before rollout. * **HKCU registry is not enforcement** — any user can write it. * **Dockerfile-delivered policy is bypassable** by anyone with repo write access. * **Permission rules ≠ network control** — pair deny rules with sandboxing or an egress proxy. * **Silent MCP policy blocks** confuse users (servers vanish from `/mcp` without explanation) — announce restriction rollouts. * **`awsAuthRefresh` + TLS-inspecting proxies** can cause infinite SSO browser loops; remove the setting and run `aws sso login` manually. * **ZDR trade-offs**: no contribution metrics, and analytics show usage only. ## Related Concepts [[concepts/permissions-security]] · [[concepts/mcp-integration]] · [[concepts/hooks-system]] · [[concepts/configuration]] · [[concepts/agent-sdk]] · [[concepts/installation-setup]] · [[syntheses/cost-management]] · [[entities/claude-code-web]] · [[entities/plugin-marketplaces]] ## Sources Admin setup decision map, Bedrock and Vertex provider guides, LLM gateway page, dev containers guide, analytics and OpenTelemetry references, data-usage and legal pages, the secure-deployment guide, and the MDM examples README. --- title: "Hooks System" type: concept tags: [hooks, automation, lifecycle, guardrails, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-automate-actions-with-hooks.md", "raw/llms_txt_doc-hooks-reference.md", "raw/llms_txt_doc-intercept-and-control-agent-behavior-with-hooks.md"] --- ## Definition Hooks are user-defined actions that execute at specific points in Claude Code's lifecycle — before a tool runs, after an edit, when a session starts, when Claude stops. Unlike instructions in CLAUDE.md or a skill, which Claude may or may not follow, hooks are deterministic: they always fire on their event. This makes them the right place for guardrails ("never edit `.env`"), automation (format after every edit), and integration (post to Slack when a session ends). ## How It Works Hooks live in a `hooks` block in a settings file. Each event name keys a list of matcher groups; each group holds one or more hook handlers: ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" } ] } ] } } ``` When an event fires, all matching hooks run **in parallel**; results are merged afterward (for `PreToolUse`, the most restrictive decision wins: `deny` > `defer` > `ask` > `allow`). Browse configured hooks with `/hooks` (read-only — edit settings JSON to change them). Disable everything with `"disableAllHooks": true`. ### Hook events The major lifecycle events (full list of ~30 in the hooks reference): * **Session boundaries**: `SessionStart` (matchers: `startup`, `resume`, `clear`, `compact`), `SessionEnd`, `Setup` (`--init-only` / `--maintenance` runs) * **Prompts**: `UserPromptSubmit`, `UserPromptExpansion` * **Tools**: `PreToolUse` (can block), `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch` * **Turn end**: `Stop` (fires whenever Claude finishes responding), `StopFailure` (API errors) * **Agents and tasks**: `SubagentStart`, `SubagentStop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted` (see [[concepts/subagents-orchestration]]) * **Environment**: `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `InstructionsLoaded` * **Context**: `PreCompact`, `PostCompact`, `Notification` (matchers include `permission_prompt`, `idle_prompt`), `Elicitation`/`ElicitationResult` (MCP) ### Hook types | Type | What it runs | Notes | |---|---|---| | `command` | Shell command | The workhorse; default timeout 10 min; supports `"async": true` and exec form (`"args": []`) | | `http` | POST event JSON to a URL | Header env-var interpolation gated by `allowedEnvVars` | | `mcp_tool` | A tool on a connected MCP server | | | `prompt` | Single-turn LLM evaluation (Haiku default) | Returns `{"ok": true/false, "reason": "..."}`; 30 s timeout | | `agent` | Multi-turn subagent with tool access | Experimental; 60 s default timeout, up to 50 turns | ### Input/output contract (command hooks) Event data arrives as JSON on stdin (`session_id`, `cwd`, `hook_event_name`, plus event-specific fields like `tool_name` and `tool_input`). The exit code decides what happens: * **Exit 0** — no objection; for `UserPromptSubmit` and `SessionStart`, stdout is injected into Claude's context * **Exit 2** — block the action; stderr is fed back to Claude as feedback * **Other** — action proceeds; a hook-error notice appears in the transcript For richer control, exit 0 and print structured JSON: `PreToolUse` supports `permissionDecision` (`allow`/`deny`/`ask`, plus `defer` in `-p` mode) with `permissionDecisionReason`; `PostToolUse` and `Stop` use top-level `decision: "block"`; `PermissionRequest` answers the dialog via `hookSpecificOutput.decision.behavior` and can switch permission modes with `updatedPermissions: [{"type": "setMode", "mode": "acceptEdits", "destination": "session"}]`. Don't mix styles — JSON is ignored when you exit 2. ### Matchers and the `if` field Tool events match on tool name (`Bash`, `Edit|Write`, regex like `mcp__github__.*` for MCP tools); other events match event-specific values (e.g. `SessionStart` matches `compact`). The `if` field (v2.1.85+) filters by tool name *and arguments* using permission-rule syntax, e.g. `"if": "Bash(git *)"` — but it parses best-effort and fails open, so use [[concepts/permissions-security]] rules, not hooks, for hard allow/deny enforcement. ### Where hooks live `~/.claude/settings.json` (all your projects), `.claude/settings.json` (project, committable), `.claude/settings.local.json` (project, gitignored), managed policy settings (org-wide, see [[concepts/enterprise-deployment]]), plugin `hooks/hooks.json`, and skill/agent frontmatter. Hooks from all sources merge — everything registered fires. ## Key Parameters Proven recipes from the docs (verbatim commands): * **Desktop notification** (`Notification` event): `osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'` (macOS), `notify-send 'Claude Code' 'Claude Code needs your attention'` (Linux) * **Block protected files** (`PreToolUse`, `Edit|Write`): script reads `.tool_input.file_path`, exits 2 with a stderr reason for patterns like `.env`, `package-lock.json`, `.git/`; script path referenced as `"$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh` and must be `chmod +x` * **Re-inject context after compaction** (`SessionStart` matcher `compact`): stdout is added to context — pairs with [[concepts/memory-context]] * **direnv-style env reload** (`SessionStart` + `CwdChanged`): `direnv export bash > "$CLAUDE_ENV_FILE"` — Claude runs that file as a preamble before each Bash command * **Auto-approve plan exits** (`PermissionRequest` matcher `ExitPlanMode`): echo an allow decision JSON * **Keep-working evaluator** (`Stop`, `type: "prompt"`): the mechanism behind `/goal` Async hooks: add `"async": true` (command hooks only) to run in the background; output with `additionalContext` is delivered on the next turn, and async hooks can never block since the action already happened. ## When To Use Use a hook when an action must happen the same way every time and doesn't need Claude's judgment: format on save, reject dangerous commands, audit logging, notifications. Use a skill instead when Claude should reason about how to apply steps ([[concepts/skills-system]]). The docs' key dictum: **put guardrails in hooks** — a CLAUDE.md instruction is a request; a `PreToolUse` hook is enforcement. Notably, a `PreToolUse` deny blocks the tool even in `bypassPermissions` mode, while a hook `allow` can never override deny rules from settings: hooks can tighten but not loosen. ## Risks & Pitfalls * **Security**: command hooks run with your full user permissions. Validate inputs, quote shell variables (`"$VAR"`), block `..` path traversal, use absolute paths. * **Bash escapes file matchers**: Claude can modify files via `Bash`, bypassing an `Edit|Write` matcher. For compliance coverage, add a `Stop` hook that scans `git status --porcelain`. * **Stop hook block cap**: after 8 consecutive blocks without progress the Stop hook is overridden; check `stop_hook_active` in input and exit 0 when true, or raise `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`. * **Parallel-hook surprises**: one hook's deny doesn't stop siblings' side effects; multiple hooks returning `updatedInput` race nondeterministically — let only one hook rewrite a given tool's input. * **Shell-profile pollution**: unconditional `echo` in `~/.bashrc` prepends garbage to your hook's JSON ("JSON validation failed"); guard with `if [[ $- == *i* ]]`. * **`PermissionRequest` doesn't fire in `-p` (non-interactive) mode** — use `PreToolUse`. * **Debugging**: `Ctrl+O` transcript shows per-hook summaries; `claude --debug-file /tmp/claude.log` or `/debug` mid-session for full detail. Test scripts by piping sample JSON manually. In the [[concepts/agent-sdk]], hooks are registered as in-process callback functions via `options.hooks` (with `HookMatcher`), alongside any settings-file hooks loaded through `settingSources`. Callbacks can modify tool input, deny calls, and inject context with the same decision vocabulary. ## Related Concepts [[concepts/skills-system]] · [[concepts/permissions-security]] · [[concepts/subagents-orchestration]] · [[concepts/configuration]] · [[concepts/enterprise-deployment]] · [[concepts/agent-sdk]] · [[concepts/memory-context]] ## Sources The hooks guide (recipes, exit-code contract, troubleshooting), the 21k-word hooks reference (event schemas, async hooks, security), and the SDK hooks page (callback model). --- title: "Installation and Setup" type: concept tags: [setup, installation, authentication, onboarding, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/github_doc-readme-md.md", "raw/llms_txt_doc-authentication.md", "raw/llms_txt_doc-quickstart.md", "raw/llms_txt_doc-cli-reference.md"] --- # Installation and Setup ## Definition Installation and setup covers getting the Claude Code CLI onto your machine, launching it for the first time, and authenticating with one of several account types: a Claude Pro/Max subscription, Claude for Teams/Enterprise, the Claude Console (API billing), or a cloud provider (Bedrock, Vertex AI, Microsoft Foundry). ## How It Works ### Install methods by platform Claude Code requires **Node.js 18+**. Install via native installers (recommended) — npm installation is **deprecated**: | Platform | Command | | --- | --- | | macOS/Linux (recommended) | `curl -fsSL https://claude.ai/install.sh | bash` | | Homebrew (macOS/Linux) | `brew install --cask claude-code` | | Windows (recommended) | `irm https://claude.ai/install.ps1 | iex` | | WinGet (Windows) | `winget install Anthropic.ClaudeCode` | | NPM (deprecated) | `npm install -g @anthropic-ai/claude-code` | To pin or reinstall a version, run `claude install [version]` — it accepts a version like `2.1.118`, or `stable` or `latest`. Update later with `claude update`. ### First run and login Navigate to your project directory and run `claude`. On first launch, Claude Code opens a browser window to log in. Two fallbacks matter in practice: - If the browser doesn't open automatically, press `c` to copy the login URL and paste it into a browser. - If the browser shows a login code instead of redirecting back, paste it at the `Paste code here if prompted` prompt. This happens when the browser can't reach Claude Code's local callback server — common in **WSL2, SSH sessions, and containers**. In-session, `/login` and `/logout` switch accounts; from the shell, `claude auth login` (with `--email`, `--sso`, or `--console` for Console/API billing), `claude auth logout`, and `claude auth status` (JSON; `--text` for human-readable; exits 0 if logged in, 1 if not) do the same. ### Authentication options - **Claude Pro or Max subscription**: log in with your Claude.ai account. - **Claude for Teams or Enterprise**: log in with the account your team admin invited you to. Enterprise adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings. - **Claude Console** (API billing): admins invite users via Settings -> Members -> Invite and assign the **Claude Code** role (Claude Code API keys only) or **Developer** role (any API key). - **Cloud providers**: no browser login. Set the provider toggle before running `claude`: `CLAUDE_CODE_USE_BEDROCK=1` (AWS Bedrock), `CLAUDE_CODE_USE_VERTEX=1` (Google Vertex AI), `CLAUDE_CODE_USE_FOUNDRY=1` (Microsoft Azure/Foundry), or `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` plus `ANTHROPIC_AWS_WORKSPACE_ID` (Claude Platform on AWS), then configure the provider's credentials. ### Headless and CI authentication For CI pipelines where browser login isn't available, run `claude setup-token` to generate a one-year OAuth token (requires a Pro, Max, Team, or Enterprise plan). The command prints the token without saving it; export it as `CLAUDE_CODE_OAUTH_TOKEN`. Note: bare mode (`--bare`) does not read `CLAUDE_CODE_OAUTH_TOKEN` — authenticate with `ANTHROPIC_API_KEY` or an `apiKeyHelper` there instead. ### Credential storage - **macOS**: encrypted macOS Keychain. - **Linux**: `~/.claude/.credentials.json` with file mode `0600`. - **Windows**: `%USERPROFILE%\.claude\.credentials.json` (inherits user-profile ACLs). - If `CLAUDE_CONFIG_DIR` is set on Linux/Windows, `.credentials.json` lives under that directory instead. ## Key Parameters **Authentication precedence** when multiple credentials are present: 1. Cloud provider credentials (`CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY`) 2. `ANTHROPIC_AUTH_TOKEN` (sent as `Authorization: Bearer` — for gateways/proxies) 3. `ANTHROPIC_API_KEY` (sent as `X-Api-Key`; in interactive mode you approve it once, in `-p` mode it's always used) 4. `apiKeyHelper` script output (rotating/vault credentials; refreshed every 5 minutes or on HTTP 401; tune with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`) 5. `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`) 6. Subscription OAuth credentials from `/login` (the default for subscription users) `apiKeyHelper`, `ANTHROPIC_API_KEY`, and `ANTHROPIC_AUTH_TOKEN` apply to terminal CLI sessions only — the [[entities/desktop-app]] and cloud sessions use OAuth exclusively. ## When To Use - Individual developer: native installer + Pro/Max subscription login is the fastest path. - Team standardizing on Claude Code: Teams/Enterprise with admin invites; Console for API-metered billing. - Regulated/cloud-locked orgs: Bedrock/Vertex/Foundry env-var setup, distributed via managed settings (see [[concepts/enterprise-deployment]]). - Scripts and CI: `claude setup-token` + `CLAUDE_CODE_OAUTH_TOKEN`, or `ANTHROPIC_API_KEY` (see [[concepts/cli-reference]]). ## Risks & Pitfalls - **A stale `ANTHROPIC_API_KEY` overrides your subscription** once approved. If the key belongs to a disabled or expired org, authentication fails confusingly. Run `unset ANTHROPIC_API_KEY` to fall back to your subscription and check `/status` to confirm which method is active. - npm install still works but is deprecated; prefer native installers so `claude update` and auto-updates work cleanly. - WSL2/SSH/container users should expect the paste-a-code login flow, not the browser redirect. - Anthropic does not allow third-party products to offer claude.ai login; agents built on the SDK must use API key auth (see [[concepts/agent-sdk]]). - Login problems are distinct from configuration problems — for the latter, see [[concepts/configuration]]. ## Related Concepts - [[concepts/configuration]] — settings files and environment variables after install - [[concepts/cli-reference]] — `claude auth`, `claude install`, `claude setup-token` and all flags - [[concepts/enterprise-deployment]] — org-wide rollout, managed settings, cloud providers - [[summaries/casebook-install-auth]] — real-world install/auth failure cases - [[syntheses/troubleshooting-checklist]] — first stops when login or install breaks ## Sources - `raw/github_doc-readme-md.md` — official install commands per platform, Node 18+ requirement - `raw/llms_txt_doc-authentication.md` — login flows, team setup, credential storage, precedence, setup-token - `raw/llms_txt_doc-quickstart.md` — Agent SDK install/auth (API key, cloud provider env vars) - `raw/llms_txt_doc-cli-reference.md` — `claude auth`, `claude install`, `claude update` command reference --- title: "Interactive Mode: The REPL, Slash Commands, and Shortcuts" type: concept tags: [interactive-mode, repl, slash-commands, keyboard-shortcuts, terminal, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-interactive-mode.md", "raw/llms_txt_doc-commands.md", "raw/llms_txt_doc-customize-keyboard-shortcuts.md", "raw/llms_txt_doc-fullscreen-rendering.md"] --- # Interactive Mode: The REPL, Slash Commands, and Shortcuts ## Definition Interactive mode is the terminal REPL you get by running `claude`: a prompt where you converse with Claude, steered by slash commands, keyboard shortcuts, input prefixes (`!` shell mode, `@` file mentions), an optional vim editing mode, and an opt-in fullscreen renderer. ## How It Works ### Slash commands Type `/` to see everything you can invoke — built-in commands, bundled and user-authored skills, plugin and MCP-contributed commands. A command is only recognized at the start of a message; trailing text becomes its arguments. The most-used commands by workflow stage: - **First session in a repo**: `/init` (generate a starter CLAUDE.md), `/memory`, `/mcp`, `/agents`, `/permissions` - **During a task**: `/plan`, `/model`, `/effort`, `/context` (context usage grid), `/compact [instructions]`, `/btw ` (ephemeral side question that never enters history) - **Parallel work**: `/agents`, `/tasks`, `/background` (detach session as a background agent), `/fork`, `/batch` - **Before shipping**: `/diff`, `/code-review [--fix]`, `/review`, `/security-review` - **Between sessions**: `/clear` (fresh context; previous conversation stays in `/resume`), `/resume`, `/branch`, `/rename` - **When something is wrong**: `/rewind` (see [[concepts/checkpointing]]), `/doctor`, `/debug`, `/feedback` (alias `/bug`) - **Environment**: `/config` (settings UI; vim mode lives at `/config` → Editor mode), `/theme`, `/statusline`, `/keybindings`, `/terminal-setup`, `/tui`, `/usage` (aliases `/cost`, `/stats`) Availability varies by platform and plan (e.g. `/desktop` only on macOS/Windows with a subscription). MCP prompts appear as `/mcp____`. ### Keyboard shortcuts worth memorizing | Shortcut | Action | | --- | --- | | `Esc` | Interrupt Claude mid-turn; work so far is kept | | `Esc` + `Esc` | Clear input draft; on an empty prompt, opens the rewind menu | | `Shift+Tab` | Cycle permission modes (`default`, `acceptEdits`, `plan`, plus enabled modes) | | `Ctrl+O` | Toggle transcript viewer (expands collapsed tool/MCP output) | | `Ctrl+R` | Reverse-search command history (`Ctrl+S` cycles scope: session/project/all) | | `Ctrl+B` | Background the running task (tmux users press twice) | | `Ctrl+T` | Toggle the task list | | `Ctrl+G` or `Ctrl+X Ctrl+E` | Edit the prompt in your external editor | | `Ctrl+V` (`Alt+V` on Windows/WSL) | Paste image from clipboard | | `Option+P` / `Alt+P` | Switch model without clearing your prompt | | `Ctrl+L` | Redraw a garbled screen | | `Ctrl+C` / `Ctrl+D` | Interrupt-or-clear / exit (both hardcoded, not rebindable) | Multiline input: `\` + `Enter` anywhere, `Ctrl+J` anywhere, `Shift+Enter` natively in iTerm2/WezTerm/Ghostty/Kitty/Warp/Apple Terminal/Windows Terminal — for VS Code, Cursor, Alacritty, or Zed, run `/terminal-setup` to install the binding. macOS Option-key shortcuts require setting Option as Meta in your terminal. ### Input prefixes and modes - `!` at start enters **shell mode**: the command runs directly without Claude approving or interpreting it, and the command plus output join the conversation context. Tab-completes from previous `!` commands. - `@` triggers file path autocomplete; mentioned files are attached. - **Vim mode** (`/config` → Editor mode) gives NORMAL/INSERT/VISUAL editing with motions, text objects, `.` repeat, and history navigation when `j`/`k` hit the input boundary. ### Custom keybindings Run `/keybindings` to create/open `~/.claude/keybindings.json`. Bindings are grouped by context (`Global`, `Chat`, `Transcript`, `Confirmation`, `Scroll`, ...) mapping keystrokes to `namespace:action` names: ```json { "$schema": "https://www.schemastore.org/claude-code-keybindings.json", "bindings": [ { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+u": null } } ] } ``` Set an action to `null` to unbind; chords use space-separated sequences (`ctrl+x ctrl+k`); a standalone uppercase letter implies Shift. Changes apply without restart, and `/doctor` reports validation warnings. Reserved: `Ctrl+C`, `Ctrl+D`, `Ctrl+M`, Caps Lock. Watch for multiplexer conflicts: `Ctrl+B` (tmux prefix), `Ctrl+A` (GNU screen), `Ctrl+Z` (SIGTSTP). ### Fullscreen rendering A research-preview renderer (v2.1.89+) that draws on the terminal's alternate screen buffer like `vim`: no flicker, flat memory in long conversations, and mouse support (click to expand tool output, click URLs, drag to select with auto-copy, wheel scrolling). Enable with `/tui fullscreen` or `CLAUDE_CODE_NO_FLICKER=1 claude`; disable with `/tui default` or force the classic renderer with `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`. Because the conversation leaves native scrollback, search changes: press `Ctrl+O` for transcript mode, then `/` to search, `[` to dump the conversation into native scrollback (so `Cmd+F`/tmux copy mode work), or `v` to open it in `$VISUAL`/`$EDITOR`. Scroll with `PgUp`/`PgDn`, `Ctrl+Home`/`Ctrl+End`; tune wheel speed with `/scroll-speed` or `CLAUDE_CODE_SCROLL_SPEED`. If mouse capture interferes (SSH, tmux), set `CLAUDE_CODE_DISABLE_MOUSE=1` to keep flicker-free rendering with native selection. In tmux, add `set -g mouse on`; avoid iTerm2's `tmux -CC` integration mode entirely. ## Key Parameters - `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false` — disable the grayed-out predicted prompts (accept with `Tab`/`Right arrow`) - `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` — disable all backgrounding including `Ctrl+B` - `CLAUDE_CODE_TASK_LIST_ID=my-project` — share a task list across sessions via `~/.claude/tasks/` - Keybindings file: `~/.claude/keybindings.json`; vim mode and themes via `/config` ## When To Use Interactive mode is the default for development work — exploration, iteration, review. Switch to `-p` print mode ([[concepts/cli-reference]]) when no human is watching, and to background agents or worktrees ([[concepts/subagents-orchestration]]) when you want parallel sessions. ## Risks & Pitfalls - `Esc Esc` is overloaded: with text in the prompt it clears (recoverable with `Up`); on an empty prompt it opens the rewind menu. - `Shift+Tab` falls back to `Meta+M` on Windows without VT mode (old Node/Bun). - Shell-mode (`!`) output enters context — a huge build log can eat your window; prefer backgrounding noisy commands. - Fullscreen mode breaks muscle memory for `Cmd+F` and terminal copy; learn the `[` scrollback dump before committing to it. - Input history is per working directory and resets on `/clear`. ## Related Concepts - [[concepts/checkpointing]] — the rewind menu behind `Esc Esc` and `/rewind` - [[concepts/cli-reference]] — launch-time flags and print mode - [[concepts/memory-context]] — `/memory`, `/context`, `/compact` - [[concepts/permissions-security]] — the modes `Shift+Tab` cycles through - [[concepts/skills-system]] — adding your own slash commands - [[summaries/best-practices]] — workflow habits built on these controls ## Sources - `raw/llms_txt_doc-interactive-mode.md` — shortcuts, shell mode, history, `/btw`, task list, vim mode - `raw/llms_txt_doc-commands.md` — full command table and workflow grouping - `raw/llms_txt_doc-customize-keyboard-shortcuts.md` — `keybindings.json` format, contexts, actions, reserved keys - `raw/llms_txt_doc-fullscreen-rendering.md` — `/tui fullscreen`, mouse, transcript search, tmux caveats --- title: "MCP Integration" type: concept tags: [mcp, integrations, tools, authentication, foundational, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-connect-claude-code-to-tools-via-mcp.md", "raw/llms_txt_doc-connect-to-mcp-servers.md", "raw/llms_txt_doc-scale-to-many-tools-with-tool-search.md", "raw/llms_txt_doc-control-mcp-server-access-for-your-organization.md", "raw/llms_txt_doc-give-claude-custom-tools.md"] --- ## Definition The Model Context Protocol (MCP) is the open standard Claude Code uses to connect to external tools and data sources — issue trackers, databases, monitoring dashboards, design tools. An MCP server exposes tools, prompts, and resources to Claude; once connected, Claude reads and acts on that system directly instead of working from what you paste into chat. Browse reviewed connectors in the Anthropic Directory (claude.ai/directory). ## How It Works ### Adding servers Four transports, configured with `claude mcp add` from your shell (not inside a session): ```bash # Remote HTTP server (recommended for cloud services) claude mcp add --transport http notion https://mcp.notion.com/mcp claude mcp add --transport http secure-api https://api.example.com/mcp \ --header "Authorization: Bearer your-token" # Local stdio server — `--` separates Claude's flags from the server command claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \ -- npx -y airtable-mcp-server # From JSON claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}' ``` SSE is deprecated (use HTTP); WebSocket (`"type":"ws"`) exists for servers that push events and is configured via `add-json` only. `streamable-http` is accepted as an alias for `http` in JSON configs. Manage with `claude mcp list`, `claude mcp get `, `claude mcp remove `, and the in-session `/mcp` panel (connection status, tool counts, token costs, OAuth). `claude mcp add-from-claude-desktop` imports Claude Desktop servers (macOS/WSL). `claude mcp serve` runs Claude Code itself as an MCP server for other clients. ### Scopes | Scope | Loads in | Shared | Stored in | |---|---|---|---| | `local` (default) | Current project only | No | `~/.claude.json` under the project path | | `project` | Current project only | Yes, via version control | `.mcp.json` in project root | | `user` | All your projects | No | `~/.claude.json` | Pick with `--scope`. Precedence when the same name appears at several levels (whole entry wins, no field merging): local > project > user > plugin-provided > claude.ai connectors. Project-scoped servers require an approval prompt before first use (`claude mcp reset-project-choices` to redo). `.mcp.json` supports `${VAR}` and `${VAR:-default}` expansion in `command`, `args`, `env`, `url`, and `headers`, so teams can commit configs without committing secrets. claude.ai connectors flow into Claude Code automatically when you authenticate with a Claude.ai subscription (not when `ANTHROPIC_API_KEY`, Bedrock, or Vertex is active); disable with `ENABLE_CLAUDEAI_MCP_SERVERS=false`. ### Authentication Remote servers that return 401/403 are flagged in `/mcp` for an OAuth 2.0 browser flow; tokens are stored securely and auto-refreshed. For servers without Dynamic Client Registration, pass `--client-id` and `--client-secret` (prompted, masked) plus `--callback-port 8080` to match a pre-registered `http://localhost:PORT/callback` redirect URI. Other knobs: `oauth.scopes` (space-separated string) pins requested scopes to a security-approved subset; `oauth.authServerMetadataUrl` overrides metadata discovery (v2.1.64+); `headersHelper` runs a script at connect time to generate headers for Kerberos/SSO/short-lived-token schemes (receives `CLAUDE_CODE_MCP_SERVER_NAME` and `CLAUDE_CODE_MCP_SERVER_URL`). ### Tool search at scale Tool search is on by default: only tool names and server instructions load at session start, full schemas are deferred, and Claude discovers the 3–5 most relevant tools on demand via a `ToolSearch` call. Rationale: 50 tools can consume 10–20K tokens, and selection accuracy degrades past 30–50 loaded tools. Control with `ENABLE_TOOL_SEARCH`: unset (deferred, with fallbacks), `true` (force), `auto` (load upfront if under 10% of context), `auto:N` (custom threshold), `false` (all upfront). Not supported on Haiku; disabled by default on Vertex AI (supported there only on Sonnet 4.5+ / Opus 4.5+) and behind non-first-party `ANTHROPIC_BASE_URL` proxies. Per-server exemption: `"alwaysLoad": true` in the server entry (v2.1.121+); per-tool: `"anthropic/alwaysLoad": true` in the tool's `_meta`. Output limits: a warning fires above 10,000 tokens of tool output; the default cap is 25,000, raised via `MAX_MCP_OUTPUT_TOKENS`. Server authors can annotate a tool with `_meta["anthropic/maxResultSizeChars"]` (up to 500,000 chars). Startup/connection knobs: `MCP_TIMEOUT` (server startup), `MCP_TOOL_TIMEOUT` or a per-server `"timeout"` field in ms (tool execution); HTTP/SSE servers auto-reconnect with exponential backoff (5 attempts). ### Beyond tools: prompts, resources, channels * **MCP prompts** appear as commands: `/mcp__github__pr_review 456`. * **MCP resources** are @-mentionable: `@github:issue://123`, fuzzy-searchable in autocomplete. * **Elicitation**: servers can request structured input mid-task via a form or browser dialog; auto-respond with an `Elicitation` hook ([[concepts/hooks-system]]). * **Channels**: a server declaring the `claude/channel` capability can push external events (CI results, chat messages) into a running session when started with `--channels`. ### Org-level control Admins choose a restriction pattern (full details in [[concepts/enterprise-deployment]]): * **Exclusive control**: deploy `managed-mcp.json` (same format as `.mcp.json`) at `/Library/Application Support/ClaudeCode/managed-mcp.json` (macOS), `/etc/claude-code/managed-mcp.json` (Linux/WSL), or `C:\Program Files\ClaudeCode\managed-mcp.json` (Windows). Only those servers load; `claude mcp add` fails with an enterprise-policy error. An empty `{"mcpServers": {}}` disables MCP entirely. `"allowAllClaudeAiMcps": true` in managed settings re-admits claude.ai connectors (v2.1.149+). * **Allowlist/denylist**: `allowedMcpServers` / `deniedMcpServers` entries match by `serverUrl` (wildcards allowed), `serverCommand` (exact argv match), or `serverName` (exact, *not* a security control — users pick names). Denylist always wins and merges from every source; set `allowManagedMcpServersOnly: true` in managed settings to make the managed allowlist authoritative. Once any `serverUrl` entry exists, every remote server must match a URL pattern (same for `serverCommand` and stdio servers). * **Monitoring**: with OpenTelemetry export, `OTEL_LOG_TOOL_DETAILS=1` records which MCP servers and tools users invoke. ### Custom tools in the SDK The [[concepts/agent-sdk]] can define tools in-process without an external server: define with `tool()` (TypeScript, Zod schema) or `@tool` (Python), bundle with `createSdkMcpServer` / `create_sdk_mcp_server`, and pass via `mcpServers` in `query()`. Handlers return `content` blocks (text, image, resource), optional `structuredContent`, and `isError: true` for recoverable failures. Set `readOnlyHint: true` so Claude can parallelize side-effect-free tools. MCP tool names follow `mcp____`; pre-approve a whole server with a wildcard like `mcp__enterprise-tools__*` in `allowedTools`. ## Key Parameters * `claude mcp add --transport http|stdio` with `--header` (HTTP auth) or `--env KEY=value` (stdio) — and `--` to separate the server command's flags from Claude's. * `--scope local|project|user` — where the server config lives (`~/.claude.json` vs committed `.mcp.json`); precedence local > project > user > plugin > claude.ai connectors. * `${VAR}` / `${VAR:-default}` expansion in `.mcp.json` (`command`, `args`, `env`, `url`, `headers`) — commit configs without secrets. * `--client-id` / `--client-secret` / `--callback-port`, plus `oauth.scopes` and `oauth.authServerMetadataUrl` — OAuth for servers without Dynamic Client Registration; `headersHelper` scripts generate headers for Kerberos/SSO schemes. * `ENABLE_TOOL_SEARCH` — `true` / `auto` / `auto:N` / `false`; controls deferred tool loading (on by default, off on Haiku and by default on Vertex). * `"alwaysLoad": true` per server (v2.1.121+) or `"anthropic/alwaysLoad": true` in a tool's `_meta` — exempt from tool search deferral. * `MAX_MCP_OUTPUT_TOKENS` — raise the 25,000-token output cap; servers can set `_meta["anthropic/maxResultSizeChars"]` (up to 500,000). * `MCP_TIMEOUT` (server startup), `MCP_TOOL_TIMEOUT` or per-server `"timeout"` in ms (tool execution). * `ENABLE_CLAUDEAI_MCP_SERVERS=false` — stop claude.ai connectors from flowing into Claude Code. * `allowedMcpServers` / `deniedMcpServers` (match on `serverUrl`, `serverCommand`, or `serverName`), `allowManagedMcpServersOnly: true`, `managed-mcp.json`, `"allowAllClaudeAiMcps": true` — org-level control. * `mcp____` naming — pre-approve a whole server in `allowedTools` with a wildcard like `mcp__enterprise-tools__*`. ## When To Use Connect a server when you keep copying data into chat from another tool. Use HTTP transport for hosted services, stdio for local system access, project scope for team-shared servers, user scope for personal cross-project utilities. Pair MCP with a skill that documents schemas and usage patterns ([[concepts/skills-system]]) — MCP provides the connection, the skill the know-how. ## Risks & Pitfalls * **Prompt injection**: verify you trust each server; servers that fetch external content can carry injected instructions. Anthropic reviews Directory listings but doesn't security-audit servers. See [[concepts/permissions-security]]. * **stdio flag parsing**: forgetting `--` makes Claude Code parse the server's flags as its own; also keep another option between `--env KEY=value` and the server name or the name is read as another pair. * **Silent policy blocks**: a previously configured server blocked by new org policy just disappears from `/mcp` with no warning — tell users when rolling out restrictions. * **Auth header vs OAuth**: if a configured `headers.Authorization` is rejected, the connection fails rather than falling back to OAuth — remove the header to use the OAuth flow. * **Reserved name**: `workspace` is reserved; a server with that name is skipped. * **Missing env vars**: an unexpanded `${VAR}` with no default makes the whole config fail to parse. ## Related Concepts [[concepts/enterprise-deployment]] · [[concepts/hooks-system]] · [[concepts/skills-system]] · [[concepts/agent-sdk]] · [[concepts/permissions-security]] · [[concepts/configuration]] · [[entities/plugin-marketplaces]] · [[entities/desktop-app]] ## Sources Full MCP reference, the step-by-step connect guide, the tool-search page (SDK variant), the managed-MCP org-control page, and the SDK custom-tools guide. --- title: "Memory and Context: CLAUDE.md, Auto Memory, and the Context Window" type: concept tags: [memory, claude-md, context-window, compaction, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-how-claude-remembers-your-project.md", "raw/llms_txt_doc-explore-the-context-window.md", "raw/llms_txt_doc-how-claude-code-works.md"] --- # Memory and Context: CLAUDE.md, Auto Memory, and the Context Window ## Definition Every Claude Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions: **CLAUDE.md files** (instructions you write) and **auto memory** (notes Claude writes itself). Inside a session, the context window holds your conversation, file reads, tool output, and startup content — and is managed via `/context`, `/compact`, `/clear`, and automatic compaction. ## How It Works ### CLAUDE.md file locations and load order | Scope | Location | Shared with | | --- | --- | --- | | Managed policy | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` · Linux/WSL: `/etc/claude-code/CLAUDE.md` · Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | All users in org (cannot be excluded) | | User instructions | `~/.claude/CLAUDE.md` | Just you, all projects | | Project instructions | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team via source control | | Local instructions | `./CLAUDE.local.md` (gitignore it) | Just you, current project | Claude walks **up** the directory tree from your working directory, loading every `CLAUDE.md`/`CLAUDE.local.md` it finds; all files are concatenated (root-most first, working directory last, `CLAUDE.local.md` after `CLAUDE.md` at each level). Files in **subdirectories** load on demand — when Claude reads a file in that directory — not at launch. Block-level HTML comments are stripped before injection, so use them for maintainer notes. Run `/init` to generate a starting CLAUDE.md (it reads existing `AGENTS.md`, `.cursorrules`, etc.); for repos using `AGENTS.md`, a one-line CLAUDE.md containing `@AGENTS.md` imports it. Imports use `@path/to/import` syntax, resolve relative to the importing file, and recurse up to four hops — but imported files still load at launch, so imports organize content without saving context. ### Rules: `.claude/rules/` For larger projects, split instructions into topic files under `.claude/rules/` (discovered recursively; `~/.claude/rules/` for personal cross-project rules, loaded before project rules). Rules can be scoped with YAML frontmatter: ```markdown --- paths: - "src/api/**/*.ts" --- # API Development Rules - All API endpoints must include input validation ``` Path-scoped rules load only when Claude reads a matching file; unscoped rules load at launch like `.claude/CLAUDE.md`. Symlinks are supported for sharing rules across projects. In monorepos, `claudeMdExcludes` (glob patterns against absolute paths, any settings layer) skips other teams' files. ### Auto memory Auto memory (on by default, v2.1.59+) lets Claude save its own notes — build commands, debugging insights, preferences — to `~/.claude/projects//memory/`, shared across worktrees of the same repo. `MEMORY.md` is the index: its **first 200 lines or 25KB** load at session start; topic files (`debugging.md`, etc.) are read on demand. Everything is plain markdown you can audit via `/memory`. Toggle with `autoMemoryEnabled` in settings or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`; relocate with `autoMemoryDirectory`. Saying "remember that X" saves to auto memory; "add this to CLAUDE.md" edits the file. ### The context window and compaction Startup content includes the system prompt, CLAUDE.md files, auto memory, MCP tool names, and skill descriptions; each file read, rule trigger, and hook output adds more as Claude works. Run `/context` for a live breakdown and `/memory` to verify what loaded. As the window approaches its limit (~95% by default, tunable with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`), Claude Code compacts automatically: older tool outputs are cleared first, then the conversation is summarized. What survives: | Mechanism | After compaction | | --- | --- | | System prompt and output style | Unchanged | | Project-root CLAUDE.md and unscoped rules | Re-injected from disk | | Auto memory | Re-injected from disk | | Rules with `paths:` frontmatter | Lost until a matching file is read again | | Nested CLAUDE.md in subdirectories | Lost until a file there is read again | | Invoked skill bodies | Re-injected, capped at 5,000 tokens/skill, 25,000 total | | Hooks | Not applicable — hooks run as code, not context | Act before auto-compaction when you can: `/compact focus on the auth bug fix` keeps what you choose; `/clear` between unrelated tasks; delegate large reads to a [[concepts/subagents-orchestration]] subagent, which keeps file contents in its own context window and returns only a summary. Fable 5, Opus 4.6+, and Sonnet 4.6 support a 1M-token window (`[1m]` variants). ## Key Parameters - Size target: **under 200 lines per CLAUDE.md** — longer files reduce adherence - Specificity: "Use 2-space indentation" beats "Format code properly"; "Run `npm test` before committing" beats "Test your changes" - `MEMORY.md` load cap: first 200 lines or 25KB - `claudeMdExcludes`, `autoMemoryEnabled`, `autoMemoryDirectory` settings keys; `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`, `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` (load memory from `--add-dir` directories) env vars - Managed `claudeMd` settings key embeds org CLAUDE.md content directly in `managed-settings.json` (managed/policy scope only) ## When To Use - Claude makes the same mistake twice, or you retype the same correction → add it to CLAUDE.md. - Multi-step procedures or area-specific guidance → a skill ([[concepts/skills-system]]) or path-scoped rule, not CLAUDE.md. - Anything that must *never* happen → permissions or hooks ([[concepts/permissions-security]], [[concepts/hooks-system]]); CLAUDE.md is guidance, not enforcement. - Org-wide coding standards → managed CLAUDE.md; technical enforcement → managed settings. ## Risks & Pitfalls - CLAUDE.md is delivered as a user message after the system prompt — there's no guarantee of strict compliance, especially for vague or conflicting instructions. Two contradictory rules mean Claude may pick one arbitrarily. - "Instructions lost after `/compact`" usually means they were conversation-only or in a nested CLAUDE.md; move persistent rules to the project root. - Subdirectory CLAUDE.md files don't load at launch and don't trigger on writes — only when Claude *reads* a file there. - Built-in Explore and Plan subagents skip CLAUDE.md entirely; restate critical instructions in the delegating prompt. - If one giant file/tool output refills context immediately after each summary, auto-compaction stops with a thrashing error rather than looping. ## Related Concepts - [[concepts/configuration]] — settings layers that hold memory-related keys - [[concepts/skills-system]] — on-demand instructions vs always-loaded memory - [[concepts/subagents-orchestration]] — context isolation for large reads - [[concepts/hooks-system]] — enforcement that survives any compaction - [[concepts/checkpointing]] — rewind/summarize as targeted context surgery - [[syntheses/cost-management]] — context size drives token spend ## Sources - `raw/llms_txt_doc-how-claude-remembers-your-project.md` — CLAUDE.md locations, rules, imports, auto memory, troubleshooting - `raw/llms_txt_doc-explore-the-context-window.md` — startup loads, compaction survival table, mitigation strategies - `raw/llms_txt_doc-how-claude-code-works.md` — agentic loop, session storage, when context fills up --- title: "Permissions and Security Model" type: concept tags: [permissions, security, auto-mode, sandboxing, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-configure-permissions.md", "raw/llms_txt_doc-configure-auto-mode.md", "raw/github_doc-security-md.md", "raw/llms_txt_doc-handle-approvals-and-user-input.md", "raw/github_doc-examples-settings-readme-md.md"] --- # Permissions and Security Model ## Definition Claude Code's security model layers **permission modes** (session-wide posture), **allow/ask/deny rules** (pattern-matched per tool call), **hooks** (custom code gates), an optional **auto-mode classifier** (model-based approval), and **sandboxing** for the Bash tool. Unlike CLAUDE.md guidance, these are enforced by the client regardless of what the model decides. ## How It Works ### Evaluation order When Claude requests a tool, permissions are checked in this order: 1. **Hooks** — can deny outright or pass on; an `allow` from a hook does not skip the deny/ask rules below 2. **Deny rules** — if matched, blocked **even in `bypassPermissions` mode**. A bare-name deny (`Bash`) removes the tool from Claude's context entirely; a scoped rule (`Bash(rm *)`) leaves the tool available and denies only matching calls 3. **Ask rules** — force a prompt even in `bypassPermissions`; in `dontAsk` mode a matching ask rule is denied instead 4. **Permission mode** — `bypassPermissions` approves everything reaching this step; `acceptEdits` approves file operations; `plan` routes write operations to a prompt regardless of allow rules 5. **Allow rules** — matched tools are approved 6. **Prompt the user** — interactively in the terminal, or via the `canUseTool` callback in the SDK; skipped (denied) in `dontAsk` mode ### Permission modes Cycle modes with `Shift+Tab` or start with `--permission-mode `: | Mode | Behavior | Use case | | --- | --- | --- | | `default` | No auto-approvals; unmatched tools prompt | Standard interactive work | | `acceptEdits` | Auto-approves file edits (Edit, Write) and filesystem commands (`mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`) inside the working directory and `additionalDirectories` | Trusted iteration, prototyping | | `plan` | Read-only exploration; file edits never auto-approved, even by allow rules | Review before changes | | `dontAsk` | Anything not pre-approved is denied without prompting | Locked-down headless agents | | `auto` | A model classifier approves or denies each call, blocking irreversible/destructive/external actions | Autonomous work with guardrails (research preview) | | `bypassPermissions` | Everything approved unless a deny/ask rule or hook blocks it | Sandboxed CI, fully trusted environments only | **Subagent inheritance warning**: when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`, all subagents inherit that mode and can't be overridden per subagent. ### Rule syntax and where rules live Rules go in `permissions.allow` / `permissions.ask` / `permissions.deny` in any settings scope ([[concepts/configuration]]), or per-invocation via `--allowedTools` / `--disallowedTools`. Bash rules use literal prefix matching: `Bash(git log *)` allows anything starting with `git log`. Allow rules accept MCP tool globs only with a literal server prefix (`mcp__puppeteer__*`); an unanchored `allow: ["*"]` is ignored with a warning. Manage interactively with `/permissions`, which also shows recently denied actions. ### Auto mode configuration The auto-mode classifier reads your CLAUDE.md (so "never force push" steers both Claude and the classifier) plus an `autoMode` settings block from user settings, `.claude/settings.local.json`, managed settings, or `--settings` — deliberately **not** from shared project settings, so a checked-in repo can't inject its own allow rules. Out of the box it trusts only the working directory and the repo's configured remotes; tell it about your infrastructure: ```json { "autoMode": { "environment": [ "$defaults", "Source control: github.example.com/acme-corp and all repos under it", "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets", "Trusted internal domains: *.corp.example.com, api.internal.example.com" ] } } ``` Entries are prose, not regex. Three more arrays override the built-in rule lists — `hard_deny` (unconditional), `soft_deny` (user intent or `allow` exceptions can clear), `allow` (exceptions) — with precedence hard_deny → soft_deny → allow → explicit user intent ("force-push this branch" authorizes a force push; "clean up the repo" does not). **Always include the literal string `"$defaults"`** unless you intend to replace the entire built-in list: a `soft_deny` without it discards the built-in force-push, `curl | bash`, and production-deploy blocks. Inspect with `claude auto-mode defaults`, `claude auto-mode config`, and `claude auto-mode critique`; denied calls appear in `/permissions` under Recently denied (press `r` to let Claude retry). ### Sandboxing and enterprise hardening The `sandbox` settings property forces the Bash tool to run inside a sandbox; it applies **only to Bash**, not to Read/Write/WebSearch/WebFetch/MCP tools, hooks, or internal commands. Anthropic's example managed settings show common postures: disabling `--dangerously-skip-permissions`, blocking plugin marketplaces, blocking user/project-defined permission rules (`allowManagedPermissionRulesOnly`) and hooks (`allowManagedHooksOnly`), denying web tools, and requiring Bash approval or sandboxing. Toggle the sandbox interactively with `/sandbox` on supported platforms. ### Approvals in the SDK In the [[concepts/agent-sdk]], unresolved tool requests fire a `canUseTool` callback with the tool name and input (e.g. `command` for Bash, `file_path`/`content` for Write); return an allow (optionally with modified input) or deny (with a message Claude sees). The callback can stay pending indefinitely; for long human approval loops, return a `defer` hook decision so the process can exit and resume later. ### Vulnerability reporting Anthropic runs its security program on HackerOne; validated Claude Code vulnerabilities should be reported through the HackerOne submission form, with bounty guidelines on the Anthropic HackerOne program page. ## Key Parameters - `--permission-mode`, `--allowedTools`, `--disallowedTools`, `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions` (adds bypass to the `Shift+Tab` cycle without starting in it) - `permissions.allow` / `ask` / `deny` / `additionalDirectories` settings keys - `autoMode.environment` / `allow` / `soft_deny` / `hard_deny` with `"$defaults"` - `CLAUDE_CODE_ENABLE_AUTO_MODE` — required to enable auto mode on Bedrock, Vertex AI, or Foundry ## When To Use - Day-to-day: `default`, escalating to `acceptEdits` once you trust the direction; see [[syntheses/permission-mode-picker]]. - Repeated prompts for safe commands: add `permissions.allow` rules (e.g. `Bash(npm test *)`) rather than reaching for bypass. - Org policy: managed-settings `permissions.deny` — it blocks before the classifier and cannot be overridden. - Autonomous long runs: `auto` mode with a populated `autoMode.environment`. ## Risks & Pitfalls - **`allowedTools` does not constrain `bypassPermissions`** — every tool is approved, not just the listed ones. Use deny rules for must-not-run tools. - Prefix deny rules match the literal command string: `Bash(rm *)` does not block `/bin/rm` or `find -delete`. For hard guarantees use a PreToolUse hook ([[concepts/hooks-system]]) or the sandbox. - Auto-mode `allow` entries are additive across scopes: a developer's personal allow can override an org `soft_deny`. Only managed `permissions.deny` and `hard_deny` are firm. - Replacing default classifier lists by omitting `"$defaults"` silently drops built-in exfiltration and destructive-action protections. - Checkpoints don't undo external side effects (databases, deploys) — which is exactly why permission prompts exist; see [[concepts/checkpointing]]. ## Related Concepts - [[syntheses/permission-mode-picker]] — decision guide across modes - [[concepts/hooks-system]] — programmatic gates evaluated before rules - [[concepts/configuration]] — settings scopes that carry permission rules - [[concepts/enterprise-deployment]] — managed settings and MDM distribution - [[concepts/cli-reference]] — permission flags for headless runs ## Sources - `raw/llms_txt_doc-configure-permissions.md` — evaluation order, modes, allow/deny semantics, subagent inheritance - `raw/llms_txt_doc-configure-auto-mode.md` — `autoMode` block, `"$defaults"`, CLI subcommands, denial review - `raw/llms_txt_doc-handle-approvals-and-user-input.md` — `canUseTool` callback contract - `raw/github_doc-security-md.md` — HackerOne vulnerability reporting - `raw/github_doc-examples-settings-readme-md.md` — enterprise hardening examples, Bash-only sandbox scope --- title: "Skills System" type: concept tags: [extension, skills, customization, foundational, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-agent-skills-in-the-sdk.md", "raw/llms_txt_doc-extend-claude-code.md", "raw/llms_txt_doc-commands.md", "raw/github_doc-plugins-frontend-design-skills-frontend-design-skill-md.md"] --- ## Definition A skill is a markdown file containing knowledge, workflows, or instructions that extends what Claude Code can do. Skills are the most flexible extension mechanism: you can invoke one explicitly with a slash command like `/deploy`, or Claude can load it automatically when its description matches your task. Skills can be reference material (an API style guide) or action workflows (a deployment checklist), and they can run in your current conversation or in an isolated context via subagents. ## How It Works Skills are packaged as directories containing a `SKILL.md` file with YAML frontmatter and Markdown content. The `description` field determines when Claude invokes the skill autonomously. ```bash .claude/skills/processing-pdfs/ └── SKILL.md ``` A real `SKILL.md` from Anthropic's frontend-design plugin starts like this: ```yaml --- name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. --- ``` The markdown body below the frontmatter holds the actual instructions Claude follows when the skill loads. ### Where skills live | Location | Scope | |---|---| | `.claude/skills/` (project) | Shared with your team via git | | `~/.claude/skills/` (user) | Personal skills across all projects | | Plugin skills | Bundled with installed plugins, namespaced as `/my-plugin:review` | When the same skill name exists at multiple levels, one definition wins by priority: managed > user > project. ### How loading works (context cost) By default, skill *descriptions* load at session start so Claude can decide when to use them; full content loads only when the skill is used. Set `disable-model-invocation: true` in a skill's frontmatter to hide it from Claude entirely until you invoke it manually — zero context cost, and it guarantees only you trigger it (recommended for skills with side effects). For a skill you didn't write, set `skillOverrides` in settings instead of editing its file. In subagents the behavior differs: skills listed in a subagent's `skills:` frontmatter field are fully preloaded into its context at launch, and the subagent can still discover unlisted skills through the Skill tool. A skill can also run in isolated context itself using `context: fork` in its frontmatter. ### Invoking skills * **You invoke**: type `/` (e.g. `/deploy`). Text after the command name is passed as arguments. Type `/` alone to see every available command and skill. * **Claude invokes**: Claude matches your task against skill descriptions. If descriptions are vague or overlapping, Claude may load the wrong skill or miss one — write specific descriptions with relevant keywords. Useful management commands (verbatim): * `/skills` — list available skills; press `t` to sort by token count, `Space` to hide a skill, `Enter` to save * `/reload-skills` — re-scan skill directories so skills added on disk mid-session become available without restarting (v2.1.152+) * `/usage` — includes a usage breakdown by skill on paid plans ### Bundled skills Claude Code ships skills that work out of the box, marked as skills in the [[concepts/cli-reference]] command table: `/code-review`, `/batch`, `/debug`, `/simplify`, `/verify`, `/run`, `/run-skill-generator`, `/loop`, `/claude-api`, and `/fewer-permission-prompts`. They behave like skills you write yourself: a prompt handed to Claude, which Claude can also invoke automatically when relevant. ## Key Parameters Frontmatter fields that appear across the sources: * `name` — the skill's name; invocation matches this or the directory name. Plugin skills use `plugin:skill` form. * `description` — drives automatic invocation; the most important field to get right. * `disable-model-invocation: true` — user-only invocation, zero idle context cost. * `context: fork` — run the skill in isolated context like a subagent. * `allowed-tools` — restrict tool access; only honored by the Claude Code CLI, **not** by the Agent SDK (use the SDK's `allowedTools` option there). In the [[concepts/agent-sdk]], the `skills` option on `query()` filters which discovered skills are available: `"all"`, a list of names, or `[]` to disable all. Skills are discovered through `settingSources`/`setting_sources` (`"user"` and/or `"project"`); the SDK has no programmatic API for registering skills — they must exist on the filesystem. Note the `skills` option is a context filter, not a sandbox: unlisted skills are hidden from the model but their files remain readable on disk. ## When To Use Use the trigger-based rule from the docs: save a skill when you keep typing the same prompt to start a task, or when you paste the same playbook into chat for the third time. Compared to alternatives: * **CLAUDE.md vs skill**: CLAUDE.md loads every session — use it for "always do X" rules and keep it under 200 lines. Skills load on demand — use them for reference material and invocable workflows. See [[concepts/memory-context]]. * **Hook vs skill**: a hook fires deterministically on a lifecycle event; a skill is interpreted by Claude and the outcome can vary. Put guardrails in hooks, reasoning workflows in skills. See [[concepts/hooks-system]]. * **Subagent vs skill**: skills share content into a context; subagents isolate work in a separate context. They combine — a subagent can preload skills, and an `/audit` skill can spawn subagents. See [[concepts/subagents-orchestration]]. * **MCP vs skill**: MCP provides the connection to an external system; a skill teaches Claude how to use it well (schema, query patterns). See [[concepts/mcp-integration]]. Package skills into a plugin when a second repository needs the same setup, and distribute via [[entities/plugin-marketplaces]]. ## Risks & Pitfalls * **Skill not triggering**: the usual cause is a vague description. Verify the file exists (`ls .claude/skills/*/SKILL.md` or `ls ~/.claude/skills/*/SKILL.md`) and that the name is spelled correctly when invoking. * **Too many skills add noise**: every model-invocable skill's description loads each request; vague or overlapping descriptions make Claude load the wrong one. Hide self-trigger-only skills with `disable-model-invocation: true`. * **SDK gotcha**: `allowed-tools` in SKILL.md is ignored by the SDK; if you pass an explicit `tools` list in the SDK, include `"Skill"` or Claude can't invoke skills at all. * **Skills load at session start**: skills added mid-session need `/reload-skills` (or a restart on older versions). ## Related Concepts [[concepts/subagents-orchestration]] · [[concepts/hooks-system]] · [[concepts/mcp-integration]] · [[concepts/memory-context]] · [[concepts/agent-sdk]] · [[syntheses/extension-decision-guide]] · [[entities/plugin-marketplaces]] ## Sources The dedicated `/en/skills` page is not in the raw set; this page draws on the SDK skills doc, the extension overview, the commands reference, and a real plugin SKILL.md. Detailed authoring guidance (multi-file skills, naming conventions) lives in Anthropic's platform-level Agent Skills docs, referenced but not captured in raw. --- title: "Subagents and Orchestration" type: concept tags: [subagents, parallelism, orchestration, agent-view, agent-teams, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-run-agents-in-parallel.md", "raw/llms_txt_doc-subagents-in-the-sdk.md", "raw/llms_txt_doc-manage-multiple-agents-with-agent-view.md", "raw/llms_txt_doc-orchestrate-teams-of-claude-code-sessions.md", "raw/llms_txt_doc-keep-claude-working-toward-a-goal.md", "raw/llms_txt_doc-todo-lists.md", "raw/llms_txt_doc-extend-claude-code.md"] --- ## Definition Claude Code can run more than one agent at a time through four distinct mechanisms: **subagents** (delegated workers inside one session), **agent view** (a dashboard for background sessions, opened with `claude agents`), **agent teams** (multiple coordinated sessions with shared tasks and messaging, experimental), and **dynamic workflows** (a script that fans work out to many subagents). The right one depends on who coordinates the work, whether workers need to talk to each other, and whether they edit the same files. ## How It Works ### Subagents: isolated workers inside a session A subagent runs its own agentic loop in a fresh context window and returns only its final message to the parent. Intermediate tool calls, file reads, and search results stay inside the subagent — this is the core benefit (context isolation), alongside parallelization, specialized instructions, and tool restrictions (e.g. a read-only reviewer limited to `Read`, `Grep`, `Glob`). Subagents are defined three ways: as markdown files in `.claude/agents/` directories, programmatically via the SDK's `agents` parameter (see [[concepts/agent-sdk]]), or not at all — Claude can always invoke the built-in `general-purpose` subagent via the Agent tool. Scope precedence when names collide: managed > CLI flag > project > user > plugin. What a subagent inherits: its own system prompt, the Agent tool's prompt string, project CLAUDE.md, and tool definitions. What it does **not** inherit: the parent's conversation history, the parent's system prompt, or skill content unless listed in its `skills:` field. The prompt string is the only channel from parent to subagent, so include file paths, error messages, and decisions directly in it. (The built-in Explore and Plan agents omit even CLAUDE.md and git status.) Key facts: * Subagents cannot spawn their own subagents. * `/agents` opens the manager (Running tab for live subagents, Library tab to create/edit). `/tasks` lists everything running in the background of the current session. * `/fork ` (v2.1.161+) spawns a *forked subagent* that inherits the full conversation and works in the background while you continue. * Subagent transcripts persist separately from the main conversation, survive compaction, and can be resumed (the Agent tool result contains `agentId: `); cleanup follows `cleanupPeriodDays` (default 30 days). * Filesystem agents load at startup only — restart the session after adding one. * A subagent can get its own git worktree with `isolation: worktree` in its frontmatter. ### Agent view: dispatch and monitor background sessions `claude agents` opens a full-terminal dashboard of every background session (research preview, v2.1.139+). Each row shows state (Working, Needs input, Idle, Completed, Failed, Stopped), a Haiku-generated one-line summary, and PR status when the session opened a pull request. Core loop: type a prompt and press `Enter` to dispatch a new session, `Space` to peek and reply without attaching, `Enter`/`→` to attach to the full conversation, `←` on an empty prompt to detach. Dispatching options (verbatim): ```bash claude agents # open agent view claude --bg "investigate the flaky test" # dispatch from shell claude --agent code-reviewer --bg "address review comments on PR 1234" claude attach | claude logs | claude stop | claude rm ``` Inside a session, `/background` (alias `/bg`) detaches it to keep running in the background. Background sessions are hosted by a per-user supervisor process — they keep running when you close the terminal, survive sleep, and persist state under `~/.claude/jobs//`. Before editing files, Claude moves each background session into an isolated git worktree under `.claude/worktrees/` (disable with `"worktree": {"bgIsolation": "none"}` in `.claude/settings.json`). Dispatch defaults can be set with `claude agents --permission-mode plan --model opus --effort high`. Turn agent view off entirely with the `disableAgentView` setting or `CLAUDE_CODE_DISABLE_AGENT_VIEW`. ### Agent teams: coordinated peer sessions (experimental) Agent teams are disabled by default; enable with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in env or settings.json (requires v2.1.32+). One session is the team lead; teammates are full independent Claude Code sessions that share a task list (with dependencies and file-locked claiming) and message each other through a mailbox. You ask for a team in natural language; the lead spawns teammates, assigns tasks, and synthesizes results. Use Shift+Down to cycle through teammates in-process, or split panes via tmux/iTerm2 (`teammateMode` setting, `--teammate-mode` flag). State lives in `~/.claude/teams/{team-name}/config.json` and `~/.claude/tasks/{team-name}/`, both removed at cleanup. Teammates load CLAUDE.md, MCP servers, and skills like a normal session but not the lead's history. Hooks can enforce quality gates: `TeammateIdle`, `TaskCreated`, and `TaskCompleted` block with exit code 2 (see [[concepts/hooks-system]]). ### Choosing between them | Approach | Coordination | Communication | Token cost | |---|---|---|---| | Subagents | Claude delegates inside one conversation | Report back to caller only | Lower — summaries return | | Agent view | You hand off independent tasks | Sessions report only to you | Per-session quota | | Agent teams | Lead plans, assigns, supervises | Teammates message each other | Highest — each teammate is a full instance | | Dynamic workflows | A script holds the plan | Results cross-checked by the script | Scales to dozens–hundreds of agents | `/batch` is a packaged combination, not a fifth style: it splits one large change into 5–30 worktree-isolated subagents that each open a PR. Worktrees underpin all of this by giving each writer its own checkout. ### Keeping a session working: /goal and task lists `/goal ` (v2.1.139+) sets a completion condition; after each turn a small fast model (default Haiku) judges whether the condition holds and Claude keeps going until it does. It is a wrapper around a session-scoped prompt-based Stop hook. Write conditions with one measurable end state and a stated check ("`npm test` exits 0"), up to 4,000 characters; bound runaway goals with a clause like `or stop after 20 turns`. `/goal clear` cancels; works non-interactively via `claude -p "/goal ..."`. Compare: `/loop` re-runs on a time interval, a Stop hook applies your own logic, auto mode only approves tools within a turn. For task tracking, sessions use structured Task tools (`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`) as of v2.1.142, replacing `TodoWrite`; agent teams coordinate through the same shared task list. ## Key Parameters * `.claude/agents/` markdown files or the SDK `agents` option — subagent definitions; scope precedence managed > CLI flag > project > user > plugin. * `skills:` and `isolation: worktree` — subagent frontmatter fields for granting skill content and a dedicated git worktree. * `claude agents` — open agent view; `claude --bg ""` and `claude --agent --bg` dispatch background sessions from the shell; manage with `claude attach|logs|stop|rm `. * `claude agents --permission-mode plan --model opus --effort high` — set dispatch defaults for agent view. * `disableAgentView` setting or `CLAUDE_CODE_DISABLE_AGENT_VIEW` — turn agent view off. * `"worktree": {"bgIsolation": "none"}` in `.claude/settings.json` — disable automatic worktree isolation for background sessions. * `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (env or settings.json, v2.1.32+) — enable agent teams; `teammateMode` setting / `--teammate-mode` flag picks in-process vs split-pane display. * `/goal ` (up to 4,000 chars, `/goal clear` to cancel) — completion-condition loop judged by a small fast model; bound with a clause like `or stop after 20 turns`. * `/fork ` (v2.1.161+), `/background` (`/bg`), `/agents`, `/tasks`, `/batch` — in-session orchestration commands. * `cleanupPeriodDays` (default 30) — retention for subagent transcripts and team state; background session state persists under `~/.claude/jobs//`. ## When To Use * Side task would flood your context with output you won't reference again → subagent. * Several independent tasks to hand off and check later → agent view. * Workers need to debate, share findings, or own separate layers → agent team (start with 3–5 teammates, 5–6 tasks each; research/review tasks first). * Job outgrows a handful of subagents (codebase-wide audit, 500-file migration) → dynamic workflow. * Substantial work with a verifiable end state → `/goal`. ## Risks & Pitfalls * **Token multiplication**: every parallel approach multiplies usage; ten background sessions burn quota roughly ten times as fast. * **File conflicts**: agent teams do not isolate teammates in worktrees — partition work so each teammate owns different files. Outside a git repo, background sessions aren't isolated either. * **Worktree deletion**: deleting a session in agent view (`Ctrl+X` twice) deletes its Claude-created worktree *including uncommitted changes*; push or merge first. `claude rm` is safer — it keeps dirty worktrees and prints the path. * **Agent team limitations**: no session resumption for in-process teammates, one team per lead, no nested teams, lead is fixed, task status can lag, shutdown can be slow. * **Windows**: SDK subagents with very long prompts can fail on the 8191-char command-line limit. * **`claude agents` vs `/agents`**: despite the names, the shell command opens agent view; the in-session command manages subagent definitions. ## Related Concepts [[concepts/skills-system]] · [[concepts/hooks-system]] · [[concepts/agent-sdk]] · [[concepts/checkpointing]] · [[concepts/interactive-mode]] · [[entities/claude-code-web]] · [[syntheses/cost-management]] ## Sources Primary: the parallel-agents comparison page, agent view guide, agent teams guide, `/goal` guide, SDK subagents reference, and SDK todo-tracking doc. The dedicated `/en/sub-agents` page (frontmatter field reference for filesystem subagents) is not in raw; field details here come from its mentions in the captured pages. --- title: "Agent SDK — Python" type: entity tags: [agent-sdk, python, api-reference, automation, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-agent-sdk-reference-python.md", "raw/llms_txt_doc-agent-sdk-overview.md"] --- # Agent SDK — Python ## Overview `claude-agent-sdk` is the Python library for building agents on Claude Code's agent loop and built-in tools. It requires Python 3.10+ (a `No matching distribution found` from pip means your interpreter is older) and talks to the Claude Code CLI over a subprocess transport. Unlike the TypeScript SDK, the Python package offers two distinct entry points: `query()` for one-off tasks (fresh session per call) and `ClaudeSDKClient` for continuous conversations with interrupts and response-driven control flow. Authentication matches the TypeScript SDK: `ANTHROPIC_API_KEY`, or Bedrock/Vertex/Foundry env switches. From June 15, 2026, SDK usage on subscription plans draws from a separate monthly Agent SDK credit. General concepts are in [[concepts/agent-sdk]]; this page is the Python-specific reference entity. ## Characteristics - **Install**: `pip install claude-agent-sdk`. - **`query()` vs `ClaudeSDKClient`**: `query()` creates a new session each call (unless `continue_conversation=True` or `resume` is set), manages the connection automatically, supports streaming input, hooks, and custom tools, but **not interrupts**. `ClaudeSDKClient` reuses one session across multiple `.query()` calls, supports `interrupt()`, and gives explicit lifecycle control — it's the Python equivalent of the TypeScript SDK's streaming-input mode. Use `query()` for automation scripts; use the client for chat interfaces, REPLs, and logic that reacts to responses. - **`ClaudeSDKClient` methods**: `connect()`, `query(prompt, session_id)`, `receive_messages()` (all messages), `receive_response()` (until a `ResultMessage`), `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()` (requires `enable_file_checkpointing=True` — [[concepts/checkpointing]]), `get_mcp_status()`, `reconnect_mcp_server()`, `toggle_mcp_server()`, `stop_task()`, `get_server_info()`, `disconnect()`. Works as an async context manager (`async with ClaudeSDKClient() as client:`). Avoid `break` inside message iteration (asyncio cleanup issues); after `interrupt()`, drain the interrupted task's messages (its `ResultMessage` has `subtype="error_during_execution"`) before reading the next response. - **Custom tools**: the `@tool(name, description, input_schema, annotations)` decorator defines in-process MCP tools — schemas as simple type maps (`{"name": str}`) or full JSON Schema; `create_sdk_mcp_server(name, version, tools)` bundles them for `ClaudeAgentOptions.mcp_servers` ([[concepts/mcp-integration]]). Tool names become `mcp____` in `allowed_tools`. - **`ClaudeAgentOptions`** (dataclass; snake_case mirror of the TS `Options`): `allowed_tools`/`disallowed_tools` (same semantics: allow ≠ restrict; `"Bash(rm *)"` denies even in `bypassPermissions`), `permission_mode`, `can_use_tool` (async callback returning `PermissionResultAllow` — optionally with `updated_input` to rewrite the call — or `PermissionResultDeny`), `hooks` (`dict[HookEvent, list[HookMatcher]]` — [[concepts/hooks-system]]), `agents` (`AgentDefinition` subagents — [[concepts/subagents-orchestration]]), `system_prompt` (string or `{"type": "preset", "preset": "claude_code"}`), `setting_sources`, `mcp_servers`, `strict_mcp_config`, `resume`/`fork_session`/`continue_conversation`, `session_store`/`session_store_flush`, `output_format` (`{"type": "json_schema", "schema": {...}}`), `max_turns`, `max_budget_usd`, `effort`, `thinking`, `model`/`fallback_model`, `sandbox`, `plugins`, `skills`, `cwd`, `cli_path`, `env`, `extra_args`. Note: Python `env` *merges* onto the inherited environment (TypeScript `env` replaces it). There is no Python equivalent of TypeScript's `applyFlagSettings()` or `startup()` pre-warming. - **Types**: dataclasses (`ResultMessage`, `AssistantMessage`, `TextBlock`, `AgentDefinition`) use attribute access; `TypedDict` types (`McpStdioServerConfig`, `ThinkingConfigEnabled`) are plain dicts requiring key access. Messages: `UserMessage`, `AssistantMessage` (content blocks: `TextBlock`, `ThinkingBlock`, `ToolUseBlock`, `ToolResultBlock`), `SystemMessage` (`subtype == "init"` carries `session_id`), `ResultMessage` (result, cost, usage), `StreamEvent` when `include_partial_messages=True`. Errors: `ClaudeSDKError`, `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError`. - **Session utilities**: `list_sessions()`, `get_session_messages()`, `get_session_info()`, `rename_session()`, `tag_session()` — synchronous transcript-store functions. A custom `Transport` ABC allows non-subprocess channels (low-level, unstable interface). - **Timeout env vars** via `ClaudeAgentOptions.env`: `API_TIMEOUT_MS`, `CLAUDE_CODE_MAX_RETRIES`, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`, `CLAUDE_ENABLE_STREAM_WATCHDOG`/`CLAUDE_STREAM_IDLE_TIMEOUT_MS`. ## How to Use One-off task: ```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): options = ClaudeAgentOptions( system_prompt="You are an expert Python developer", permission_mode="acceptEdits", cwd="/home/user/project", ) async for message in query(prompt="Create a Python web server", options=options): print(message) asyncio.run(main()) ``` Continuous conversation: ```python async with ClaudeSDKClient() as client: await client.query("What's the capital of France?") async for message in client.receive_response(): print(message) await client.query("What's the population of that city?") # context retained async for message in client.receive_response(): print(message) ``` A `can_use_tool` callback enables programmatic guardrails — deny writes to system paths with `PermissionResultDeny(message=..., interrupt=True)`, or sandbox-redirect file paths by returning `PermissionResultAllow(updated_input={**input_data, "file_path": safe_path})` ([[concepts/permissions-security]], [[syntheses/permission-mode-picker]]). Subagents are defined inline: `agents={"code-reviewer": AgentDefinition(description=..., prompt=..., tools=["Read", "Glob", "Grep"])}` with `"Agent"` in `allowed_tools`. To inherit Claude Code's filesystem configuration (CLAUDE.md, skills, project settings — [[concepts/memory-context]]), use the `claude_code` system-prompt preset and default `setting_sources`; pass `setting_sources=[]` to isolate the agent from local config. Choose Python vs TypeScript by host application, not capability — the option surfaces are near-identical. The notable gaps on the Python side are interrupts in plain `query()` (use `ClaudeSDKClient`), `applyFlagSettings()`, and subprocess pre-warming. Bugs go to `anthropics/claude-agent-sdk-python` on GitHub. ## Related Entities - [[entities/agent-sdk-typescript]] — TypeScript counterpart with `startup()` pre-warming and runtime flag settings - [[entities/github-actions]] / [[entities/gitlab-cicd]] — CI surfaces built on the SDK family - [[concepts/agent-sdk]] — hosting, structured outputs, cost tracking, migration guidance - [[concepts/cli-reference]] — the CLI the SDK drives; [[syntheses/cost-management]] — `max_budget_usd` and token budgeting --- title: "Agent SDK — TypeScript" type: entity tags: [agent-sdk, typescript, api-reference, automation, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-agent-sdk-reference-typescript.md", "raw/llms_txt_doc-typescript-sdk-v2-session-api-removed.md", "raw/llms_txt_doc-agent-sdk-overview.md"] --- # Agent SDK — TypeScript ## Overview `@anthropic-ai/claude-agent-sdk` is the TypeScript library that exposes Claude Code's agent loop, built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, and more), and context management as a programmable API. The package bundles a native Claude Code binary per platform as an optional dependency (e.g. `@anthropic-ai/claude-agent-sdk-darwin-arm64`), so no separate Claude Code install is required; the SDK spawns it as a subprocess. Authenticate with `ANTHROPIC_API_KEY`, or via Bedrock (`CLAUDE_CODE_USE_BEDROCK=1`), Vertex (`CLAUDE_CODE_USE_VERTEX=1`), or Foundry (`CLAUDE_CODE_USE_FOUNDRY=1`) — claude.ai login may not be offered by third-party products. Starting June 15, 2026, SDK and `claude -p` usage on subscription plans draws from a separate monthly Agent SDK credit. The general SDK concepts live in [[concepts/agent-sdk]]; this page is the TypeScript-specific reference entity. ## Characteristics - **Install**: `npm install @anthropic-ai/claude-agent-sdk`. If optional deps were skipped, the SDK throws `Native CLI binary for not found` — point `pathToClaudeCodeExecutable` at a separately installed `claude`. For `bun build --compile` single-file executables, embed the platform binary as a file asset and extract with `extractFromBunfs()` (SDK v0.3.144+). - **Core function `query()`**: takes `{ prompt, options }` where `prompt` is a string or `AsyncIterable` (streaming input mode, required for multi-turn), and returns a `Query` — an `AsyncGenerator` with control methods: `interrupt()`, `setPermissionMode()`, `setModel()`, `applyFlagSettings()` (runtime settings changes; TypeScript-only), `rewindFiles()` (requires `enableFileCheckpointing: true` — [[concepts/checkpointing]]), `initializationResult()`, `supportedCommands()/supportedModels()/supportedAgents()`, `mcpServerStatus()`, `setMcpServers()`, `streamInput()`, `stopTask()`, `close()`. - **`startup()`** pre-warms the CLI subprocess and returns a `WarmQuery` whose one-shot `.query()` skips spawn/initialization latency. `WarmQuery` implements `AsyncDisposable` (`await using`). - **Custom tools**: `tool(name, description, zodSchema, handler, { annotations })` defines a type-safe in-process MCP tool (Zod 3 and 4 supported); `createSdkMcpServer({ name, version, tools })` wraps them into a server passed via `options.mcpServers` ([[concepts/mcp-integration]]). - **Session utilities**: `listSessions()`, `getSessionMessages()`, `getSessionInfo()`, `renameSession()`, `tagSession()` read and mutate local transcript storage; `resolveSettings()` (alpha) computes effective settings with provenance using the CLI's merge engine. - **Key `Options`** (selected from ~60): `allowedTools`/`disallowedTools` (allow auto-approves but doesn't restrict; a scoped deny like `"Bash(rm *)"` blocks even in `bypassPermissions`), `permissionMode`, `canUseTool` (programmatic permission callback returning allow/deny with optional `updatedInput`), `hooks` (callback-based [[concepts/hooks-system]] events), `agents` (programmatic [[concepts/subagents-orchestration]] via `AgentDefinition`: `description`, `prompt`, `tools`, `model`, `skills`, `background`, `memory`, `effort`, `permissionMode`), `mcpServers`, `strictMcpConfig`, `settingSources` (`["user","project","local"]`; `[]` disables filesystem settings — managed policy always loads), `systemPrompt` (string, or `{ type: 'preset', preset: 'claude_code', append }`; default is a minimal prompt, *not* Claude Code's), `resume`/`forkSession`/`continue`, `sessionStore` (mirror transcripts to external storage), `outputFormat` (JSON-schema structured output), `maxTurns`, `maxBudgetUsd`, `effort`, `thinking`, `model`/`fallbackModel`, `env` (replaces, not merges — spread `process.env`), `sandbox`, `plugins`, `skills`, `cwd`. - **Message stream**: `SDKMessage` union — `SDKAssistantMessage`, `SDKUserMessage`, `SDKResultMessage` (final result, cost and usage), `SDKSystemMessage` (`subtype: "init"` carries the session ID), partial/compact-boundary/permission-denied variants, plus typed tool input/output schemas for every built-in tool. - **Timeout env vars** (passed via `options.env`): `API_TIMEOUT_MS` (default 600000), `CLAUDE_CODE_MAX_RETRIES` (default 10), `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`, `CLAUDE_ENABLE_STREAM_WATCHDOG=1` + `CLAUDE_STREAM_IDLE_TIMEOUT_MS`. ## How to Use Minimal agent: ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Find and fix the bug in auth.ts", options: { allowedTools: ["Read", "Edit", "Bash"] } })) { console.log(message); // Claude reads the file, finds the bug, edits it } ``` Multi-turn: pass an `AsyncIterable` as `prompt`, or capture `session_id` from the `init` system message and pass `options.resume` on the next `query()`. To get Claude Code's full behavior (CLAUDE.md, skills, project settings), set `systemPrompt: { type: 'preset', preset: 'claude_code' }` and `tools: { type: 'preset', preset: 'claude_code' }` — defaults are deliberately minimal for embedding. **V2 session API — removed.** Agent SDK 0.3.142 removed the experimental `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`, and the `SDKSession`/`SDKSessionOptions` types (the send/stream-per-turn pattern). Migrate to `query()` with an `AsyncIterable` prompt for multi-turn or `options.resume` for continuation. Code that must stay on V2 pins the last compatible release: ```bash npm install @anthropic-ai/claude-agent-sdk@0.2 ``` The version line jumped from 0.2.x straight to 0.3.142, so that pin and the removal boundary are the same. If you see imports of `unstable_v2_*` in a codebase, that's the signal it's frozen on 0.2.x. When to use the SDK vs. other layers: the Anthropic Client SDK gives raw API access where you implement the tool loop yourself; the Agent SDK runs the loop in your process on your infrastructure; Managed Agents is Anthropic's hosted REST alternative. CLI for interactive work, SDK for CI/CD and production automation — [[entities/github-actions]] and [[entities/gitlab-cicd]] are both built on it. Branding note for products: "Claude Agent" is allowed, "Claude Code" branding is not. Changelog and issues live at `anthropics/claude-agent-sdk-typescript` on GitHub; see [[summaries/changelog-digest]] for the CLI side. ## Related Entities - [[entities/agent-sdk-python]] — the Python counterpart (`ClaudeSDKClient` instead of streaming-input `query()`; no `applyFlagSettings()`) - [[entities/github-actions]] / [[entities/gitlab-cicd]] — CI integrations built on this SDK - [[concepts/agent-sdk]] — concepts: hosting, system prompts, structured output, cost tracking - [[concepts/permissions-security]] — `canUseTool`, allow/deny rule semantics; [[concepts/configuration]] — `settingSources` and settings precedence --- title: "Claude Code on the Web" type: entity tags: [web, cloud-sessions, sandbox, deep-links, channels, chrome, emerging] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-use-claude-code-on-the-web.md", "raw/llms_txt_doc-launch-sessions-from-links.md", "raw/llms_txt_doc-use-claude-code-with-chrome-beta.md", "raw/llms_txt_doc-channels-reference.md", "raw/llms_txt_doc-push-events-into-a-running-session-with-channels.md"] --- # Claude Code on the Web ## Overview Claude Code on the web runs tasks on Anthropic-managed cloud infrastructure at claude.ai/code. Each session gets a fresh isolated VM with your GitHub repository cloned; sessions persist when you close your browser and are monitorable from the Claude mobile app. It is in research preview for Pro, Max, and Team users (Enterprise with premium or Chat + Claude Code seats). Usage counts against your subscription limits with no separate compute charge. This page also covers two adjacent "reach a session from outside the terminal" mechanisms: deep links (`claude-cli://` URLs that open local sessions) and channels (MCP servers that push events into a running session), plus the Chrome browser integration. ## Characteristics - **Cloud environment**: fresh Ubuntu 24.04 VM per session, ~4 vCPUs / 16 GB RAM / 30 GB disk. Pre-installed: Python 3.x (pip/poetry/uv/pytest/ruff), Node 20–22 via nvm, Ruby 3.1–3.3, PHP 8.4, OpenJDK 21, Go, Rust, GCC/Clang, Docker, PostgreSQL 16, Redis 7.0, git/jq/ripgrep/tmux. Ask Claude to run `check-tools` (cloud-only command) for exact versions. The `gh` CLI is *not* pre-installed; built-in GitHub tools cover issues/PRs/diffs via a credential-isolating proxy. - **What carries over**: only what's committed to the repo — `CLAUDE.md`, `.claude/settings.json` hooks, `.mcp.json`, `.claude/rules|skills|agents|commands/`, and plugins declared in repo settings. User-level `~/.claude/*` files, `claude mcp add` servers, and static credentials do not carry over; there is no secrets store yet (env vars are visible to anyone who can edit the environment). - **Environments** control network access, env vars (`.env` format, one `KEY=value` per line, no quotes), and a **setup script** (runs as root; keep under ~5 minutes; the filesystem is snapshotted and cached for ~7 days so later sessions skip setup). Network access levels: **None**, **Trusted** (default allowlist: package registries, GitHub, container registries, cloud SDKs), **Full**, **Custom** (own allowlist, `*.` wildcards). All outbound traffic passes a security proxy; GitHub operations use a separate scoped-credential proxy that restricts pushes to the working branch. - **GitHub auth**: either authorize the Claude GitHub App, or run `/web-setup` in your terminal to sync your local `gh` token. Either grants access to any repo the account can see. The App is required for **Auto-fix** (Claude watches a PR and responds to CI failures and review comments; enable via the CI status bar, `/autofix-pr` on the branch, the mobile app, or pasting a PR URL). Zero Data Retention orgs cannot use cloud session features; org IP allowlisting breaks cloud sessions, Code Review, and Routines. - **Session movement**: `claude --remote "task"` starts a cloud session from your terminal (pushes nothing — it clones from GitHub, so push first; non-GitHub repos upload as a bundle under 100 MB, forced with `CCR_FORCE_BUNDLE=1`). `claude --teleport` (or `/teleport`, `/tp`, or `t` from `/tasks`) pulls a cloud session into your terminal — requires clean git state, the same repo, the branch pushed, and the same claude.ai account. `--teleport` is unavailable on API key/Bedrock/Vertex/Foundry auth. `/remote-env` selects the default environment for `--remote`. - **Context management**: `/compact` and `/context` work in cloud sessions; `/clear` does not. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` tunes auto-compaction. Subagents work as locally ([[concepts/subagents-orchestration]]). - **Deep links**: `claude-cli://open?repo=owner/name&q=` (or `cwd=` for absolute paths; `cwd` wins if both given) opens a local terminal session with the prompt pre-filled but never auto-sent — a `Prompt from an external link` warning shows until you send or clear. Prompt max 5,000 chars, `%0A` for line breaks. Requires Claude Code v2.1.91+. Handler registers on first interactive session (macOS: `~/Applications/Claude Code URL Handler.app`; Linux: `claude-code-url-handler.desktop`; Windows: `HKEY_CURRENT_USER\Software\Classes\claude-cli`). GitHub-rendered Markdown strips the scheme, so put links in code blocks there. Disable with `disableDeepLinkRegistration: "disable"` in settings. - **Channels** (research preview, v2.1.80+): an MCP server that declares `capabilities.experimental['claude/channel']` and emits `notifications/claude/channel` events that arrive in your running session as `` tags. Telegram, Discord, iMessage, and the localhost demo fakechat ship as plugins (require Bun). Two-way channels expose a reply tool; with `claude/channel/permission` declared they can relay tool-approval prompts to your phone ("yes "/"no ", v2.1.81+). Sender allowlists with pairing codes gate prompt injection. Enable per session with `--channels plugin:@claude-plugins-official`; test custom servers with `--dangerously-load-development-channels`. Team/Enterprise admins must set `channelsEnabled: true`; `allowedChannelPlugins` replaces the Anthropic allowlist. Not available on Bedrock/Vertex/Foundry. - **Chrome integration (beta)**: the Claude in Chrome extension (v1.0.36+, Chrome or Edge only; no Brave/Arc/WSL) gives CLI sessions browser automation — live debugging from console logs, testing local web apps, form filling, data extraction, GIF recording — sharing your logged-in browser state. Requires Claude Code v2.0.73+ and a direct Anthropic plan. ## How to Use Start at claude.ai/code (connect GitHub during onboarding) or from the terminal: ```bash claude --remote "Fix the authentication bug in src/auth/login.ts" ``` Monitor with `/tasks`; run multiple `--remote` commands for parallel sessions. A proven pattern is *plan locally, execute remotely*: `claude --permission-mode plan`, commit the plan, then `claude --remote "Execute the migration plan in docs/migration-plan.md"`. Review diffs in the browser (`+42 -18` indicator → inline comments), then create a PR or teleport back. Sessions can be shared (Private/Team on Team-Enterprise; Private/Public on Pro/Max — check for credentials first), archived, or deleted. For Chrome, start `claude --chrome` (or `/chrome` in-session; VS Code needs no flag — see [[entities/ide-extensions]]). For dependency installs that should run both locally and in the cloud, prefer a SessionStart hook gated on `CLAUDE_CODE_REMOTE=true` ([[concepts/hooks-system]]); use the environment setup script for cloud-only tooling like `apt update && apt install -y gh`. Troubleshooting: "Session creation failed" → check status.claude.com, retry, confirm repo access; "environment has expired" → reopen from claude.ai/code; `--teleport` auth errors → `/login` with the owning account. See [[syntheses/troubleshooting-checklist]]. ## Related Entities - [[entities/desktop-app]] — Remote sessions in Desktop run on this same infrastructure; Desktop's "Continue in" can push a local session to the web (the CLI cannot) - [[entities/github-actions]] — run Claude in your own CI instead of Anthropic's managed sandbox - [[entities/plugin-marketplaces]] — channels ship as plugins; repo-declared plugins install into cloud sessions - [[concepts/mcp-integration]] — channels are an MCP extension; [[concepts/permissions-security]] — permission relay and sandbox isolation - [[syntheses/surface-picker]], [[summaries/casebook-runtime]] --- title: "Claude Code Desktop App" type: entity tags: [desktop, surface, parallel-sessions, computer-use, scheduled-tasks, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-desktop-application.md", "raw/llms_txt_doc-get-started-with-the-desktop-app.md", "raw/llms_txt_doc-schedule-recurring-tasks-in-claude-code-desktop.md"] --- # Claude Code Desktop App ## Overview The Claude Desktop app is a graphical surface for Claude Code with three tabs: **Chat** (conversation, no file access), **Cowork** (autonomous background agent in a cloud VM, home of Dispatch), and **Code** (interactive coding on local files). It runs the same engine as the CLI — both can run simultaneously on the same project and share configuration via CLAUDE.md, MCP servers, hooks, skills, and settings files. Available on macOS (universal Intel/Apple Silicon) and Windows (x64 and ARM64 installers); not available on Linux (use the CLI). Requires a Pro, Max, Team, or Enterprise subscription. The app bundles Claude Code, so no Node.js or separate CLI install is needed. On Windows, Git for Windows must be installed for the Code tab to work. ## Characteristics - **Sessions**: each Code-tab conversation is an independent session with its own chat history, project folder, and changes. For Git repos, each session gets an isolated Git worktree (stored in `/.claude/worktrees/` by default) so parallel sessions don't collide. A `.worktreeinclude` file copies gitignored files like `.env` into new worktrees. - **Environments**: sessions run **Local** (your machine), **Remote** (Anthropic cloud — continues even if you close the app; same infrastructure as [[entities/claude-code-web]], supports multiple repositories), or **SSH** (remote Linux/macOS machine; Desktop installs Claude Code there automatically on first connect). - **Permission modes**: Ask permissions (`default`), Auto accept edits (`acceptEdits`), Plan mode (`plan`), Auto (`auto`, research preview requiring Claude Opus 4.6+/Sonnet 4.6), and Bypass permissions (`bypassPermissions`, equivalent to `--dangerously-skip-permissions`, enabled in Settings). `dontAsk` mode is CLI-only. See [[syntheses/permission-mode-picker]]. - **Workspace panes**: chat, diff, preview, terminal, file, plan, tasks, and subagent panes in a drag-and-drop layout (requires Desktop v1.2581.0+). Integrated terminal opens with **Ctrl+`** and shares the session's environment; local sessions only. - **Diff review and PRs**: a `+12 -1` style indicator opens the diff viewer; comment on lines and submit all comments with **Cmd+Enter** (macOS) / **Ctrl+Enter** (Windows). **Review code** asks Claude to evaluate the diff. After a PR opens, a CI status bar offers **Auto-fix** (Claude fixes failing checks) and **Auto-merge** (squash merge once checks pass); PR monitoring requires the GitHub CLI (`gh`). - **App preview**: Claude starts dev servers and verifies changes in an embedded browser (screenshots, DOM inspection, clicking, form filling). Configuration lives in `.claude/launch.json` (fields: `name`, `runtimeExecutable`, `runtimeArgs`, `port`, `cwd`, `env`, `autoPort`, `program`, `args`). `autoVerify` is on by default; disable with `"autoVerify": false`. - **Computer use**: research preview on macOS/Windows for Pro and Max plans (not Team/Enterprise). Off by default; enable in Settings > General. Per-app tiers are fixed: browsers and trading platforms are view-only, terminals and IDEs click-only, everything else full control. macOS additionally requires Accessibility and Screen Recording permissions. - **Dispatch**: a persistent Cowork-tab conversation that can spawn Code sessions from your phone; such sessions show a **Dispatch** badge and computer-use app approvals expire after 30 minutes. - **Scheduled tasks (Routines)**: local tasks run on your machine while the app is open (minimum interval 1 minute); remote routines run on Anthropic cloud even when your computer is off (minimum 1 hour). Task prompts live in `~/.claude/scheduled-tasks//SKILL.md`. Missed runs get exactly one catch-up run for the most recently missed time within seven days. - **Key shortcuts** (Cmd on macOS, Ctrl on Windows): `Cmd N` new session, `Cmd W` close session, `Ctrl Tab` cycle sessions, `Esc` stop response, `Cmd Shift D` diff pane, `Cmd Shift P` preview pane, `Ctrl` `` ` `` terminal, `Cmd ;` side chat, `Ctrl O` cycle view modes (Normal/Verbose/Summary), `Cmd Shift M` permission mode menu, `Cmd /` show all shortcuts. Terminal [[concepts/interactive-mode]] shortcuts like Shift+Tab do not apply in Desktop. ## How to Use Install from claude.com download links, sign in, and click the **Code** tab. Pick an environment, select a project folder, choose a model from the dropdown, set a permission mode, type a task, and press Enter. By default new sessions start in Ask permissions mode with Accept/Reject buttons per change. Useful flows: - **Context**: `@filename` mentions (local/SSH only), file attachments (images, PDFs), drag-and-drop. Type `/` to browse built-in commands, custom skills, and plugin skills ([[concepts/skills-system]]). - **Side chat**: press **Cmd+;** / **Ctrl+;** or type `/btw` to ask a question using session context without adding to the main thread. - **Move a CLI session to Desktop**: run `/desktop` in the terminal (subscription auth only; not API key/Bedrock/Vertex/Foundry). The **Continue in** menu sends a local session to the web (requires clean working tree) or opens the project in an IDE ([[entities/ide-extensions]]). - **Connectors and plugins**: the **+** button adds Connectors (MCP servers with graphical setup — see [[concepts/mcp-integration]]) and Plugins from configured marketplaces ([[entities/plugin-marketplaces]]); neither is available in cloud sessions. The Desktop app also loads MCP servers from `claude_desktop_config.json`; the standalone CLI does not (use `claude mcp add-from-claude-desktop` to import). - **Create a scheduled task**: click **Routines** → **New routine** → **Local**, or just describe it in a session ("set up a daily code review that runs every morning at 9am"). Run it once manually and choose "always allow" on permission prompts so future runs don't stall. - **Enterprise**: managed settings keys include `permissions.disableBypassPermissionsMode`, `disableAutoMode`, `autoMode`, `sshConfigs`, `sshHostAllowlist`, and `managedMcpServers`. MDM via `com.anthropic.claudefordesktop` (macOS) or registry `SOFTWARE\Policies\Claude` (Windows). See [[concepts/enterprise-deployment]]. CLI flag equivalents: `--model` → model dropdown, `--resume`/`--continue` → sidebar click, `--permission-mode` → mode selector, `--verbose` → Verbose view mode. `--print`/`--output-format` have no Desktop equivalent (Desktop is interactive only — use the [[concepts/cli-reference]] or [[concepts/agent-sdk]] for scripting). Not available in Desktop: Linux, inline code suggestions, agent teams, and terminal-dialog commands (`/permissions`, `/config`, `/agents`, `/doctor`) — edit settings files directly instead ([[concepts/configuration]]). Troubleshooting highlights: 403 errors → sign out/in and verify a paid plan; "Git is required" on Windows → install Git for Windows and restart; tools not found → check shell PATH and restart the app; cloud-created branch missing locally → `git fetch origin ` then `git checkout `. Runtime API errors (500/529/429) are shared across surfaces — see [[summaries/casebook-runtime]] and [[syntheses/troubleshooting-checklist]]. ## Related Entities - [[entities/claude-code-web]] — the cloud infrastructure behind Remote sessions - [[entities/ide-extensions]] — alternative graphical surfaces inside VS Code and JetBrains - [[entities/plugin-marketplaces]] — plugins installable from the Desktop plugin browser - [[syntheses/surface-picker]] — choosing between CLI, Desktop, web, and IDE - [[concepts/installation-setup]], [[concepts/memory-context]], [[concepts/permissions-security]] --- title: "Claude Code GitHub Actions" type: entity tags: [github, ci-cd, code-review, automation, enterprise, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-claude-code-github-actions.md", "raw/llms_txt_doc-code-review.md", "raw/llms_txt_doc-claude-code-with-github-enterprise-server.md"] --- # Claude Code GitHub Actions ## Overview Claude Code GitHub Actions (`anthropics/claude-code-action@v1`) runs Claude inside your GitHub Actions workflows. A `@claude` mention in any PR or issue comment makes Claude analyze code, implement features, fix bugs, and open PRs, following your repository's `CLAUDE.md` standards. It is built on the [[concepts/agent-sdk]] and runs on your own GitHub runners (you pay Actions minutes plus API tokens). Two sibling offerings cover related ground: **Code Review**, an Anthropic-managed multi-agent PR review service for Team/Enterprise plans (no runner setup, billed per review), and **GitHub Enterprise Server (GHES)** support for self-hosted GitHub instances. ## Characteristics **The Action** auto-detects its mode: interactive (responds to `@claude` mentions in `issue_comment` / `pull_request_review_comment` events) or automation (runs immediately when a `prompt` input is set, on any trigger including `schedule`). Key inputs: `prompt` (plain text or a skill invocation like `/code-review:code-review ...`), `claude_args` (passthrough for any CLI argument: `--max-turns`, `--model`, `--mcp-config`, `--allowedTools`, `--debug`), `plugin_marketplaces` / `plugins` (install plugins before execution), `anthropic_api_key`, `github_token`, `trigger_phrase` (default `"@claude"`), `use_bedrock`, `use_vertex`. v1.0 broke from beta: `@beta` → `@v1`, `mode` removed, `direct_prompt` → `prompt`, `custom_instructions` → `claude_args: --append-system-prompt`, `max_turns`/`model`/`allowed_tools` → `claude_args` flags. **Code Review** (research preview, Team/Enterprise; not for Zero Data Retention orgs): a fleet of specialized agents reviews the diff against the full codebase on Anthropic infrastructure, verification filters false positives, and findings post as inline comments tagged 🔴 Important / 🟡 Nit / 🟣 Pre-existing. The "Claude Code Review" check run always concludes neutral (never blocks merges); its Details text ends with a machine-readable `bughunter-severity:` JSON you can parse with `gh ... --jq` to gate merges yourself. Per-repo triggers: once after PR creation, after every push, or manual. Comment commands: `@claude review` (starts a review *and* subscribes the PR to push-triggered reviews) and `@claude review once` (single review, no subscription) — top-level comments only, comment must start with the command, requires owner/member/collaborator access. Reviews average $15–25 each, billed via usage credits separately from plan usage; ~20 minutes per review. Tune behavior with `CLAUDE.md` (violations flagged as nits, applies to all Claude Code use — [[concepts/memory-context]]) and `REVIEW.md` (review-only, injected highest-priority, verbatim — no `@` imports; use it for severity definitions, nit caps, skip paths, repo-specific checks). Locally, `/code-review` reviews a diff in any session without the GitHub App (`--comment` posts inline, `--fix` applies, `ultra` runs the cloud ultrareview). **GHES**: an admin connects the self-hosted instance once at claude.ai/admin-settings/claude-code (guided GitHub-App-manifest flow or manual credentials). Then web sessions, Code Review, Claude Security, teleport, plugin marketplaces (full git URLs, not `owner/repo`), and contribution metrics all work; the GitHub MCP server does not (use `gh auth login --hostname github.example.com` instead). `/install-github-app` is github.com-only — adapt the example workflow manually for Actions on GHES. The instance must be reachable from Anthropic infrastructure (allowlist Anthropic API IPs). ## How to Use **Quick setup**: run `/install-github-app` in a Claude Code terminal (repo admin required; direct Anthropic API only). Manual: install the Claude GitHub App (github.com/apps/claude — Contents, Issues, Pull requests: read & write), add `ANTHROPIC_API_KEY` to repo secrets, copy `examples/claude.yml` into `.github/workflows/`. Minimal workflow: ```yaml name: Claude Code on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude: runs-on: ubuntu-latest steps: - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Responds to @claude mentions in comments ``` Scheduled automation passes a prompt directly: ```yaml on: schedule: - cron: "0 9 * * *" # ... - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: "Generate a summary of yesterday's commits and open issues" claude_args: "--model opus" ``` To run a plugin skill on every PR, set `plugin_marketplaces: "https://github.com/anthropics/claude-code.git"`, `plugins: "code-review@claude-code-plugins"`, and `prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"` ([[entities/plugin-marketplaces]]). **Bedrock / Vertex AI** ([[concepts/enterprise-deployment]]): create your own GitHub App (Contents/Issues/PRs read-write), authenticate via OIDC — AWS needs an IAM role trusted by `token.actions.githubusercontent.com` (secret `AWS_ROLE_TO_ASSUME`, then `use_bedrock: "true"` with `claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'`; Bedrock model IDs carry a region prefix); GCP needs Workload Identity Federation (`GCP_WORKLOAD_IDENTITY_PROVIDER`, `GCP_SERVICE_ACCOUNT`, then `use_vertex: "true"` with env `ANTHROPIC_VERTEX_PROJECT_ID` and `CLOUD_ML_REGION`). Generate tokens with `actions/create-github-app-token@v2` from `APP_ID` + `APP_PRIVATE_KEY` secrets. **Code Review setup**: admin opens claude.ai/admin-settings/claude-code → Code Review → Setup, installs the GitHub App, selects repos, picks per-repo Review Behavior. Set spend caps at claude.ai/admin-settings/usage; monitor at claude.ai/analytics/code-review. A failed/timed-out review never blocks the PR but doesn't retry — comment `@claude review once` (GitHub's Re-run button does *not* retrigger). **Cost control** ([[syntheses/cost-management]]): use specific `@claude` commands, set `--max-turns` and workflow timeouts, use concurrency limits; for Code Review, push-triggered mode multiplies cost per push, and `@claude review` subscribes the PR to that. Never commit API keys — always `${{ secrets.ANTHROPIC_API_KEY }}`. **Troubleshooting**: no response to `@claude` → App installed? workflows enabled? key set? comment says `@claude` not `/claude`? CI not running on Claude's commits → use a GitHub App token, not the Actions user. Auth errors → verify key/OIDC config and secret names. See [[syntheses/troubleshooting-checklist]]. ## Related Entities - [[entities/gitlab-cicd]] — the equivalent integration for GitLab pipelines - [[entities/claude-code-web]] — Auto-fix PRs and managed cloud sessions instead of self-run CI - [[entities/agent-sdk-typescript]] / [[entities/agent-sdk-python]] — the SDK layer this action is built on - [[concepts/skills-system]] — skills invocable from the `prompt` input; [[concepts/configuration]] - [[syntheses/extension-decision-guide]] — managed Code Review vs. self-hosted Actions vs. local `/code-review` --- title: "Claude Code GitLab CI/CD" type: entity tags: [gitlab, ci-cd, automation, merge-requests, enterprise, emerging] created: 2026-06-10 updated: 2026-06-10 confidence: medium sources: ["raw/llms_txt_doc-claude-code-gitlab-ci-cd.md"] --- # Claude Code GitLab CI/CD ## Overview Claude Code for GitLab CI/CD runs Claude inside GitLab pipeline jobs to turn issues and comments into merge requests: mention `@claude` (via a webhook-driven trigger) or run a job manually, and Claude analyzes the thread and repository, implements changes in a branch, and opens an MR. The integration is in beta and is **maintained by GitLab, not Anthropic** (support via GitLab issue 573776). It is built on the Claude Code CLI and [[concepts/agent-sdk]], runs entirely on your GitLab runners inside isolated containers, and supports three providers: the Claude API, Amazon Bedrock (OIDC role assumption), and Google Vertex AI (Workload Identity Federation). Because every change flows through an MR, your branch protection and approval rules apply to AI-generated code unchanged. ## Characteristics - **Architecture**: event-driven orchestration (GitLab listens for chosen triggers, collects context from the thread and repo, builds prompts, runs Claude Code) → provider abstraction (API / Bedrock / Vertex) → sandboxed execution (container with restricted network and filesystem; workspace-scoped permissions constrain writes). - **Triggering**: there is no built-in `@claude` listener — you wire it yourself. Job `rules` typically cover `$CI_PIPELINE_SOURCE == "web"` (manual) and `"merge_request_event"`; mention-driven flows need a project webhook for "Comments (notes)" that calls the pipeline trigger API with variables like `AI_FLOW_INPUT`, `AI_FLOW_CONTEXT`, and `AI_FLOW_EVENT` when a comment contains `@claude`. - **Credentials**: `ANTHROPIC_API_KEY` as a masked CI/CD variable for the direct API; `AWS_ROLE_TO_ASSUME` + `AWS_REGION` for Bedrock; `GCP_WORKLOAD_IDENTITY_PROVIDER` + `GCP_SERVICE_ACCOUNT` + `CLOUD_ML_REGION` for Vertex — all OIDC-based, no static cloud keys. GitLab API operations use `CI_JOB_TOKEN` by default or a Project Access Token with `api` scope stored as `GITLAB_ACCESS_TOKEN`. - **GitLab MCP server**: jobs can start `/bin/gitlab-mcp-server` and expose its tools to Claude via `--allowedTools "... mcp__gitlab"`, which is how Claude posts comments and opens MRs ([[concepts/mcp-integration]]). - **Project guidance**: Claude reads `CLAUDE.md` at the repo root during runs and follows your conventions ([[concepts/memory-context]]). Task-specific instructions go through `-p` / `prompt_file` per job. - **Bedrock model IDs** carry region prefixes, e.g. `us.anthropic.claude-sonnet-4-6`. ## How to Use **Quick setup**: add `ANTHROPIC_API_KEY` as a masked variable (**Settings → CI/CD → Variables**), then add a job to `.gitlab-ci.yml`: ```yaml stages: - ai claude: stage: ai image: node:24-alpine3.21 rules: - if: '$CI_PIPELINE_SOURCE == "web"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' variables: GIT_STRATEGY: fetch before_script: - apk update - apk add --no-cache git curl bash - curl -fsSL https://claude.ai/install.sh | bash script: - /bin/gitlab-mcp-server || true - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT" - > claude -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}" --permission-mode acceptEdits --allowedTools "Bash Read Edit Write mcp__gitlab" --debug ``` Test manually from **CI/CD → Pipelines** or trigger from an MR. Typical comment-driven asks: `@claude implement this feature based on the issue description`, `@claude fix the TypeError in the user dashboard component`, `@claude suggest a concrete approach to cache the results of this API call`. **Amazon Bedrock job**: in `before_script`, exchange the GitLab OIDC token (`CI_JOB_JWT_V2`) for temporary credentials with `aws sts assume-role-with-web-identity --role-arn "$AWS_ROLE_TO_ASSUME" ... --duration-seconds 3600`, export `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` from the JSON, then run the same `claude -p` invocation. **Vertex AI job**: use the `gcr.io/google.com/cloudsdktool/google-cloud-cli:slim` image and authenticate with `gcloud auth login --cred-file=` pointing at an inline `external_account` JSON referencing `${GCP_WORKLOAD_IDENTITY_PROVIDER}` and `${GCP_SERVICE_ACCOUNT}`; set `CLOUD_ML_REGION` (e.g. `us-east5`). Neither requires downloadable keys. **Permission posture**: the documented jobs run `--permission-mode acceptEdits` with an explicit `--allowedTools` list — appropriate for an isolated runner container but worth understanding before adapting; see [[concepts/permissions-security]] and [[syntheses/permission-mode-picker]]. Common knobs: `-p`/`prompt_file`, `max_turns`, `timeout_minutes`. Exact flags vary by version — run `claude --help` in the job ([[concepts/cli-reference]]). **Costs** ([[syntheses/cost-management]]): you pay GitLab runner minutes plus API tokens per interaction. Keep `CLAUDE.md` concise, write clear issue/MR descriptions to cut iterations, set job timeouts and `max_turns`, limit concurrency, and cache npm/package installs in runners. **Troubleshooting**: no response to `@claude` → pipeline actually triggered? variables present? comment says `@claude` not `/claude`? webhook/listener configured? Can't comment or open MRs → `CI_JOB_TOKEN` permissions or PAT `api` scope, `mcp__gitlab` in `--allowedTools`, job has MR context via `AI_FLOW_*`. Auth errors → key validity, or OIDC/WIF role, region, and model availability for Bedrock/Vertex. See [[syntheses/troubleshooting-checklist]]. Compared with [[entities/github-actions]]: same bring-your-own-runner model and provider choices, but GitLab has no `/install-github-app`-style one-command setup, no Anthropic-managed Code Review equivalent, and mention triggers require manual webhook plumbing. Repos on GitLab also can't push results back from Claude Code on the web cloud sessions (bundle upload is one-way), making CI/CD the primary automation path for GitLab-hosted code. ## Related Entities - [[entities/github-actions]] — the GitHub counterpart, including managed Code Review - [[entities/claude-code-web]] — GitLab repos can be bundled into cloud sessions but can't push back - [[entities/agent-sdk-typescript]] / [[entities/agent-sdk-python]] — for custom automation beyond CI jobs - [[concepts/enterprise-deployment]] — Bedrock/Vertex provider setup in depth - [[syntheses/extension-decision-guide]] --- title: "IDE Extensions (VS Code & JetBrains)" type: entity tags: [ide, vscode, jetbrains, surface, diff-viewing, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: medium sources: ["raw/llms_txt_doc-jetbrains-ides.md", "raw/llms_txt_doc-launch-sessions-from-links.md", "raw/llms_txt_doc-use-claude-code-with-chrome-beta.md", "raw/llms_txt_doc-claude-code-changelog.md", "raw/github_issue-bug-claude-code-does-not-detect-jetbrains-ide-on-windows-wsl.md"] --- # IDE Extensions (VS Code & JetBrains) ## Overview Claude Code integrates with editors through two extensions: a native VS Code extension (which also serves Cursor, Windsurf, and other VS Code forks) and a JetBrains plugin (IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, GoLand, and most other JetBrains IDEs). Both connect a Claude Code session to the editor so diffs render in the IDE's diff viewer, the current selection and tab are shared as context, and IDE diagnostics (lint and syntax errors) flow to Claude automatically. The JetBrains integration wraps the terminal CLI; the VS Code extension is a native extension with its own editor-tab UI, activity-bar session list, and plan review documents. Note: the captured raw corpus has no dedicated VS Code doc page, so VS Code specifics here are assembled from the changelog, deep-links, and Chrome docs — hence medium confidence. ## Characteristics **Shared integration features** (both IDEs): - **Quick launch**: `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) opens Claude Code from the editor. - **Diff viewing**: code changes display in the IDE diff viewer instead of the terminal (set via `/config`, diff tool `auto`). - **Selection context**: the current selection/tab is automatically shared with Claude; `Read` deny rules in [[concepts/permissions-security]] block this sharing for matching files. - **File reference shortcuts**: `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) inserts references like `@src/auth.ts#L1-99`. - **Diagnostic sharing**: IDE lint/syntax errors are shared with Claude as you work. **VS Code specifics** (from changelog and related docs): - Native extension with a spark icon in the activity bar listing all sessions; sessions open as full editors. Supports the secondary sidebar (VS Code 1.97+), respects `chat.fontSize`/`chat.fontFamily`. - Full markdown plan view with inline commenting; the preview auto-updates as Claude iterates. - URI handler `vscode://anthropic.claude-code/open` opens a new Claude Code editor tab programmatically, with optional `prompt` and `session` query parameters — the editor-tab counterpart of the `claude-cli://` deep links covered in [[entities/claude-code-web]]. - Browser automation: with the Claude in Chrome extension installed, Chrome tools are available in VS Code sessions with no extra flag (the CLI needs `--chrome`). - `/terminal-setup` tunes the integrated terminal (scroll sensitivity, disables GPU acceleration to prevent garbled rendering, fixes Shift+Enter). **JetBrains specifics**: - Plugin settings live at **Settings → Tools → Claude Code [Beta]**: custom Claude command (e.g. `claude`, `/usr/local/bin/claude`, or `npx @anthropic-ai/claude-code`), notification suppression, Option+Enter multi-line prompts (macOS), automatic plugin updates. - WSL users set the Claude command to `wsl -d Ubuntu -- bash -lic "claude"` (replace `Ubuntu` with your distribution). - If ESC doesn't interrupt Claude in JetBrains terminals: **Settings → Tools → Terminal**, then uncheck "Move focus to the editor with Escape" or delete the "Switch focus to Editor" keybinding. - **Remote Development**: the plugin must be installed on the remote host via **Settings → Plugin (Host)**, not the local client. - **Security**: with auto-edit permissions, Claude could modify IDE configuration files that the IDE auto-executes, potentially bypassing bash permission prompts. Consider manual approval mode in JetBrains IDEs. ## How to Use **Install — VS Code**: install the Claude Code extension from the VS Code marketplace (also works in Cursor/Windsurf); running `claude` in the integrated terminal also surfaces integration. **Install — JetBrains**: install the Claude Code plugin from the JetBrains marketplace (plugin id `27310-claude-code-beta-`) and restart the IDE completely (sometimes more than once). Claude Code itself must already be installed — see [[concepts/installation-setup]]. **Connect a session**: run `claude` from the IDE's integrated terminal and integration activates automatically. From an external terminal, connect with: ```text /ide ``` Start Claude Code from the project root so it sees the same files as the IDE. Configure diff behavior with `/config` (diff tool `auto` = IDE, `terminal` = stay in terminal). **WSL2 + JetBrains "No available IDEs detected"** (a long-running pain point — GitHub issue #1232 collected 113 comments before docs added fixes): WSL2's NAT networking or Windows Firewall blocks the WSL-to-IDE connection. Two fixes: 1. Firewall rule (recommended). Find your WSL subnet with `hostname -I`, then in admin PowerShell: ```powershell New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16 ``` 2. Mirrored networking (Windows 11 22H2+): add to `.wslconfig` in your Windows user directory, then `wsl --shutdown`: ```ini [wsl2] networkingMode=mirrored ``` **Other troubleshooting**: plugin installed but features missing → run from project root, confirm plugin enabled, fully restart the IDE; "command not found" on the Claude icon → verify `claude --version` works and set the command path in plugin settings. For install/login problems outside the IDE, see [[summaries/casebook-install-auth]]. **When to choose an IDE extension** over the CLI or [[entities/desktop-app]]: you want diffs, selection context, and diagnostics inside the editor you already use; the Desktop app instead offers parallel worktree sessions, app preview, and PR monitoring; the bare CLI offers scripting via [[concepts/cli-reference]]. See [[syntheses/surface-picker]] and [[syntheses/extension-decision-guide]] for the comparison. ## Related Entities - [[entities/desktop-app]] — standalone graphical surface; its "Continue in" menu can hand a session to your IDE - [[entities/claude-code-web]] — `claude-cli://` and `vscode://` deep links open sessions from runbooks and dashboards - [[entities/plugin-marketplaces]] — LSP plugins give Claude the same language-server intelligence that powers VS Code - [[concepts/interactive-mode]], [[concepts/configuration]], [[syntheses/troubleshooting-checklist]] --- title: "Plugins & Marketplaces" type: entity tags: [plugins, marketplaces, lsp, extensions, skills, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-discover-and-install-prebuilt-plugins-through-marketplaces.md", "raw/llms_txt_doc-explore-the-claude-directory.md", "raw/github_doc-plugins-readme-md.md"] --- # Plugins & Marketplaces ## Overview Plugins are reusable packages that extend Claude Code with skills, agents, hooks, MCP servers, and LSP configurations. Marketplaces are catalogs of plugins — using one is a two-step process like an app store: add the marketplace (registers the catalog, installs nothing), then install individual plugins from it. The official Anthropic marketplace (`claude-plugins-official`) is available automatically; the community marketplace (`anthropics/claude-plugins-community`, validated third-party plugins pinned to commit SHAs) and the demo marketplace in the `anthropics/claude-code` repo are added manually. Plugins are highly trusted components that execute arbitrary code with your user privileges — only install from sources you trust. ## Characteristics - **Official marketplace categories**: *code intelligence* (LSP plugins per language — `pyright-lsp`, `typescript-lsp`, `rust-analyzer-lsp`, `gopls-lsp`, `clangd-lsp`, `jdtls-lsp`, etc. — each requiring the language-server binary on `$PATH`; they give Claude automatic post-edit diagnostics and precise navigation: go-to-definition, references, call hierarchies); *external integrations* (pre-configured MCP servers: `github`, `gitlab`, `atlassian`, `linear`, `notion`, `figma`, `vercel`, `supabase`, `slack`, `sentry` — see [[concepts/mcp-integration]]); *security* (`security-guidance` reviews each change for vulnerabilities); *development workflows* (`commit-commands`, `pr-review-toolkit`, `agent-sdk-dev`, `plugin-dev`); *output styles* (`explanatory-output-style`, `learning-output-style`). - **Bundled example plugins** (demo marketplace `claude-code-plugins` in the anthropics/claude-code repo): `feature-dev` (7-phase workflow with `code-explorer`/`code-architect`/`code-reviewer` agents), `code-review` (5 parallel agents with confidence scoring), `commit-commands` (`/commit`, `/commit-push-pr`, `/clean_gone`), `hookify` (generates hooks from conversation patterns — [[concepts/hooks-system]]), `frontend-design` (auto-invoked skill), `ralph-wiggum` (`/ralph-loop` self-iteration via a Stop hook), `agent-sdk-dev` (`/new-sdk-app` plus SDK verifier agents — [[concepts/agent-sdk]]), `plugin-dev`, `pr-review-toolkit`, `claude-opus-4-5-migration`, and the two output styles. - **Plugin anatomy**: `.claude-plugin/plugin.json` metadata plus optional `commands/`, `agents/`, `skills/`, `hooks/`, and `.mcp.json`. A marketplace is any repo/path/URL containing `.claude-plugin/marketplace.json`. Installed plugins live in `~/.claude/plugins` (cloned marketplaces, versions, per-plugin data; orphaned versions deleted 7 days after update/uninstall). Skills are namespaced: `commit-commands` provides `/commit-commands:commit` ([[concepts/skills-system]]). - **Scopes**: user (default — all your projects), project (all collaborators, via `.claude/settings.json`), local (you, this repo only), and managed (admin-installed, immutable). See [[concepts/configuration]]. - **Plugin manager** (`/plugin`): tabs for Discover, Installed, Marketplaces, Errors. Details show a Context cost token estimate (v2.1.143+), Last updated (v2.1.144+), and a Will install component inventory (v2.1.145+). Admin-allowlisted marketplaces (via `pluginSuggestionMarketplaces`) can pin directory-relevant plugins as "suggested" (v2.1.154+). - **Auto-update**: official marketplaces auto-update on startup by default; third-party/local ones don't. `DISABLE_AUTOUPDATER` kills all updates; add `FORCE_AUTOUPDATE_PLUGINS=1` to keep plugin updates while freezing Claude Code itself. ## How to Use Install from the official marketplace: ```shell /plugin install github@claude-plugins-official ``` If "not found in any marketplace": `/plugin marketplace update claude-plugins-official`, or `/plugin marketplace add anthropics/claude-plugins-official`. Community marketplace: `/plugin marketplace add anthropics/claude-plugins-community`, then `/plugin install @claude-community`. Add marketplaces from GitHub (`/plugin marketplace add anthropics/claude-code`), any git host (`/plugin marketplace add https://gitlab.com/company/plugins.git`, SSH form `git@gitlab.com:company/plugins.git`, pin a ref with `#v1.0.0` — include `.git` so it clones), local paths (`./my-marketplace` or a direct `marketplace.json` path), or remote URLs. Shortcuts: `/plugin market`, `rm` for `remove`. On GitHub Enterprise Server use full git URLs — `owner/repo` shorthand always resolves to github.com ([[entities/github-actions]]). Manage: `/plugin list` (`--enabled`/`--disabled`), `/plugin disable|enable|uninstall plugin-name@marketplace-name`, `claude plugin install formatter@your-org --scope project`, `/plugin marketplace list|update|remove`. Removing a marketplace uninstalls its plugins. After changes run `/reload-plugins` — note it invalidates prompt cache for non-deferred MCP tools and from v2.1.163 warns and requires `--force` in that case. Team distribution via project `.claude/settings.json`: ```json { "extraKnownMarketplaces": { "my-team-tools": { "source": { "source": "github", "repo": "your-org/claude-plugins" } } } } ``` When members trust the folder, Claude Code prompts them to install. Admins can restrict allowed marketplaces with `strictKnownMarketplaces` (including `hostPattern` for whole GHES hosts) and set `"autoUpdate": true` per managed marketplace entry ([[concepts/enterprise-deployment]]). Plugins declared in repo settings also install into [[entities/claude-code-web]] cloud sessions; the [[entities/desktop-app]] has a graphical plugin browser (no terminal needed). Troubleshooting: `/plugin` unrecognized → update Claude Code (`npm install -g @anthropic-ai/claude-code@latest` or `brew upgrade claude-code`); `Executable not found in $PATH` in the Errors tab → install the LSP binary; skills not appearing → `rm -rf ~/.claude/plugins/cache`, restart, reinstall; high LSP memory (rust-analyzer, pyright on large projects) → `/plugin disable `; files-not-found → plugins are cached copies, so paths outside the plugin directory break. See [[syntheses/troubleshooting-checklist]]. ## Related Entities - [[entities/desktop-app]] — plugin manager UI; [[entities/claude-code-web]] — repo-declared plugins in cloud sessions; channels install as plugins - [[entities/github-actions]] / [[entities/gitlab-cicd]] — `plugin_marketplaces`/`plugins` inputs install plugins in CI - [[concepts/skills-system]], [[concepts/subagents-orchestration]], [[concepts/hooks-system]] — the component types plugins package - [[summaries/best-practices]], [[syntheses/extension-decision-guide]] --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion --- ### 2026-06-10 — [Initial compilation] - **Source/Trigger**: KB created via source-pipeline (create_kb.py + agent curation per RECIPE Phase 3, MEDIUM retention ring) - **Pages created**: full initial set — see index.md (concepts, entities, summaries incl. solved-issue casebooks, decision syntheses) - **Sources**: 177 provenance-stamped files in raw/ (llms.txt docs set, github docs/releases/issues, anthropic engineering post) - **Notes**: gaps recorded in index.md Gaps/TODO; casebook claims from open issues marked low-confidence --- title: "Best Practices for Claude Code" type: summary tags: [best-practices, context-management, prompting, workflows, foundational, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-best-practices-for-claude-code.md", "raw/web_community-best-practices-for-claude-code-claude-code-docs.md", "raw/llms_txt_doc-common-workflows.md"] --- # Best Practices for Claude Code Summary of Anthropic's official best-practices guide (docs page and the matching anthropic.com/engineering post — content is identical between the two sources) plus the common-workflows recipes. ## Key Points ### The governing constraint: the context window - Nearly every best practice derives from one fact: **the context window fills fast and LLM performance degrades as it fills**. The window holds every message, every file read, and every command output; one debugging session can consume tens of thousands of tokens. Manage it as your scarcest resource (`/context`, a custom status line, `/usage`). ### Give Claude a way to verify its work - Provide a check that returns pass/fail — tests, a build exit code, a linter, a diff-against-fixture script, or a screenshot comparison. Without it, "looks done" is the only stop signal and *you* become the verification loop. - Escalating ways to gate the stop: (1) ask for the check in the same prompt; (2) set it as a `/goal` condition re-checked every turn; (3) a **Stop hook** that blocks turn-end until the check passes (Claude Code overrides after 8 consecutive blocks); (4) a verification subagent or dynamic workflow where a fresh model tries to refute the result. - Have Claude **show evidence** (test output, command + result, screenshot) rather than asserting success. ### Explore → Plan → Implement → Commit - Use plan mode to separate research from execution: explore (read files, no changes), plan (press `Ctrl+G` to edit the plan in your editor), implement (switch out of plan mode, verify against the plan), commit/PR. - Skip planning for small, well-scoped fixes: "If you could describe the diff in one sentence, skip the plan." ### Prompt with specific context - Scope the task ("write a test for foo.py covering the logged-out edge case. avoid mocks"), point to sources (git history), reference existing patterns (name an exemplar file), describe the symptom + likely location + definition of fixed. - Provide rich content: `@file` references, pasted screenshots, URLs (allowlist frequent domains via `/permissions`), `cat error.log | claude`, or let Claude fetch what it needs. ### Configure your environment - **CLAUDE.md:** generated by `/init`, loaded every session. Keep it short (per-line test: "would removing this cause mistakes?"); bloated files cause Claude to ignore rules. Include: commands Claude can't guess, style rules that differ from defaults, test instructions, repo etiquette, env quirks, gotchas. Exclude anything Claude can read from code. Supports `@path/to/import`. Locations: `~/.claude/CLAUDE.md` (all sessions), `./CLAUDE.md` (checked in), `./CLAUDE.local.md` (gitignored), parent dirs (monorepo), child dirs (loaded on demand). Emphasis ("IMPORTANT", "YOU MUST") improves adherence. - **Permissions:** three ways to cut prompt fatigue — auto mode (classifier blocks only risky actions), `/permissions` allowlists (e.g. `npm run lint`), `/sandbox` OS-level isolation. See [[syntheses/permission-mode-picker]]. - **CLI tools beat MCP for context efficiency:** install `gh`, `aws`, `gcloud`, `sentry-cli`; Claude can also learn unknown CLIs via `--help`. - **MCP servers** (`claude mcp add`) for issue trackers, databases, Figma. - **Hooks** for actions that must happen every time with zero exceptions (deterministic, unlike advisory CLAUDE.md). Claude can write hooks for you: "Write a hook that runs eslint after every file edit." - **Skills** (`.claude/skills//SKILL.md`) for domain knowledge and repeatable workflows; `disable-model-invocation: true` for manually-triggered workflows with side effects. Invoke with `/fix-issue 1234` style arguments. - **Subagents** (`.claude/agents/*.md`) with their own tools/model for isolated, focused tasks. - **Plugins** (`/plugin`) bundle the above; code-intelligence plugins are recommended for typed languages. ### Communicate effectively - Ask codebase questions like you'd ask a senior engineer — best onboarding workflow, no special prompting. - For larger features, **let Claude interview you** using the AskUserQuestion tool, write a spec to SPEC.md, then execute in a *fresh* session with clean context. ### Manage your session - Course-correct early: `Esc` to stop mid-action; `Esc Esc` or `/rewind` to restore conversation/code state; "undo that"; `/clear` between unrelated tasks. - **Two-corrections rule:** if you've corrected Claude twice on the same issue, `/clear` and rewrite the initial prompt incorporating what you learned — a clean session with a better prompt beats a long session with accumulated corrections. - Compaction control: `/compact `; partial compaction via rewind menu ("Summarize from here" / "up to here"); CLAUDE.md compaction directives ("always preserve the list of modified files"); `/btw` for side questions that never enter history. - **Subagents for investigation:** "use subagents to investigate X" — exploration happens in a separate window, only the summary returns. Also for post-hoc review: "use a subagent to review this code for edge cases." - Checkpoints: every prompt creates one; restore conversation, code, or both; persists across sessions. Tracks only Claude's changes — **not a git replacement**. Enables "try something risky, rewind if it fails." - Resume: `claude --continue` (latest) / `claude --resume` (picker); `/rename` sessions like branches (`oauth-migration`). ### Automate and scale - `claude -p "prompt"` for CI/scripts; `--output-format json` or `stream-json --verbose` for parsing. - Parallel options: git worktrees (CLI), Desktop sessions (each in its own worktree), Claude Code on the web (isolated cloud VMs), agent teams (experimental). See [[syntheses/surface-picker]]. - Writer/Reviewer pattern across two sessions; fresh context makes the reviewer unbiased. - Fan-out: generate a file list, loop `claude -p "Migrate $file ... Return OK or FAIL." --allowedTools "Edit,Bash(git commit *)"`, test on 2–3 files before running at scale. - `claude --permission-mode auto -p "fix all lint errors"` for unattended runs with classifier safety checks; with `-p`, auto mode aborts on repeated blocks since no user can answer. - Adversarial review: subagent reviews the diff against PLAN.md in fresh context — but tell it to flag only correctness gaps, or it will invent findings and drive over-engineering. ### Five common failure patterns (and fixes) 1. **Kitchen-sink session** → `/clear` between unrelated tasks. 2. **Correcting over and over** → after two failures, `/clear` + better prompt. 3. **Over-specified CLAUDE.md** → ruthlessly prune; convert enforceable rules to hooks. 4. **Trust-then-verify gap** → always provide verification; if you can't verify it, don't ship it. 5. **Infinite exploration** → scope investigations or push them into subagents. ### Common-workflows recipes (companion doc) - Codebase orientation: broad overview → architecture → key data models → trace a flow ("trace the login process from front-end to database"). - Bug fixing: paste the exact error, name the likely location, ask for a failing test first. - The same recipes work on any surface (CLI, desktop, web). ## Relevant Concepts - [[concepts/memory-context]] — CLAUDE.md, context window, compaction - [[concepts/permissions-security]] — allowlists, auto mode, sandboxing - [[concepts/checkpointing]] — rewind and checkpoint mechanics - [[concepts/skills-system]] — SKILL.md format and invocation - [[concepts/subagents-orchestration]] — investigation and review subagents - [[concepts/hooks-system]] — deterministic automation - [[concepts/interactive-mode]] — Esc, `/btw`, keyboard-driven session control - [[syntheses/extension-decision-guide]] — which mechanism for which job - [[syntheses/cost-management]] — the cost side of context hygiene ## Source Metadata - **Type:** Official documentation (code.claude.com/docs/en/best-practices.md, common-workflows.md) and the Anthropic engineering blog mirror (anthropic.com/engineering/claude-code-best-practices); the blog and docs page carry identical content - **Author:** Anthropic - **Fetched:** 2026-06-10 --- title: "Casebook: Install, Node, Auth, and API Errors" type: summary tags: [troubleshooting, authentication, api-errors, installation, usage-limits, community] created: 2026-06-10 updated: 2026-06-10 confidence: medium sources: ["raw/github_issue-anthropic-api-overloaded-error-with-repeated-529-status-code.md", "raw/github_issue-anthropic-api-overloaded-repeated-529-errors-during-request.md", "raw/github_issue-anthropic-api-overloaded-repeated-529-errors-on-requests.md", "raw/github_issue-bug-anthropic-api-credential-restriction-preventing-api-requ.md", "raw/github_issue-bug-api-error-500-type-error-error-type-api-error-message-in.md", "raw/github_issue-bug-api-error-500.md", "raw/github_issue-bug-critical-widespread-abnormal-usage-limit-drain-across-al.md", "raw/github_issue-bug-claude-code-requires-node-js-version-18-or-higher-to-be-.md", "raw/llms_txt_doc-error-reference.md"] --- # Casebook: Install, Node, Auth, and API Errors Solved-problem casebook compiled from high-traffic GitHub issues (80–270+ comments each). Each case: verbatim symptom → cause → fix/workaround → issue ref. GitHub-issue-derived fixes are **medium confidence** unless corroborated by the official error reference; confidence is noted per case. ## Key Points ### Case 1 — Repeated 529 "Overloaded" errors **Symptom (verbatim):** ``` API Error (529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}) · Retrying in 1 seconds… (attempt 1/10) ``` Repeats with exponential backoff up to attempt 10/10. Affects all plans including Max 20x; not shown as an incident on the status page in the reported episodes. **Cause:** The API is at capacity across all users (server-side, per-model capacity). Not your quota — a 529 does not count against usage limits. Claude Code retries up to 10 times (`CLAUDE_CODE_MAX_RETRIES`, default 10) before surfacing the error. **Fix/workaround (officially confirmed — high confidence):** - Check https://status.claude.com for capacity notices. - Wait a few minutes and retry. - Run `/model` and switch models — capacity is tracked per model; Claude Code itself suggests e.g. "Opus is experiencing high load, please use /model to switch to Sonnet". - Since 2.1.166 you can set `fallbackModel` (up to three models tried in order) so overloads fail over automatically ([[summaries/changelog-digest]]). **Refs:** anthropics/claude-code#3572 (274 comments), #3633 (177), #3547 (103); official error reference. ### Case 2 — "This credential is only authorized for use with Claude Code" **Symptom (verbatim):** ``` API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"This credential is only authorized for use with Claude Code and cannot be used for other API requests."},"request_id":"req_011CTQmv1MVzrMnxDP9yRrLF"} ``` Appeared suddenly for many users on the same morning (2025-09-23); even `claude doctor` returned the 400. `claude setup-token` did **not** fix it. **Cause:** After Anthropic resolved a backend connectivity incident (status.anthropic.com incident xg2v4m4nc40n), some users' stored OAuth credentials needed re-authentication, but the error did not prompt for it. **Fix (community-verified by multiple confirmations — medium confidence):** Run `/login` (re-authenticate). "UPD: relogin helped" / "This worked for me. Just re-login." **Ref:** anthropics/claude-code#8046 (102 comments). ### Case 3 — API Error: 500 Internal server error **Symptom (verbatim):** ``` API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":null} ``` **Causes (several distinct ones observed):** 1. Server-side incident — "We had a brief increase in errors, this should be resolved now!" (Anthropic staff in #3127). Not caused by your prompt, settings, or account. 2. Context exhaustion edge: reported when remaining context hits exactly 0% and auto-compact failed to run in time (#3127). Regenerating the API token did not help; starting a new chat did. 3. Model-specific state: switching models made requests succeed (#9066). 4. One user with a legacy `~/.claude/local/claude` install recovered after removing `~/.claude`, clearing the shell alias, and reinstalling via `curl -fsSL https://claude.ai/install.sh | bash` (new binary at `~/.local/bin/claude`) — possibly coincident with backend recovery (low confidence). **Fix (official — high confidence):** Check status.claude.com; wait and retry (your message stays in the conversation — type `try again`); if persistent with no incident, `/feedback`. Community additions (medium): switch model via `/model`; start a new session if the old one errors at 0% context. **Refs:** anthropics/claude-code#3127 (121 comments), #9066 (84 comments); official error reference. ### Case 4 — Abnormal usage-limit drain (March 2026 incident) **Symptom:** Single prompts consuming 3–7% of session quota; 5-hour windows depleting in as little as 19 minutes; "hello" costing 2% of a Pro session; usage rising while idle. Affected Pro, Max 5x, Max 20x and also claude.ai web (shared usage pool). **Causes (community RCA, partially confirmed by Anthropic — medium confidence):** 1. **Intentional peak-hour throttling** (confirmed by Anthropic 2026-03-26): session limits drain faster weekdays 5am–11am PT. 2. **Prompt-caching bug A ("cch sentinel"):** the standalone (Bun-fork) binary string-replaces a billing sentinel (`cch=00000`, introduced v2.1.36) on every request; if conversation history mentions billing-related terms the replacement hits the wrong position, breaking the cache prefix → full uncached rebuild at 10–20x token cost (#40524). 3. **Prompt-caching bug B (resume):** `--resume`/`--continue` inject the `deferred_tools_delta` attachment (since v2.1.69) in a different position than fresh sessions, invalidating the entire conversation cache (#34629). One resume on a long session was measured at 500K+ tokens; #38029 documented 652,069 output tokens generated during a resume with no user prompts. 4. **Expiration of the 2x off-peak promotion** (2026-03-28) amplified the perceived drop. **Fixes/workarounds (community-verified — medium confidence):** - **Update to v2.1.90+** — benchmarked at 95–99% cache reads in stable sessions (vs near-zero during the regression). Affected range was roughly v2.1.69–v2.1.89. - During the regression: downgrade to v2.1.34, or run `npx @anthropic-ai/claude-code` instead of the standalone binary (avoids the Bun string-replacement bug). - Avoid `--resume`/`--continue` on long sessions while a resume cache bug is live; prefer `/clear` + a structured CLAUDE.md for carrying context. - Pin a known-good version: add `"DISABLE_AUTOUPDATER": "1"` to the `env` section of `~/.claude/settings.json`. - Monitor: if a single short message burns >3–5% of session, restart immediately; a local proxy via `ANTHROPIC_BASE_URL` or the script at `gitlab.com/treetank/cc-diag` can verify `cache_read` vs `cache_write` behavior. - Be aware of multipliers: multiple terminals drain in parallel; subagent Haiku calls were measured at 0% cache read; large CLAUDE.md files are resent every turn. **Ref:** anthropics/claude-code#41930 (108 comments; cross-refs #40524, #34629, #38029, #38335, #39649). See [[summaries/casebook-runtime]] Case 5 for the cache-invalidation mechanics. ### Case 5 — "Claude Code requires Node.js version 18 or higher" (false positive) **Symptom (verbatim):** `Claude Code requires Node.js version 18 or higher to be installed.` — shown even though `node --version` reports v18.20, v20.19, v22.16, or v24.9. **Cause:** Not actually a missing Node install. Reported almost exclusively from **IDE-integrated terminals** (VS Code, Cursor, including under WSL) where the extension environment resolves a different/embedded Node than the shell. Regression around v2.0.0. **Fix/workaround (community — medium confidence):** Run `claude` from a standalone terminal instead of the IDE's integrated terminal ("use it from the command line for now, don't use it in vscode like that" — confirmed working by multiple commenters). Native-installer builds (`curl -fsSL https://claude.ai/install.sh | bash`) don't depend on system Node at all. **Ref:** anthropics/claude-code#8410 (81 comments). ### Cross-case auth diagnostics (official — high confidence) - `/status` shows which credential is active. A stray `ANTHROPIC_API_KEY` in the environment **takes precedence over `/login`** and is a recurring root cause of 401/429/"organization disabled" errors. - `Invalid API key · Fix external API key` → check `env | grep ANTHROPIC`; direnv/dotenv/IDE terminals can load a stale key from a project `.env`. - `OAuth token revoked/expired` → `/login`; if it recurs in-session, `/logout` then `/login`. - `Your organization has disabled API key authentication` → unset `ANTHROPIC_API_KEY` or remove `apiKeyHelper`, then `/login`. ## Relevant Concepts - [[concepts/installation-setup]] — install methods, `claude doctor`, native installer vs npm - [[concepts/configuration]] — settings.json `env`, `DISABLE_AUTOUPDATER`, `fallbackModel` - [[syntheses/troubleshooting-checklist]] — ordered diagnostic sequence built from these cases - [[syntheses/cost-management]] — usage tracking and cache economics - [[summaries/casebook-runtime]] — compaction/runtime sibling casebook - [[summaries/changelog-digest]] — which version fixed what ## Source Metadata - **Type:** Community GitHub issues (anthropics/claude-code) #3572, #3633, #3547, #8046, #3127, #9066, #41930, #8410 plus the official error reference (code.claude.com/docs/en/errors.md) - **Dates:** Issues span 2025-07 → 2026-04; all fetched 2026-06-10 - **Confidence note:** per CURATION law, GitHub-issue fixes are medium confidence unless officially confirmed; official-doc recovery steps are high. --- title: "Casebook: Runtime, Compaction, Permissions, and Windows/WSL Problems" type: summary tags: [troubleshooting, compaction, permissions, windows, wsl, cowork, community] created: 2026-06-10 updated: 2026-06-10 confidence: medium sources: ["raw/github_issue-bug-error-during-compaction.md", "raw/github_issue-critical-context-auto-compact-stuck-at-0-tool-unusable.md", "raw/github_issue-bug-auto-compact-not-triggering-on-claude-ai-web-desktop-des.md", "raw/github_issue-bug-claude-continually-asks-for-permission-even-after-select.md", "raw/github_issue-bug-conversation-history-invalidated-on-subsequent-turns.md", "raw/github_issue-bug-file-named-nul-created-on-windows.md", "raw/github_issue-bug-claude-code-does-not-detect-jetbrains-ide-on-windows-wsl.md", "raw/github_issue-bug-cowork-cannot-use-folders-outside-home-directory-on-wind.md", "raw/github_issue-bug-cowork-folder-picker-rejects-folders-outside-home-direct.md", "raw/github_issue-bug-cowork-shows-virtualization-is-not-enabled-on-windows-10.md", "raw/github_issue-bug-cowork-windows-cannot-connect-to-claude-api-from-workspa.md", "raw/github_issue-bug-oversized-image-breaks-conversation-permanently-no-way-t.md", "raw/llms_txt_doc-error-reference.md", "raw/llms_txt_doc-jetbrains-ides.md"] --- # Casebook: Runtime, Compaction, Permissions, and Windows/WSL Problems Solved-problem casebook from high-traffic GitHub issues. Each case: verbatim symptom → cause → fix/workaround → issue ref. Issue-derived fixes are **medium confidence** unless officially confirmed. ## Key Points ### Case 1 — "Error during compaction: Conversation too long" **Symptom (verbatim):** ``` Error during compaction: Error: Conversation too long. Press esc twice to go up a few messages and try again. ``` Could fire even at ~25% context during a buggy period (v1.0.111); for some users "esc twice" didn't help either. **Cause (official):** `/compact` itself needs free context to hold the summary it produces. The error occurs when the window is already full at the moment auto-compact triggers, or when you run `/compact` after `Prompt is too long`. The aggravated v1.0.111-era behavior was a regression fixed around v1.0.113. **Fix (official — high confidence):** 1. Press `Esc` twice to open the message list and step back several turns (drops the most recent messages from context), then run `/compact` again. 2. If that doesn't free enough space, `/clear` — the old conversation stays on disk and reopens via `/resume`. **Ref:** anthropics/claude-code#7530 (134 comments); official error reference. ### Case 2 — "Context left until auto-compact: 0%" immediately, tool unusable **Symptom (verbatim):** `Context left until auto-compact: 0%` persistently, minutes after starting a session, even on small codebases. `/clear`, reinstall, and deleting `~/.claude` did not fix; microcompact didn't help; users also saw back-to-back compaction loops. **Cause:** Context-accounting bug (duplicate cluster: #1168, #2283, #3375, #4660). A contributing pattern visible in one transcript: post-compact file re-reads (five 885-line JSON files) plus a 1,000+-line MCP tool result instantly refilled the window — large MCP outputs and bulk file reads make any accounting bug fatal. **Fix/workaround (medium confidence):** Resolved by later releases; meanwhile, reduce per-turn context bulk (avoid huge MCP tool results, scope reads), and use `/clear` plus fresh sessions rather than fighting compaction. Check `/context` to see what's consuming the window. **Ref:** anthropics/claude-code#5385 (98 comments). ### Case 3 — Auto-compact not triggering on Claude.ai web & desktop **Symptom:** At the context limit, the message silently bounces back to the input box (no error), or occasionally "limit reached". Auto-compact never runs. Broken since the 2026-01-14 outage, persisting after being marked fixed on 2026-01-15. **Cause:** Regression in the claude.ai web/desktop compaction implementation (distinct from the CLI's compaction path). **Fix/workaround (community — medium confidence):** Compact manually when you see "limit reached" and ask the model to continue; or start a new chat and use `conversation_search` to restore context. CLI sessions were not affected the same way — for long-form work, the CLI was the workaround. **Ref:** anthropics/claude-code#18866 (176 comments; duplicate #18482). ### Case 4 — Permission re-prompt loop ("Yes, always allow" not remembered) **Symptom (verbatim):** ``` Read file Read(AP-Cleanup-Documentation.md) Do you want to proceed? ❯ 1. Yes 2. Yes, during this session 3. No, and tell Claude what to do differently (esc) ``` Re-asks for the same action repeatedly despite allow rules in global/project settings. Heavily reported on Windows (v2.0.36+). **Causes (multiple, from triage across 82 comments):** 1. **Windows path-format bug:** permission rules spelled with backslashes (`~\`, `\\server\share`) or case-variant paths never matched — officially fixed in **2.1.162** ([[summaries/changelog-digest]]). 2. **UNC/network paths:** rules didn't match network resources like `\\10.0.0.10\files\claude`; mapping the share to a drive letter fixed it (medium confidence). 3. **Settings-file precedence confusion:** one user's project `.claude/settings.json` permissions had no effect until duplicated as `.claude/settings.local.json` (medium confidence). 4. **General-purpose subagents** not inheriting session approvals, while named subagents with their own permissions behaved (medium confidence). **Fix/workaround:** Update to ≥2.1.162 on Windows; use forward-slash/glob rule syntax (e.g. `Read(**)`); map network drives; if rules in `settings.json` seem ignored, mirror them in `settings.local.json`. Last-resort `"defaultMode": "bypassPermissions"` in `~/.claude/settings.json` works but removes the safety layer — see [[syntheses/permission-mode-picker]] before doing this. **Ref:** anthropics/claude-code#11380 (82 comments; duplicates #10629, #11172, #7161). ### Case 5 — Conversation history invalidated on subsequent turns (cache destruction) **Symptom:** Token usage explodes; usage logs show `cache_read` collapsing to ~11K (system prompt only) with six-figure `cache_creation` writes, especially after `--resume`: ``` 07:55:55 0 0 8 1 haiku-4-5 max_tokens <-- resume 07:56:22 11428 163547 3 143 opus-4-6 tool_use <-- partial cache regenerate 07:57:25 11428 307626 3 87 opus-4-6 end_turn <-- full cache regenerate ``` **Cause (community reverse-engineering, methodology incl. Ghidra + MITM proxy; Anthropic confirmed investigating):** - **Sentinel bug:** the standalone binary string-replaces the `cch=00000` billing sentinel on every request; if message history contains billing-like text, the replacement corrupts the cache prefix from that point on. - **Resume bug:** the `deferred_tools_delta` attachment (v2.1.69+) makes `messages[0]` differ between fresh and resumed sessions, independently breaking prefix matching (#34629). **Fix/workaround (medium confidence):** Update to v2.1.90+ (95–99% cache reads benchmarked); avoid `--resume` on affected versions; one user additionally needed `"env": {"ENABLE_TOOL_SEARCH": "false"}` (anecdotal — low confidence). Full economics in [[summaries/casebook-install-auth]] Case 4. **Ref:** anthropics/claude-code#40524 (124 comments). ### Case 6 — File named `nul` created on Windows **Symptom:** A file literally named `nul` appears in the working directory (v1.0.62–1.0.95 era). It can't be deleted by normal means and "borks Git commits". **Cause:** Unix-style `>/dev/null` redirection emitted on Windows, where `nul` becomes a literal filename (intermittent; `nul` is a reserved device name so Explorer/del can't remove it). **Fix/workaround (community — medium confidence):** Delete via the extended-path prefix: ``` del "\\?\C:\myfolder\nul" ``` (Workaround of last resort seen in the thread: add to a 7-Zip archive with "delete after compression".) **Ref:** anthropics/claude-code#4928 (184 comments; duplicates #4206, #3839, #4535). ### Case 7 — JetBrains IDE not detected from WSL **Symptom (verbatim):** `/ide` returns `No available IDEs detected. Make sure your IDE has the Claude Code extension or plugin installed and is running.` — Claude Code installed in WSL2, JetBrains plugin installed on Windows. **Cause (official docs):** WSL2's NAT networking or Windows Firewall blocks the connection between WSL2 and the IDE on the Windows host. WSL1 uses the host network directly and isn't affected. **Fix/workaround (official — high confidence):** - Allow the IDE/plugin port through Windows Firewall, or use WSL1 for this workflow. - In the JetBrains plugin settings, set the Claude command to `wsl -d Ubuntu -- bash -lic "claude"` (substitute your distro). - For JetBrains Remote Development, the plugin must be installed on the **remote host** (Settings → Plugin (Host)), not the local client. - Run `claude` from the IDE's integrated terminal, started at the project root, so the integration auto-activates. **Ref:** anthropics/claude-code#1232 (113 comments); JetBrains IDE docs page. ### Case 8 — Cowork (Desktop) on Windows: three launch blockers **8a. Folder picker rejects anything outside the home directory.** Verbatim: `Invalid Folder Selection — The selected folder is outside your home directory. Only folders within your home directory can be used.` Cause: Cowork validates against `os.homedir()` after `fs.realpath()` resolution, so secondary drives (`D:\Projects`), redirected Known Folders (Documents on another drive), **and symlink/junction workarounds all fail** (the link resolves back to the real path). Affects macOS external volumes too. Status: no working user-side workaround in-thread; keep projects under `C:\Users\\...` for Cowork, or use Claude Code CLI/Desktop Code tab which have no such restriction. (#29583, 96 comments; #24964, 157 comments) **8b. "Virtualization is not enabled" despite Hyper-V fully enabled.** Verbatim: `Virtualization is not enabled. Claude's workspace requires hardware virtualization (Hyper-V). Enable virtualization in your computer's BIOS/UEFI settings, then restart.` Cause: false detection — logs show `yukonSilver not supported (status=unsupported)` and `[startVM] VM not supported (win32/x64), skipping` even when `systeminfo` confirms "A hypervisor has been detected". Hit Windows 10 Pro and some Windows 11 machines on older CPUs; BIOS/Windows-feature changes don't help because the gate is in the app's own support matrix. (#27316, 82 comments) **8c. "Cannot connect to Claude API from workspace" (Windows 11 Home and Pro).** The Cowork VM starts but can't reach api.anthropic.com; regular Chat works in the same app. Fix that worked for several users (medium confidence): **change the network adapter's DNS to public resolvers (primary 1.1.1.1, secondary 8.8.8.8) and restart Claude Desktop** — points to DNS resolution inside the VM path. Also seen: full Windows restart clears a `VM service not running` follow-up error. Installing WSL2 changed the error from "no network" to "cannot connect", confirming a network-path issue. (#24918, 107 comments) ### Case 9 — Oversized image permanently breaks the conversation **Symptom (verbatim):** ``` API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.100.content.2.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"},"request_id":"req_011CVwMREcResPJWSbJmcuri"} ``` After one oversized paste, **every** subsequent message — even plain text — fails with the same 400, because the image stays in history. **Cause:** No client-side dimension validation before adding the image; the API limit is 8000px (single image) / 2000px (many-image requests). **Fix (official — high confidence):** Fixed in **v2.1.142+**: the unprocessable image is replaced with a text placeholder and the request retried. On older versions: press `Esc` twice and step back past the turn where the image was added (`/compact` sometimes worked, sometimes re-errored). Prevent by resizing screenshots below 2000px before pasting. **Ref:** anthropics/claude-code#13480 (110 comments; duplicates #12351, #12867, #13341); official error reference. ## Relevant Concepts - [[concepts/memory-context]] — context window, compaction, `/context`, `/clear` - [[concepts/permissions-security]] — permission rules syntax and matching - [[concepts/checkpointing]] — `Esc Esc` / `/rewind` recovery used in several cases - [[entities/desktop-app]] — Cowork cases 8a–8c - [[entities/ide-extensions]] — JetBrains/WSL case 7 - [[syntheses/troubleshooting-checklist]] — ordered diagnostic flow built on this casebook - [[summaries/casebook-install-auth]] — auth/API sibling casebook - [[summaries/changelog-digest]] — version fixes (2.1.142 image, 2.1.162 Windows paths) ## Source Metadata - **Type:** Community GitHub issues (anthropics/claude-code) #7530, #5385, #18866, #11380, #40524, #4928, #1232, #29583, #24964, #27316, #24918, #13480, plus official error reference and JetBrains IDE docs - **Dates:** 2025-06 → 2026-02 (issues); fetched 2026-06-10 - **Confidence note:** official-doc recovery steps high; community workarounds medium; single-user anecdotes flagged low inline. --- title: "Changelog Digest: Recent Claude Code Releases" type: summary tags: [releases, versions, changelog, features, well-established] created: 2026-06-10 updated: 2026-06-10 confidence: high claude_code_version: "2.1.172" sources: ["raw/github_doc-changelog-md.md", "raw/llms_txt_doc-claude-code-changelog.md", "raw/github_release-v2-1-156.md", "raw/github_release-v2-1-157.md", "raw/github_release-v2-1-158.md", "raw/github_release-v2-1-159.md", "raw/github_release-v2-1-160.md", "raw/github_release-v2-1-161.md", "raw/github_release-v2-1-162.md", "raw/github_release-v2-1-163.md", "raw/github_release-v2-1-165.md", "raw/github_release-v2-1-166.md", "raw/github_release-v2-1-167.md", "raw/github_release-v2-1-168.md", "raw/github_release-v2-1-169.md", "raw/github_release-v2-1-170.md", "raw/github_release-v2-1-172.md"] --- # Changelog Digest: Recent Claude Code Releases ## Key Points - **Current latest version: 2.1.172** (released 2026-06-10). Run `claude --version` to check your installed version; the official changelog lives at `CHANGELOG.md` in the `anthropics/claude-code` GitHub repo and is mirrored at code.claude.com/docs/en/changelog. - The covered window (2.1.156 → 2.1.172) spans 2026-05-29 through 2026-06-10 — roughly one release per day, so pinning behavior to an exact version matters when troubleshooting. ### Notable features by version **2.1.172** (latest, 2026-06-10) - Sub-agents can now spawn their own sub-agents, up to 5 levels deep. - Amazon Bedrock reads the AWS region from `~/.aws` config when `AWS_REGION` isn't set (AWS SDK precedence); `/status` shows where the region came from. - Fixed `WebFetch(domain:*.example.com)` wildcard domain rules never matching subdomains, and mid-pattern file wildcards like `Read(secrets-*/config.json)` being rejected at startup. - Fixed model IDs getting a doubled 1M-context suffix (e.g. `[1M][1m]`) when `ANTHROPIC_DEFAULT_OPUS_MODEL` already includes one; fixed `opusplan` not shipping 1M context in plan mode. - Fixed sessions on 1M context without usage credits getting permanently stuck (now auto-compacts back under the standard limit). - Search bar added to `/plugin` marketplace browsing; performance work on long conversations and idle CPU. **2.1.170** (2026-06-09) - **Introduced Claude Fable 5**, a Mythos-class model; update to 2.1.170+ for access. - Fixed sessions not saving transcripts (and missing from `--resume`) when launched from the VS Code integrated terminal or a shell that inherited Claude Code env vars. **2.1.169** (2026-06-08) - Added `--safe-mode` flag (and `CLAUDE_CODE_SAFE_MODE`) to start with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled — the go-to troubleshooting bisect tool. - Added `/cd` to move a session to a new working directory without breaking the prompt cache. - Added `disableBundledSkills` setting / `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` env var. - Self-hosted runner gained a `post-session` lifecycle hook (runs after session end, before workspace deletion). - "CLAUDE.md is too long" warning threshold now scales with the model's context window. **2.1.166** (2026-06-05) - Added `fallbackModel` setting: up to three fallback models tried in order when the primary is overloaded/unavailable; `--fallback-model` now applies to interactive sessions too. - Glob support in deny-rule tool-name position (`"*"` denies all tools). - `MAX_THINKING_TOKENS=0`, `--thinking disabled`, and the per-model toggle now disable thinking on models that think by default (Claude API). - Hardened cross-session messaging: relayed `SendMessage` requests no longer carry user authority. - Fixed JetBrains terminal flickering on 2026.1+ via synchronized output. **2.1.163** (2026-06-03) - Added `requiredMinimumVersion` / `requiredMaximumVersion` managed settings (refuses to start outside the allowed range). - Added `/plugin list` with `--enabled`/`--disabled` filters. - Stop and SubagentStop hooks can return `hookSpecificOutput.additionalContext` to keep the turn going without being labeled a hook error. - Fixed Windows Bash commands failing with `EEXIST: file already exists` on read-only/OneDrive session-env directories. **2.1.162** (2026-06-02) - Fixed Windows permission rules never matching when spelled with backslashes (`~\`, `\\server\share`) or case-variant paths — a long-standing cause of permission re-prompt loops on Windows (see [[summaries/casebook-runtime]]). - Explicit `WebFetch(domain:...)` deny/ask/allow rules now take precedence over preapproved-host auto-allow. - Quieter startup; failed turns show a compact warning instead of a multi-line red block. **2.1.161** (2026-06-02) - `OTEL_RESOURCE_ATTRIBUTES` values included as metric labels (slice usage by team/repo). - A failed Bash command in a parallel batch no longer cancels the other calls. - `claude mcp` list/get/add no longer prints secrets (`${VAR}` unexpanded; credential headers redacted). **2.1.160** (2026-05-31) - Security hardening: prompt before writing to shell startup files (`.zshenv`, `.zlogin`, `.bash_login`) and `~/.config/git/`; `acceptEdits` mode now prompts before writing build-tool configs that grant code execution (`.npmrc`, `.yarnrc*`, `bunfig.toml`, `.bazelrc`, `.pre-commit-config.yaml`, `.devcontainer/`). - Single-file `grep` now satisfies the read-before-edit check. - Dynamic-workflow trigger keyword renamed from `workflow` to `ultracode`. **2.1.158** (2026-05-30) - Auto mode available on Bedrock, Vertex, and Foundry for Opus 4.7/4.8 — opt in with `CLAUDE_CODE_ENABLE_AUTO_MODE=1`. **2.1.157** (2026-05-29) - Plugins in `.claude/skills` directories auto-load, no marketplace required; `claude plugin init ` scaffolds a plugin. - `EnterWorktree` can switch between Claude-managed worktrees mid-session. - Fixed unprocessable images (zero-byte, corrupt) crashing the request instead of becoming a text placeholder. **2.1.156** (2026-05-29) - Fixed Opus 4.8 thinking blocks being modified, which led to API errors. (2.1.159 = internal infra only; 2.1.165, 2.1.167, 2.1.168 = "bug fixes and reliability improvements"; 2.1.164 and 2.1.171 were not published as releases.) ## Relevant Concepts - [[concepts/installation-setup]] — `claude update`, version checks, `--safe-mode` - [[concepts/configuration]] — new settings keys (`fallbackModel`, `disableBundledSkills`, `requiredMinimumVersion`) - [[concepts/permissions-security]] — Windows path-rule fixes, WebFetch wildcard rules, acceptEdits hardening - [[concepts/subagents-orchestration]] — nested sub-agents (5 levels), agents-view fixes - [[concepts/hooks-system]] — Stop/SubagentStop `additionalContext`, post-session hook - [[concepts/enterprise-deployment]] — managed version pinning, Bedrock/Vertex auto mode - [[summaries/casebook-runtime]] — several casebook issues resolved in this window ## Source Metadata - **Type:** Official release notes — GitHub `CHANGELOG.md`, GitHub Releases v2.1.156–v2.1.172, and the docs-site changelog mirror - **Author:** Anthropic (anthropics/claude-code) - **Dates:** Releases published 2026-05-29 → 2026-06-10; all fetched 2026-06-10 - **URLs:** https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md ; https://code.claude.com/docs/en/changelog.md --- title: "Cost Management: Model Selection, Fast Mode, Context Hygiene, and Tracking" type: synthesis tags: [decision-guide, costs, tokens, fast-mode, caching, tracking] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-manage-costs-effectively.md", "raw/llms_txt_doc-track-cost-and-usage.md", "raw/llms_txt_doc-speed-up-responses-with-fast-mode.md", "raw/llms_txt_doc-best-practices-for-claude-code.md", "raw/github_issue-bug-critical-widespread-abnormal-usage-limit-drain-across-al.md"] --- # Cost Management: Model Selection, Fast Mode, Context Hygiene, and Tracking Baseline from official docs: enterprise average ≈ **$13/developer/active day** and **$150–250/developer/month**, with 90% of users under $30/day. Token cost scales with context size, so most levers are context levers. ## Comparison ### Lever-by-lever | Lever | Mechanism | Typical impact | Cost of using it | |---|---|---|---| | Model selection (`/model`, `/config` default) | Sonnet for most coding; Opus for architecture/multi-step reasoning; `model: haiku` for simple subagents | Largest single multiplier | Possible quality loss on hard tasks | | Effort / thinking (`/effort`, `MAX_THINKING_TOKENS=8000`, disable in `/config`) | Thinking tokens bill as output; default budgets can be tens of thousands per request | Big on output-heavy sessions | Lower quality on complex planning; adaptive-reasoning models ignore nonzero budgets (use effort levels); Fable 5 can't disable thinking | | Fast mode (`/fast`) | Same Opus quality, up to 2.5x faster, **higher $/token**: $10/$50 per MTok in/out on Opus 4.8; $30/$150 on 4.7/4.6 | Negative for cost — it's a latency lever | Draws from **usage credits only** (never plan limits); first enable in a conversation pays full uncached input for the whole context — enable at session start, once per conversation | | Context hygiene (`/clear`, `/compact `, partial summarize via rewind, `/btw`) | Stale context is resent every message | Compounding; also improves quality | Discipline only | | CLAUDE.md diet / skills offload | CLAUDE.md is paid every request; skills load on demand | Steady per-message savings | Keep CLAUDE.md <200 lines | | Subagent delegation | Verbose ops (tests, logs, doc fetches) stay in the subagent's window; summary returns | Large on research-heavy work | Subagent tokens still bill; watch their cache behavior | | MCP/CLI choices | Tool schemas deferred by default; CLI tools (`gh`, `aws`) have zero per-tool listing; `/mcp` disable unused | Moderate | — | | Hooks preprocessing | e.g. PreToolUse hook rewrites `npm test` to `… | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100` | Turns 10k-line outputs into hundreds of tokens | Hook authoring | | Prompt caching | Automatic; repeated prefixes at reduced rate. SDK/API-key TTL = 5 min; `ENABLE_PROMPT_CACHING_1H=1` for 1-hour TTL (higher write rate); subscribers get 1h automatically | Foundational — when it breaks, costs inflate 10–20x (March 2026 incident) | 1h writes cost more; only pays off with >5-min gaps | | Agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) | Each teammate is a full instance; ~7x tokens of a standard session in plan mode | Negative — a spend amplifier to manage | Use Sonnet teammates, small teams, focused spawn prompts, clean up idle teammates | ### Tracking options | Tool | What it gives | Authority | |---|---|---| | `/usage` | Session tokens + estimated $; plan-limit bars; attribution of usage to skills/subagents/plugins/MCP servers (press `d`/`w` for 24h/7d) | Local estimate; excludes other devices/claude.ai | | `/usage-credits` | Monthly spend limit on usage credits (Pro/Max); raise/remove without leaving CLI | Billing-backed | | Status line / `/context` | Continuous context-usage display; window breakdown | Local | | Claude Console (workspace "Claude Code") | Workspace spend limits, admin cost reporting, per-workspace rate caps | **Authoritative billing** | | Agent SDK: `total_cost_usd`, per-step `usage`, `modelUsage` | Programmatic per-call/per-model tracking; dedupe parallel-tool messages by message ID | Client-side estimate — explicitly *not* billing data; use the Usage & Cost API or Console for invoicing | | Bedrock/Vertex/Foundry | No metrics sent from your cloud; enterprises commonly use LiteLLM to track spend by key (unaffiliated, unaudited) | Provider-side | ## Analysis - **Cache health dominates everything else.** Cached reads vs uncached rebuilds is a 10–20x cost swing — the March 2026 usage-drain incident showed exactly that when client bugs broke prefix caching ([[summaries/casebook-install-auth]] Case 4). Practical implication: keep prefixes stable (don't churn CLAUDE.md mid-session), stay on a current version, and if quota drains feel anomalous, check `cache_read` vs `cache_creation` before blaming usage. - **Fast mode is mislabeled as a cost feature — it's a deadline feature.** Same model, higher unit price, separate rate-limit pool, credits-only billing for subscribers. The one cost rule it carries: enabling mid-conversation re-pays uncached input for the entire context, once per conversation. - **The cheapest token is the one never sent.** Hooks that filter output, code-intelligence plugins that replace grep-and-read-five-files with one symbol lookup, CLI tools over MCP, and specific prompts ("add input validation to the login function in auth.ts" vs "improve this codebase") all act before the context bill accrues. - **Plan-quality habits are cost habits.** Plan mode, early course-correction (Esc, `/rewind`), incremental testing, and verification targets all prevent the most expensive token category: re-work down a wrong path. - **Background usage exists but is noise:** summarization for `--resume` and command processing, typically under $0.04/session. - **Team sizing:** TPM-per-user recommendations fall from 200k–300k (1–5 users) to 10k–15k (500+), because concurrency drops with scale; limits apply at org level, so individuals can burst. ## Recommendations - **Individual daily defaults:** Sonnet default + Opus on demand; `/clear` between tasks (`/rename` first); status line showing context; `/usage` weekly to see which skills/MCP servers eat your plan. - **When a session feels expensive, in order:** `/context` (what's loaded?) → `/mcp` disable unused → prune CLAUDE.md → move workflows to skills → delegate verbose ops to subagents. - **Latency-critical day:** `/fast` at session start (not mid-conversation), optionally with lower `/effort` for straightforward tasks; toggle off when the deadline passes. - **Automation/SDK:** read `total_cost_usd` from every result message (success *and* error — failed runs still billed); dedupe assistant messages by ID; set `ENABLE_PROMPT_CACHING_1H=1` for short sessions with >5-min gaps against the same prompt; never invoice end users from client-side estimates. - **Team admins:** pilot small to baseline before rollout; set workspace spend limits and a workspace rate cap so Claude Code can't starve production API workloads; `fastModePerSessionOptIn: true` in managed settings if concurrent-session fast-mode spend is a worry; agent teams stay disabled unless someone owns their budget. ## Pages Compared - [[concepts/memory-context]] - [[concepts/configuration]] - [[concepts/subagents-orchestration]] - [[concepts/mcp-integration]] - [[concepts/hooks-system]] - [[concepts/agent-sdk]] - [[summaries/best-practices]] - [[summaries/casebook-install-auth]] - [[syntheses/extension-decision-guide]] --- title: "Extension Decision Guide: Skill vs Slash Command vs Hook vs MCP vs Subagent vs Plugin vs Agent SDK" type: synthesis tags: [decision-guide, skills, hooks, mcp, subagents, plugins, agent-sdk, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-extend-claude-code.md", "raw/llms_txt_doc-best-practices-for-claude-code.md", "raw/llms_txt_doc-manage-costs-effectively.md", "raw/llms_txt_doc-track-cost-and-usage.md", "raw/llms_txt_doc-configure-permissions.md", "raw/github_doc-changelog-md.md"] --- # Extension Decision Guide: Which Mechanism for Which Job Claude Code's extension mechanisms plug into different parts of the agentic loop. The official docs' framing: CLAUDE.md = always-on context, skills = on-demand knowledge/workflows, MCP = external connections, subagents = isolation, hooks = event automation, plugins = packaging, Agent SDK = build your own product on the same engine. Note on slash commands: in current Claude Code, a user-invoked skill **is** the slash command (`/deploy` invokes `.claude/skills/deploy/SKILL.md`). "Slash command" below means a skill with `disable-model-invocation: true` — invocable only by you, invisible to the model, zero context cost until used. (Legacy `.claude/commands/` files still load; same decision logic applies.) ## Comparison | Mechanism | What it is | Trigger | Determinism | Context cost | Reach | |---|---|---|---|---|---| | **CLAUDE.md** | Persistent instructions | Every session, automatically | Advisory — model interprets | Full content, every request | Project/user | | **Skill** (model-invocable) | Markdown knowledge or workflow | `/` or Claude matches description | Model-interpreted | Description every request; body when used | Project/user/plugin | | **Skill as slash command** (`disable-model-invocation: true`) | Manual workflow, often with side effects | You type `/ [args]` | You control trigger; model executes steps | **Zero until invoked** | Project/user/plugin | | **Hook** | Script / HTTP request / prompt / subagent bound to a lifecycle event | Events: PreToolUse, PostToolUse, Stop, SessionStart, PermissionDenied, … | **Guaranteed** — always fires on its event | Zero unless it returns output | Settings (user/project/managed) | | **MCP server** | Protocol connection to an external service (tools + auth) | Claude calls its tools | Tool execution deterministic; invocation model-chosen | Tool names at start; schemas deferred (tool search on by default) | Local/project/user scopes | | **Subagent** | Isolated worker with own context, tools, model | You ask, or main agent delegates | Model-driven | Isolated; only summary returns | Project/user/CLI/plugin | | **Plugin** | Bundle of skills + hooks + subagents + MCP servers | Installed via `/plugin` or auto-loaded from `.claude/skills` (v2.1.157+) | Inherits components' semantics | Sum of components | Distributable via marketplaces | | **Agent SDK** (TS/Python) | Library to run the Claude Code engine inside your own application | Your code calls `query()` | Programmatic: `allowedTools`, `permissionMode`, `canUseTool`, hooks | Your app's concern | Standalone products, services, pipelines | ## Analysis - **Determinism is the sharpest dividing line.** "Never edit `.env`" in CLAUDE.md or a skill is a request; a PreToolUse hook that blocks the edit is enforcement. Official rule: *put guardrails in hooks*, knowledge in skills, conventions in CLAUDE.md. - **Context economics differ by mechanism.** CLAUDE.md is paid on every request (keep under 200 lines; the docs warn bloated files cause rule-ignoring). Skills amortize: description-only until used. MCP is cheap-until-used thanks to deferred schemas, but CLI tools (`gh`, `aws`) are cheaper still — no per-tool listing at all. Hooks can *reduce* context (e.g. a PreToolUse hook that filters test output to failures before Claude reads it). - **MCP and skills are complements, not rivals.** MCP provides the connection (database, Slack, browser); a skill teaches Claude *how to use it well* (schema, query patterns, message formats). - **Skills vs subagents = content vs container.** A skill is reusable content loadable into any context; a subagent is an isolated execution context. They combine: subagents preload skills via `skills:`, and a skill can run isolated via `context: fork`. - **Layering/precedence:** CLAUDE.md is additive across levels; skills and subagents override by name (managed > user > project for skills); MCP overrides by name (local > project > user); hooks merge — all registered hooks fire. - **The official trigger table is the best adoption heuristic** — add mechanisms reactively, not up front (see Recommendations). - **Agent SDK is a different altitude.** Reach for it when Claude Code is a component of *your* product rather than your dev tool: it exposes the permission evaluation chain programmatically (hooks → deny → ask → mode → allow → `canUseTool`), per-step/per-model cost tracking, and session control. Don't use the SDK for things a skill or hook solves inside Claude Code. ## Recommendations Pick by trigger (the docs' "build your setup over time" table, extended): - Claude gets a convention or command wrong twice → **CLAUDE.md** line. - You keep typing the same starting prompt, or paste the same playbook a third time → **skill**. - The workflow has side effects (deploy, release, billing) and must only run when *you* say so → **skill with `disable-model-invocation: true`** (pure slash command). - Something must happen every time, with zero exceptions (lint after edit, block writes to `migrations/`, Slack on session end) → **hook**. - You keep copying data from a browser tab Claude can't see (Jira, Figma, your DB) → **MCP server** — but check first whether a CLI tool covers it more cheaply. - A side task floods your conversation with output you won't reference again, or research reads dozens of files → **subagent** (since 2.1.172 subagents can nest 5 levels for deep fan-out). - A second repository needs the same setup, or you want to distribute to others → **plugin** (+ marketplace). - You're building an autonomous service, CI bot, or product with its own UI/permission UX → **Agent SDK**. Anti-patterns to avoid: reference manuals living in CLAUDE.md (move to skills); enforcement rules living in prompts (move to hooks); an MCP server for something `gh` already does; subagents for tasks whose intermediate output you actually need to see. ## Pages Compared - [[concepts/skills-system]] - [[concepts/hooks-system]] - [[concepts/mcp-integration]] - [[concepts/subagents-orchestration]] - [[concepts/agent-sdk]] - [[concepts/memory-context]] - [[entities/plugin-marketplaces]] - [[entities/agent-sdk-typescript]] - [[entities/agent-sdk-python]] - [[summaries/best-practices]] - [[syntheses/cost-management]] --- title: "Permission Mode Picker: Default, AcceptEdits, Plan, Auto, DontAsk, Bypass, and Sandboxing" type: synthesis tags: [decision-guide, permissions, security, auto-mode, sandboxing, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-configure-permissions.md", "raw/llms_txt_doc-configure-auto-mode.md", "raw/llms_txt_doc-desktop-application.md", "raw/llms_txt_doc-best-practices-for-claude-code.md", "raw/llms_txt_doc-error-reference.md", "raw/github_issue-bug-claude-continually-asks-for-permission-even-after-select.md", "raw/github_doc-changelog-md.md"] --- # Permission Mode Picker Permission modes set the *global* posture; allow/ask/deny rules and hooks refine it. Evaluation order (same engine across CLI, Desktop, SDK): **hooks → deny rules → ask rules → permission mode → allow rules → prompt/`canUseTool`**. Two consequences worth memorizing: deny rules and explicit ask rules bind **even in bypassPermissions**, and allow-rule lists do **not** constrain bypass mode (unlisted tools are still auto-approved by the mode). ## Comparison | Mode | Behavior | Risk profile | Use when | |---|---|---|---| | `default` ("Ask permissions") | Prompts for anything not pre-approved; you see each diff/command | Lowest risk, highest interruption; approval fatigue is real ("after the tenth approval you're just clicking through") | New users, unfamiliar repos, sensitive codebases | | `plan` | Read-only exploration + plan proposal; file edits are **never** auto-approved, even with matching allow rules | Minimal — write operations can't slip through | Complex/multi-file tasks, code review, approach-first work; the Explore→Plan→Code workflow | | `acceptEdits` ("Auto accept edits") | Auto-approves Edit/Write and filesystem commands (`mkdir`, `touch`, `rm`, `mv`, `cp`, `sed`) **inside the working dir/additionalDirectories only**; other Bash still prompts | Medium: bad edits are recoverable via checkpoints/git; since 2.1.160 it re-prompts for build-tool configs that grant code execution (`.npmrc`, `.bazelrc`, `.pre-commit-config.yaml`, `.devcontainer/`…) | Trusted iteration, prototyping, isolated directories | | `auto` (research preview) | A classifier model reviews each action; blocks scope escalation, unknown infrastructure, hostile-content-driven actions; routine work proceeds unprompted. Reads/searches/edits in the working dir skip the classifier | Medium-low, *configurable*: trusts only the working repo + remotes until you extend `autoMode.environment`. Failure mode is over-blocking, not under-blocking; classifier outages fall back to manual prompts (or abort in `-p`) | "I trust the direction, not every step"; long semi-attended runs; `claude --permission-mode auto -p "fix all lint errors"` | | `dontAsk` (CLI/SDK only) | Anything not pre-approved by allow rules/hooks is **denied** — never prompts | Hard-bounded surface; silent denials can confuse the model | Headless agents wanting a fixed explicit tool surface: `allowedTools: ["Read","Glob","Grep"]` + `dontAsk` | | `bypassPermissions` (`--dangerously-skip-permissions`) | Approves everything reaching the mode step; deny/ask rules and hooks still apply | **Highest**: full autonomous system access; subagents inherit it and cannot be overridden per-subagent | Only inside sandboxed containers/VMs; enterprise admins can disable the option entirely | | **Sandboxing** (`/sandbox`, orthogonal) | OS-level filesystem + network isolation, independent of approvals | Converts "trust the model" into "bound the blast radius" | Pair with permissive modes; cloud sessions are sandboxed by design (which is why web offers no bypass) | Surface availability: Desktop exposes Ask/Accept edits/Plan/Auto/Bypass (Shift+Tab cycles modes in the CLI, Cmd/Ctrl+Shift+M in Desktop); `dontAsk` is CLI/SDK-only; cloud sessions offer Accept edits/Plan/Auto only. Auto mode requires Opus 4.6+/Sonnet 4.6 on the Anthropic API; on Bedrock/Vertex/Foundry set `CLAUDE_CODE_ENABLE_AUTO_MODE=1` (Opus 4.7/4.8 only, since v2.1.158). ## Analysis - **Auto mode is a second gate, not a replacement for rules.** Deny and explicit ask rules evaluate *before* the classifier. For actions that must never run, use `permissions.deny` in managed settings — the classifier can't be consulted and developers can't override it. Inside the classifier, precedence is `hard_deny` → `soft_deny` → `allow` exceptions → explicit user intent ("force-push this branch" authorizes a force push; "clean up the repo" does not). - **Auto mode's config is prose, not patterns.** `autoMode.environment` entries are natural-language descriptions of trusted repos/buckets/domains. Biggest footgun: setting any list without `"$defaults"` **replaces** the built-in rules — a `soft_deny` without `$defaults` discards the built-in force-push and `curl | bash` blocks. Inspect with `claude auto-mode defaults | config | critique`; review denials in `/permissions` → Recently denied (press `r` to retry). - **Classifier failure modes are documented errors**, not mysteries: "temporarily unavailable" (retry), "could not evaluate this action" (retry, `--debug`), "classifier transcript exceeded context window" (run `/compact`; in `-p` mode the run aborts). - **The known reliability gap is rule matching, not the model.** The 82-comment re-prompt-loop issue traced to Windows backslash/case-variant rules never matching (fixed 2.1.162), unmatched UNC paths, and settings.json vs settings.local.json precedence confusion — see [[summaries/casebook-runtime]] Case 4. Users who "fixed" this by jumping to `defaultMode: bypassPermissions` traded a bug for a risk; update + fix rule syntax first. - **Subagent inheritance is the quiet escalation path:** `bypassPermissions`, `acceptEdits`, and `auto` all flow down to subagents, which may have less constrained system prompts. An explicit ask rule is the one thing that still forces a prompt. ## Recommendations - **Start `default`, plan-first for anything multi-file** (Shift+Tab), then drop to `acceptEdits` to execute an approved plan — the explicitly documented Desktop best practice. - **Adopt `auto` as the daily driver once you've fed it your environment**: add source-control org + key internal services to `autoMode.environment` first (resolves most false positives), then domains and buckets as denials surface. - **Reduce prompts in `default`/`acceptEdits` with allowlists, not mode escalation:** `/permissions` entries like `Bash(npm run lint)`, `Bash(git commit *)`. - **Headless/CI:** `dontAsk` + explicit `allowedTools` for a locked surface; `auto` + `-p` when the task needs flexible tooling (knowing repeated blocks abort the run); scope fan-outs with `--allowedTools "Edit,Bash(git commit *)"`. - **Reserve `bypassPermissions` for disposable sandboxes** (containers, VMs, devcontainers). Even there, keep `disallowed_tools` deny rules for the truly forbidden, since they still bind. - **Enterprises:** enforce non-negotiables via managed `permissions.deny`; distribute `autoMode` via managed settings (note: developer `allow` entries can override org `soft_deny` — additive, not a hard boundary; only `hard_deny` and `permissions.deny` are immune); disable bypass in Desktop where appropriate. ## Pages Compared - [[concepts/permissions-security]] - [[concepts/configuration]] - [[concepts/enterprise-deployment]] - [[concepts/subagents-orchestration]] - [[entities/desktop-app]] - [[entities/claude-code-web]] - [[summaries/best-practices]] - [[summaries/casebook-runtime]] - [[syntheses/surface-picker]] --- title: "Surface Picker: Terminal CLI vs Desktop App vs IDE Extension vs Web" type: synthesis tags: [decision-guide, surfaces, cli, desktop, ide, web, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-desktop-application.md", "raw/llms_txt_doc-use-claude-code-on-the-web.md", "raw/llms_txt_doc-jetbrains-ides.md", "raw/llms_txt_doc-best-practices-for-claude-code.md", "raw/llms_txt_doc-error-reference.md", "raw/github_issue-bug-claude-code-does-not-detect-jetbrains-ide-on-windows-wsl.md", "raw/github_issue-bug-claude-code-requires-node-js-version-18-or-higher-to-be-.md"] --- # Surface Picker: Terminal CLI vs Desktop App vs IDE Extension vs Web All four surfaces wrap the same Claude Code engine (the official error reference notes CLI, Desktop, and web "all wrap the same Claude Code CLI"), so models, CLAUDE.md, skills, and permission semantics carry over. The choice is about *where it runs* and *how you supervise it*. ## Comparison | Dimension | Terminal CLI | Desktop app (Code tab) | IDE extension (VS Code / JetBrains) | Claude Code on the web | |---|---|---|---|---| | Runs on | Your machine (any OS incl. Linux) | macOS / Windows x64 & ARM64 — **no Linux** | Your machine, inside the IDE | Anthropic-managed VM (4 vCPU / 16 GB RAM / 30 GB disk) | | Best for | Scripting (`claude -p`), CI, power users, worktree parallelism, full flag surface | Visual parallel sessions, diff review + commenting, app preview, PR monitoring | Staying in your editor: IDE diff viewer, selection context, lint/diagnostic sharing | Fire-and-forget cloud tasks; sessions persist after you close the browser; monitor from mobile | | Parallelism | Manual via git worktrees / `claude agents` | Sidebar sessions, each in its own worktree | One session per IDE window (it's the CLI under the hood) | Many isolated VM sessions | | Permission modes | All, incl. `dontAsk` (CLI-only) and `bypassPermissions` via `--dangerously-skip-permissions` | Ask / Accept edits / Plan / Auto / Bypass (admin-gateable) | Same as CLI | Accept edits / Plan / Auto; **no Bypass** (already sandboxed) | | Local config (`~/.claude/*`) | Full | Full | Full | **Repo-only**: user-level CLAUDE.md, user skills, `claude mcp add` servers do NOT carry over — commit to `.claude/` / `.mcp.json` instead | | Extras | `/fast` mode (not in VS Code ext.), `--safe-mode`, full env-var control | Integrated terminal & file editor, embedded browser preview with auto-verify, computer use, Dispatch from phone, scheduled tasks | `Cmd+Esc`/`Ctrl+Esc` quick launch, `@src/auth.ts#L1-99` references | Setup scripts (root on Ubuntu 24.04), env caching, network allowlists, `--remote`/`--teleport` handoff | | Network | Yours | Yours | Yours | Filtered: Trusted allowlist by default; 403 `x-deny-reason: host_not_allowed` for off-list domains | | Known rough edges | — | Cowork tab on Windows: home-dir-only folders, virtualization false negatives, VM DNS issues ([[summaries/casebook-runtime]]) | JetBrains+WSL2 detection failures (NAT/firewall); IDE-terminal Node false positives ([[summaries/casebook-install-auth]]) | No secrets store; no interactive auth (AWS SSO); `gh` CLI not pre-installed; ZDR orgs excluded | ## Analysis - **The surfaces compose rather than compete.** Web onboarding pairs with `/web-setup` from the terminal; `--remote` pushes a local task to the cloud and `--teleport` pulls a cloud session into your terminal; Desktop lets you open files in VS Code from a session. Pick per task, not per identity. - **Local config is the biggest portability trap.** Everything in `~/.claude/` (user CLAUDE.md, user skills/agents/commands, user-scoped plugins, MCP servers added via `claude mcp add`) silently disappears in cloud sessions. Teams that commit `.claude/` and `.mcp.json` to the repo get identical behavior on all four surfaces. - **Supervision density differs.** The CLI is keyboard-first single-session attention; Desktop is built for scanning multiple sessions (Summary view mode, usage ring, CI status bar with Auto-fix/Auto-merge); web is built for *not* watching (persists after browser close, mobile monitoring). - **Windows reality check from the casebooks:** the IDE-integrated terminal is a recurring failure surface (Node-version false positives, transcript-saving bug fixed in 2.1.170), and the Desktop Cowork tab had three launch blockers at the Feb 2026 Windows launch. The plain CLI in Windows Terminal is the most reliable Windows path. ## Recommendations - **Pick the terminal CLI if:** you script or automate (`claude -p`, fan-out loops, CI), want every flag and mode (incl. `dontAsk`, `/fast`), run Linux, or are troubleshooting (only surface with `--safe-mode`). - **Pick the Desktop app if:** you run several sessions in parallel and want visual diff review with inline comments, embedded app preview with auto-verification, or PR monitoring with auto-fix/auto-merge. Requires macOS/Windows + Git for Windows. - **Pick an IDE extension if:** your center of gravity is the editor — you want diffs in the IDE diff viewer, automatic selection/diagnostic sharing, and quick launch. JetBrains on WSL2 needs firewall/`wsl -d -- bash -lic "claude"` setup first. - **Pick the web if:** the task is self-contained against a GitHub repo and you want it to run unattended on Anthropic's infrastructure — bug-fix batches, dependency bumps, Auto-fix on PRs. Avoid it when the task needs local credentials, interactive SSO, >16 GB RAM, or non-allowlisted hosts (or use Remote Control on your own hardware instead). - **Default split that works:** interactive feature work in CLI or IDE → parallel review/preview in Desktop → overflow and scheduled/batch work on the web. ## Pages Compared - [[entities/desktop-app]] - [[entities/ide-extensions]] - [[entities/claude-code-web]] - [[concepts/cli-reference]] - [[concepts/interactive-mode]] - [[summaries/best-practices]] - [[summaries/casebook-runtime]] - [[syntheses/permission-mode-picker]] --- title: "Troubleshooting Checklist: Ordered Diagnostic Sequence" type: synthesis tags: [troubleshooting, checklist, diagnostics, errors, foundational] created: 2026-06-10 updated: 2026-06-10 confidence: high sources: ["raw/llms_txt_doc-error-reference.md", "raw/github_doc-changelog-md.md", "raw/github_issue-anthropic-api-overloaded-error-with-repeated-529-status-code.md", "raw/github_issue-bug-anthropic-api-credential-restriction-preventing-api-requ.md", "raw/github_issue-bug-error-during-compaction.md", "raw/github_issue-bug-claude-continually-asks-for-permission-even-after-select.md", "raw/github_issue-bug-oversized-image-breaks-conversation-permanently-no-way-t.md", "raw/github_issue-bug-critical-widespread-abnormal-usage-limit-drain-across-al.md"] --- # Troubleshooting Checklist: Ordered Diagnostic Sequence A single ordered flow synthesized from the official error reference and the two casebooks ([[summaries/casebook-install-auth]], [[summaries/casebook-runtime]]). Run top to bottom; each step either fixes the problem or rules out a layer. Verbatim commands throughout. ## Comparison ### Step 0 — Establish the basics (30 seconds) | Check | Command | Why first | |---|---|---| | Version | `claude --version` | Many famous bugs are version-bounded: oversized-image lockout fixed 2.1.142; Windows backslash permission rules fixed 2.1.162; cache-drain regression ≈2.1.69–2.1.89, fixed 2.1.90; VS Code-terminal transcript loss fixed 2.1.170. Update: `claude update`. | | Service health | https://status.claude.com | 500s/529s are usually them, not you. | | Credential in use | `/status` | A stray `ANTHROPIC_API_KEY` silently overrides `/login` and causes 401/429/disabled-org errors. | | Local config sanity | `/doctor` | Flags oversized memory files, config problems; contradictory results inside remote sessions were a known cosmetic bug (fixed 2.1.166). | ### Step 1 — Classify by the exact error string | You see | It is | Jump to | |---|---|---| | `API Error: 500 Internal server error` / `Repeated 529 Overloaded` | Server-side | Step 2 | | `You've hit your session limit` / `weekly limit` / `429` / `Credit balance is too low` | Quota/limits | Step 3 | | `Not logged in` / `Invalid API key` / `OAuth token revoked` / `This credential is only authorized for use with Claude Code…` | Auth | Step 4 | | `Unable to connect to API` / `SSL certificate verification failed` / `403 x-deny-reason: host_not_allowed` | Network | Step 5 | | `Prompt is too long` / `Error during compaction` / `Request too large` / image/PDF errors / `400 tool use concurrency` | Request/context | Step 6 | | Permission prompts repeating, hooks/skills misbehaving, weird startup | Local config | Step 7 | | No error, output just seems worse | Quality drift | Step 8 | ### Steps 2–8 (the sequence) **2. Server errors** — already retried 10x before you saw it (`CLAUDE_CODE_MAX_RETRIES`, default 10; `API_TIMEOUT_MS`, default 600000). Wait a minute; type `try again` (your message is still in the conversation). Capacity is per model: `/model` → switch to Sonnet. Configure `fallbackModel` (up to three, v2.1.166+) to automate this. Persistent with no incident → `/feedback`. **3. Usage limits** — `/usage` for limits and reset times; `/usage-credits` to buy/enable extra usage; 1M-context entitlement error → `/model` and pick the non-`[1m]` variant. **If drain seems abnormal** (single short prompt >3–5% of session): update first (cache regressions did exactly this), avoid `--resume` on long sessions, check multiple terminals/subagents running in parallel — see [[summaries/casebook-install-auth]] Case 4. **4. Auth** — in order: `/status` (what credential won?) → `env | grep ANTHROPIC` in the same shell (direnv/dotenv/IDE terminals load stale keys from project `.env`) → unset the env var or remove `apiKeyHelper` → `/login`. If errors recur in-session: `/logout` then `/login`. The "credential is only authorized for use with Claude Code" 400 resolves with a simple re-login. **5. Network** — `curl -I https://api.anthropic.com` (PowerShell: `curl.exe -I https://api.anthropic.com`). Curl fails → fix proxy (`HTTPS_PROXY`), firewall, VPN. Curl succeeds but Claude fails → WSL: check `/etc/resolv.conf` for a broken inherited resolver; macOS: stale `utun` VPN interfaces; quit Docker Desktop to rule out interception. Corporate TLS interception → `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`, never `NODE_TLS_REJECT_UNAUTHORIZED=0`. Cloud session 403 `host_not_allowed` → edit the environment's Network access (Trusted → Custom) and add the domain. **6. Request/context errors** — - `Prompt is too long`: `/compact`, or `/clear`; `/context` to see what's eating the window; `/mcp disable `; trim CLAUDE.md; note subagents inherit every MCP tool definition. - `Error during compaction: Conversation too long`: Esc Esc → step back several turns → `/compact` again; else `/clear` (old session remains in `/resume`). - `Request too large (max 30 MB)`: Esc Esc past the oversized paste; reference files by path instead. - Image errors: ≥2.1.142 auto-recovers with a placeholder; older versions: Esc Esc past the image turn. Limits: 8000px single / 2000px many-image. - `400 due to tool use concurrency` / `unexpected tool_use_id` / thinking-block errors: on Opus 4.7/4.8 run `claude update` first (pre-2.1.156 triggered this in normal use), then `/rewind` to a checkpoint before the corrupted turn. - Usage Policy refusal: rewind past the triggering turn or `/clear` — the check evaluates the whole transcript, so retrying in-session re-triggers it. **7. Local config / customization faults** — bisect with **`claude --safe-mode`** (v2.1.169+): starts with CLAUDE.md, plugins, skills, hooks, and MCP servers all disabled. Works in safe mode → re-enable layers until it breaks. Permission re-prompt loops specifically: update to ≥2.1.162 (Windows path matching), use forward-slash glob rules, map UNC paths to drive letters, and try mirroring rules into `.claude/settings.local.json` ([[summaries/casebook-runtime]] Case 4). Gateway-related `Extra inputs are not permitted` → forward the `anthropic-beta` header or set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. **8. Quality drift (no error)** — `/model` (are you on what you think?), `/effort` (raise for hard work), `/context` (near-full window → `/compact` or `/clear`), stale CLAUDE.md/MCP definitions (`/doctor`). Prefer rewinding over correcting in-thread — failed attempts left in context anchor later answers. Still off → `/feedback` (sends the transcript; on Bedrock/Vertex/Foundry it saves a local archive instead). ### Escalation `/feedback` (prefilled GitHub issue option) → search https://github.com/anthropics/claude-code/issues → file with version, platform, terminal, and the **verbatim** error. ## Analysis - **Order matters because layers mask each other.** A stray API key (step 4) produces 429s that look like quota (step 3); a broken WSL resolver (step 5) looks like an API outage (step 2); a cache regression (step 0 version check) looks like Anthropic tightening limits (step 3). Cheapest, most-discriminating checks come first: version, status page, `/status`. - **The casebooks add what the error reference lacks:** version boundaries for known bugs, community workarounds when the official fix is "wait" (DNS swap for Cowork, `\\?\` deletion for `nul`, run-from-terminal for IDE Node false positives), and the recognition pattern for abnormal-drain incidents. - **`--safe-mode` (2.1.169) collapses what used to be step-7 guesswork** — previously users deleted `~/.claude` wholesale (which the auto-compact-stuck issue showed doesn't even work for engine bugs). ## Recommendations - Pin the checklist's three reflexes: **`/status` before debugging auth, `/context` before debugging quality, `claude --version` before reporting any bug.** - In scripts/CI, lower `CLAUDE_CODE_MAX_RETRIES` to surface failures fast; raise it for unattended overnight runs. - Keep `fallbackModel` configured so 529 episodes degrade instead of stopping work. - When filing or matching issues, paste the error **verbatim** — the casebooks show issue triage hinges on exact strings (`overloaded_error` vs `api_error` vs `invalid_request_error`). ## Pages Compared - [[summaries/casebook-install-auth]] - [[summaries/casebook-runtime]] - [[summaries/changelog-digest]] - [[concepts/installation-setup]] - [[concepts/configuration]] - [[concepts/memory-context]] - [[concepts/permissions-security]] - [[syntheses/cost-management]]