diff --git a/.claude/skills/lesson-quiz/references/question-bank.md b/.claude/skills/lesson-quiz/references/question-bank.md index 8fb714b..1f2a9b3 100644 --- a/.claude/skills/lesson-quiz/references/question-bank.md +++ b/.claude/skills/lesson-quiz/references/question-bank.md @@ -325,9 +325,9 @@ ### Q9 - **Category**: conceptual - **Question**: What are the valid `permissionMode` values for a subagent? -- **Options**: A) read, write, admin | B) default, acceptEdits, bypassPermissions, plan, ignore | C) safe, normal, dangerous | D) restricted, standard, elevated +- **Options**: A) read, write, admin | B) default, acceptEdits, bypassPermissions, plan, dontAsk, auto | C) safe, normal, dangerous | D) restricted, standard, elevated - **Correct**: B -- **Explanation**: Subagents support five permission modes: default (prompts for everything), acceptEdits (auto-accepts file edits), bypassPermissions (skips all), plan (read-only), ignore (auto-denies). +- **Explanation**: Subagents support six permission modes: default (prompts for everything), acceptEdits (auto-accepts file edits), bypassPermissions (skips all), plan (read-only), dontAsk (auto-denies unless pre-approved), auto (background classifier decides). - **Review**: Configuration fields section ### Q10 @@ -428,10 +428,10 @@ ### Q1 - **Category**: conceptual -- **Question**: What are the three types of hooks in Claude Code? -- **Options**: A) Pre, Post, and Error hooks | B) Command, HTTP, and Prompt hooks | C) Before, After, and Around hooks | D) Input, Output, and Filter hooks +- **Question**: What are the four types of hooks in Claude Code? +- **Options**: A) Pre, Post, Error, and Filter hooks | B) Command, HTTP, Prompt, and Agent hooks | C) Before, After, Around, and Through hooks | D) Input, Output, Filter, and Transform hooks - **Correct**: B -- **Explanation**: Command hooks run shell scripts, HTTP hooks call webhook endpoints, and Prompt hooks use LLM evaluation (primarily for Stop/SubagentStop events). +- **Explanation**: Command hooks run shell scripts, HTTP hooks call webhook endpoints, Prompt hooks use single-turn LLM evaluation, and Agent hooks use subagent-based verification. - **Review**: Hook types section ### Q2 @@ -493,9 +493,9 @@ ### Q9 - **Category**: conceptual - **Question**: How many hook events does Claude Code support in total? -- **Options**: A) 6 | B) 10 | C) 16 | D) 20 +- **Options**: A) 10 | B) 16 | C) 25 | D) 30 - **Correct**: C -- **Explanation**: Claude Code supports 16 hook events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PermissionRequest, Notification, PreCompact, SessionStart, SessionEnd, WorktreeCreate, WorktreeRemove, ConfigChange, TeammateIdle, TaskCompleted. +- **Explanation**: Claude Code supports 25 hook events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, StopFailure, SubagentStop, SubagentStart, PermissionRequest, Notification, PreCompact, PostCompact, SessionStart, SessionEnd, WorktreeCreate, WorktreeRemove, ConfigChange, CwdChanged, FileChanged, TeammateIdle, TaskCompleted, TaskCreated, Elicitation, ElicitationResult, InstructionsLoaded. - **Review**: Hook events table ### Q10 @@ -680,10 +680,10 @@ ### Q1 - **Category**: conceptual -- **Question**: What are the five permission modes in Claude Code? -- **Options**: A) read, write, execute, admin, root | B) default, acceptEdits, plan, dontAsk, bypassPermissions | C) safe, normal, elevated, admin, unrestricted | D) view, edit, run, deploy, full +- **Question**: What are the six permission modes in Claude Code? +- **Options**: A) read, write, execute, admin, root, sudo | B) default, acceptEdits, plan, auto, dontAsk, bypassPermissions | C) safe, normal, elevated, admin, unrestricted, god | D) view, edit, run, deploy, full, bypass - **Correct**: B -- **Explanation**: The five modes are: default (prompts for everything), acceptEdits (auto-accepts file edits), plan (read-only analysis), dontAsk (auto-denies unless pre-approved), bypassPermissions (skips all checks). +- **Explanation**: The six modes are: default (prompts for everything), acceptEdits (auto-accepts file edits), plan (read-only analysis), auto (background classifier decides), dontAsk (auto-denies unless pre-approved), bypassPermissions (skips all checks). - **Review**: Permission Modes section ### Q2 diff --git a/.claude/skills/self-assessment/SKILL.md b/.claude/skills/self-assessment/SKILL.md index a668e36..8a45453 100644 --- a/.claude/skills/self-assessment/SKILL.md +++ b/.claude/skills/self-assessment/SKILL.md @@ -317,7 +317,7 @@ Use these specific recommendations when a topic is a gap: - Done when: A hook blocks dangerous commands before execution **Hooks (score 1 — review)**: -- Focus on: All 16 hook events, prompt-type hooks for Stop/SubagentStop, component-scoped hooks in SKILL.md frontmatter, HTTP hooks with allowedEnvVars, `CLAUDE_ENV_FILE` for SessionStart +- Focus on: All 25 hook events (including PostToolUseFailure, StopFailure, TaskCreated, CwdChanged, FileChanged, PostCompact, Elicitation, ElicitationResult), 4 hook types (command, http, prompt, agent), component-scoped hooks in SKILL.md frontmatter, HTTP hooks with allowedEnvVars, `CLAUDE_ENV_FILE` for SessionStart/CwdChanged/FileChanged - Done when: You can create a prompt-based Stop hook and a component-scoped hook in a skill **MCP (score 0)**: diff --git a/01-slash-commands/README.md b/01-slash-commands/README.md index 2b88eeb..acadc97 100644 --- a/01-slash-commands/README.md +++ b/01-slash-commands/README.md @@ -18,78 +18,103 @@ Slash commands are shortcuts that control Claude's behavior during an interactiv ## Built-in Commands Reference -Built-in commands are shortcuts for common actions. Type `/` in Claude Code to see the full list, or type `/` followed by any letters to filter. +Built-in commands are shortcuts for common actions. There are **55+ built-in commands** and **5 bundled skills** available. Type `/` in Claude Code to see the full list, or type `/` followed by any letters to filter. | Command | Purpose | |---------|---------| -| `/add-dir` | Add additional working directories | -| `/agents` | Manage custom AI subagents for specialized tasks | -| `/btw ` | Side question without adding to conversation | +| `/add-dir ` | Add working directory | +| `/agents` | Manage agent configurations | +| `/branch [name]` | Branch conversation into a new session (alias: `/fork`). Note: `/fork` renamed to `/branch` in v2.1.77 | +| `/btw ` | Side question without adding to history | | `/chrome` | Configure Chrome browser integration | -| `/clear` | Clear conversation history | +| `/clear` | Clear conversation (aliases: `/reset`, `/new`) | +| `/color [color\|default]` | Set prompt bar color | | `/compact [instructions]` | Compact conversation with optional focus instructions | -| `/config` | Open the Settings interface (Config tab) | -| `/context` | Visualize context usage with actionable optimization suggestions | -| `/copy` | Copy the last assistant response to clipboard | +| `/config` | Open Settings (alias: `/settings`) | +| `/context` | Visualize context usage as colored grid | +| `/copy [N]` | Copy assistant response to clipboard; `w` writes to file | | `/cost` | Show token usage statistics | -| `/desktop` | Hand off CLI session to Desktop app (macOS/Windows) | +| `/desktop` | Continue in Desktop app (alias: `/app`) | | `/diff` | Interactive diff viewer for uncommitted changes | -| `/doctor` | Checks the health of your Claude Code installation | -| `/exit` | Exit the REPL | +| `/doctor` | Diagnose installation health | +| `/effort [low\|medium\|high\|max\|auto]` | Set effort level. `max` requires Opus 4.6 | +| `/exit` | Exit the REPL (alias: `/quit`) | | `/export [filename]` | Export the current conversation to a file or clipboard | | `/extra-usage` | Configure extra usage for rate limits | -| `/fast` | Toggle fast mode (same model, faster output) | +| `/fast [on\|off]` | Toggle fast mode | | `/feedback` | Submit feedback (alias: `/bug`) | -| `/fork` | Fork the current session into a new conversation | -| `/help` | Get usage help | -| `/hooks` | Manage hook configurations for tool events | -| `/ide` | Manage IDE integrations and show status | -| `/init` | Initialize project with `CLAUDE.md` guide | -| `/insights` | Analyze session patterns and friction points | -| `/install-github-app` | Set up Claude GitHub Actions for a repository | -| `/install-slack-app` | Install Claude Slack app | +| `/help` | Show help | +| `/hooks` | View hook configurations | +| `/ide` | Manage IDE integrations | +| `/init` | Initialize `CLAUDE.md`. Set `CLAUDE_CODE_NEW_INIT=true` for interactive flow | +| `/insights` | Generate session analysis report | +| `/install-github-app` | Set up GitHub Actions app | +| `/install-slack-app` | Install Slack app | | `/keybindings` | Open keybindings configuration | | `/login` | Switch Anthropic accounts | | `/logout` | Sign out from your Anthropic account | -| `/mcp` | Manage MCP server connections and OAuth authentication | -| `/memory` | Edit `CLAUDE.md` memory files | -| `/mobile` | QR code for Claude mobile app (aliases: `/ios`, `/android`) | -| `/model` | Select or change the AI model | +| `/mcp` | Manage MCP servers and OAuth | +| `/memory` | Edit `CLAUDE.md`, toggle auto-memory | +| `/mobile` | QR code for mobile app (aliases: `/ios`, `/android`) | +| `/model [model]` | Select model with left/right arrows for effort | | `/passes` | Share free week of Claude Code | -| `/permissions` | View or update permissions | -| `/plan` | Enter plan mode directly from the prompt | -| `/plugin` | Manage Claude Code plugins | -| `/pr-comments` | View pull request comments | -| `/privacy-settings` | View and update your privacy settings | -| `/release-notes` | View release notes | -| `/reload-plugins` | Reload active plugins without restart | -| `/remote-control` | Make session available for remote control (alias: `/rc`) | -| `/remote-env` | Configure remote session environment (claude.ai subscribers) | -| `/rename ` | Rename the current session | -| `/resume [session]` | Resume a conversation by ID or name | -| `/review` | **Deprecated** — install the `code-review` plugin instead: `claude plugin install code-review@claude-code-marketplace` | -| `/rewind` | Rewind the conversation and/or code | -| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation | -| `/security-review` | Complete a security review of pending changes | +| `/permissions` | View/update permissions (alias: `/allowed-tools`) | +| `/plan [description]` | Enter plan mode | +| `/plugin` | Manage plugins | +| `/pr-comments [PR]` | Fetch GitHub PR comments | +| `/privacy-settings` | Privacy settings (Pro/Max only) | +| `/release-notes` | View changelog | +| `/reload-plugins` | Reload active plugins | +| `/remote-control` | Remote control from claude.ai (alias: `/rc`) | +| `/remote-env` | Configure default remote environment | +| `/rename [name]` | Rename session | +| `/resume [session]` | Resume conversation (alias: `/continue`) | +| `/review` | **Deprecated** — install the `code-review` plugin instead | +| `/rewind` | Rewind conversation and/or code (alias: `/checkpoint`) | +| `/sandbox` | Toggle sandbox mode | +| `/schedule [description]` | Create/manage scheduled tasks | +| `/security-review` | Analyze branch for security vulnerabilities | | `/skills` | List available skills | -| `/stats` | Visualize daily usage, session history, streaks, and model preferences | -| `/status` | Open the Settings interface (Status tab) | -| `/statusline` | Set up Claude Code's status line UI | -| `/stickers` | Order Claude Code stickers | -| `/tasks` | List and manage background tasks | -| `/teleport` | Resume remote session from claude.ai by session ID | -| `/terminal-setup` | Install Shift+Enter key binding for newlines | -| `/theme` | Change the color theme | -| `/upgrade` | Open upgrade page | -| `/usage` | Show plan usage limits and rate limit status | -| `/vim` | Enter vim mode for alternating insert and command modes | +| `/stats` | Visualize daily usage, sessions, streaks | +| `/status` | Show version, model, account | +| `/statusline` | Configure status line | +| `/tasks` | List/manage background tasks | +| `/terminal-setup` | Configure terminal keybindings | +| `/theme` | Change color theme | +| `/vim` | Toggle Vim/Normal modes | +| `/voice` | Toggle push-to-talk voice dictation | + +### Bundled Skills + +These skills ship with Claude Code and are invoked like slash commands: + +| Skill | Purpose | +|-------|---------| +| `/batch ` | Orchestrate large-scale parallel changes using worktrees | +| `/claude-api` | Load Claude API reference for project language | +| `/debug [description]` | Enable debug logging | +| `/loop [interval] ` | Run prompt repeatedly on interval | +| `/simplify [focus]` | Review changed files for code quality | + +### Deprecated Commands + +| Command | Status | +|---------|--------| +| `/review` | Deprecated — replaced by `code-review` plugin | +| `/output-style` | Deprecated since v2.1.73 | +| `/fork` | Renamed to `/branch` (alias still works, v2.1.77) | ### Recent Changes +- `/fork` renamed to `/branch` with `/fork` kept as alias (v2.1.77) +- `/output-style` deprecated (v2.1.73) +- `/review` deprecated in favor of the `code-review` plugin +- `/effort` command added with `max` level requiring Opus 4.6 +- `/voice` command added for push-to-talk voice dictation +- `/schedule` command added for creating/managing scheduled tasks +- `/color` command added for prompt bar customization - `/model` picker now shows human-readable labels (e.g., "Sonnet 4.6") instead of raw model IDs -- `/rename` auto-generates a session name from conversation context when called without arguments -- `/rename` now updates the terminal tab title by default -- `/resume` picker increased initial session count from 10 to 50 +- `/resume` supports `/continue` alias - MCP prompts are available as `/mcp____` commands (see [MCP Prompts as Commands](#mcp-prompts-as-commands)) ## Custom Commands (Now Skills) diff --git a/02-memory/README.md b/02-memory/README.md index c1b8ae7..4e3e8cd 100644 --- a/02-memory/README.md +++ b/02-memory/README.md @@ -49,6 +49,13 @@ The `/init` command is the fastest way to set up project memory in Claude Code. - Sets up the foundation for context persistence across sessions - Provides a template structure for documenting your project standards +**Enhanced interactive mode:** Set `CLAUDE_CODE_NEW_INIT=true` to enable a multi-phase interactive flow that walks you through project setup step by step: + +```bash +CLAUDE_CODE_NEW_INIT=true claude +/init +``` + **When to use `/init`:** - Starting a new project with Claude Code @@ -219,27 +226,31 @@ Claude Code uses a multi-tier hierarchical memory system. Memory files are autom 1. **Managed Policy** - Organization-wide instructions - macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` - - Linux: `/etc/claude-code/CLAUDE.md` - - Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` + - Linux/WSL: `/etc/claude-code/CLAUDE.md` + - Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` -2. **Project Memory** - Team-shared context (version controlled) +2. **Managed Drop-ins** - Alphabetically merged policy files (v2.1.83+) + - `managed-settings.d/` directory alongside the managed policy CLAUDE.md + - Files are merged in alphabetical order for modular policy management + +3. **Project Memory** - Team-shared context (version controlled) - `./.claude/CLAUDE.md` or `./CLAUDE.md` (in repository root) -3. **Project Rules** - Modular, topic-specific project instructions +4. **Project Rules** - Modular, topic-specific project instructions - `./.claude/rules/*.md` -4. **User Memory** - Personal preferences (all projects) +5. **User Memory** - Personal preferences (all projects) - `~/.claude/CLAUDE.md` -5. **User-Level Rules** - Personal rules (all projects) +6. **User-Level Rules** - Personal rules (all projects) - `~/.claude/rules/*.md` -6. **Local Project Memory** - Personal project-specific preferences +7. **Local Project Memory** - Personal project-specific preferences - `./CLAUDE.local.md` > **Note**: `CLAUDE.local.md` is not mentioned in the [official documentation](https://code.claude.com/docs/en/memory) as of March 2026. It may still work as a legacy feature. For new projects, consider using `~/.claude/CLAUDE.md` (user-level) or `.claude/rules/` (project-level, path-scoped) instead. -7. **Auto Memory** - Claude's automatic notes and learnings +8. **Auto Memory** - Claude's automatic notes and learnings - `~/.claude/projects//memory/` **Memory Discovery Behavior:** @@ -248,7 +259,8 @@ Claude searches for memory files in this order, with earlier locations taking pr ```mermaid graph TD - A["Managed Policy
/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| B["Project Memory
./CLAUDE.md"] + A["Managed Policy
/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins
managed-settings.d/"] + A2 --> B["Project Memory
./CLAUDE.md"] B --> C["Project Rules
./.claude/rules/*.md"] C --> D["User Memory
~/.claude/CLAUDE.md"] D --> E["User Rules
~/.claude/rules/*.md"] @@ -259,6 +271,7 @@ graph TD H -->|imports| I["@docs/api-standards.md"] style A fill:#fce4ec,stroke:#333,color:#333 + style A2 fill:#fce4ec,stroke:#333,color:#333 style B fill:#e1f5fe,stroke:#333,color:#333 style C fill:#e1f5fe,stroke:#333,color:#333 style D fill:#f3e5f5,stroke:#333,color:#333 @@ -289,6 +302,26 @@ Patterns are matched against paths relative to the project root. This is particu - Repositories that contain vendored or third-party CLAUDE.md files - Reducing noise in Claude's context window by excluding stale or unrelated instructions +## Settings File Hierarchy + +Claude Code settings (including `autoMemoryDirectory`, `claudeMdExcludes`, and other configuration) are resolved from a five-level hierarchy, with higher levels taking precedence: + +| Level | Location | Scope | +|-------|----------|-------| +| 1 (Highest) | Managed policy (system-level) | Organization-wide enforcement | +| 2 | `managed-settings.d/` (v2.1.83+) | Modular policy drop-ins, merged alphabetically | +| 3 | `~/.claude/settings.json` | User preferences | +| 4 | `.claude/settings.json` | Project-level (committed to git) | +| 5 (Lowest) | `.claude/settings.local.json` | Local overrides (git-ignored) | + +**Platform-specific configuration (v2.1.51+):** + +Settings can also be configured via: +- **macOS**: Property list (plist) files +- **Windows**: Windows Registry + +These platform-native mechanisms are read alongside JSON settings files and follow the same precedence rules. + ## Modular Rules System Create organized, path-specific rules using the `.claude/rules/` directory structure. Rules can be defined at both the project level and user level: @@ -350,8 +383,9 @@ Rules in `.claude/rules/` support two organizational features: | Location | Scope | Priority | Shared | Access | Best For | |----------|-------|----------|--------|--------|----------| | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | Managed Policy | 1 (Highest) | Organization | System | Company-wide policies | -| `/etc/claude-code/CLAUDE.md` (Linux) | Managed Policy | 1 (Highest) | Organization | System | Organization standards | -| `C:\ProgramData\ClaudeCode\CLAUDE.md` (Windows) | Managed Policy | 1 (Highest) | Organization | System | Corporate guidelines | +| `/etc/claude-code/CLAUDE.md` (Linux/WSL) | Managed Policy | 1 (Highest) | Organization | System | Organization standards | +| `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Managed Policy | 1 (Highest) | Organization | System | Corporate guidelines | +| `managed-settings.d/*.md` (alongside policy) | Managed Drop-ins | 1.5 | Organization | System | Modular policy files (v2.1.83+) | | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project Memory | 2 | Team | Git | Team standards, shared architecture | | `./.claude/rules/*.md` | Project Rules | 3 | Team | Git | Path-specific, modular rules | | `~/.claude/CLAUDE.md` | User Memory | 4 | Individual | Filesystem | Personal preferences (all projects) | @@ -440,18 +474,36 @@ npm install -g @anthropic-ai/claude-code@latest By default, auto memory is stored in `~/.claude/projects//memory/`. You can change this location using the `autoMemoryDirectory` setting (available since **v2.1.74**): ```jsonc -// In ~/.claude/settings.json or .claude/settings.json +// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only) { "autoMemoryDirectory": "/path/to/custom/memory/directory" } ``` +> **Note**: `autoMemoryDirectory` can only be set in user-level (`~/.claude/settings.json`) or local settings (`.claude/settings.local.json`), not in project or managed policy settings. + This is useful when you want to: - Store auto memory in a shared or synced location - Separate auto memory from the default Claude configuration directory - Use a project-specific path outside the default hierarchy +### Worktree and Repository Sharing + +All worktrees and subdirectories within the same git repository share a single auto memory directory. This means switching between worktrees or working in different subdirectories of the same repo will read and write to the same memory files. + +### Subagent Memory + +Subagents (spawned via tools like Task or parallel execution) can have their own memory context. Use the `memory` frontmatter field in the subagent definition to specify which memory scopes to load: + +```yaml +memory: user # Load user-level memory only +memory: project # Load project-level memory only +memory: local # Load local memory only +``` + +This allows subagents to operate with focused context rather than inheriting the full memory hierarchy. + ### Controlling Auto Memory Auto memory can be controlled via the `CLAUDE_CODE_DISABLE_AUTO_MEMORY` environment variable: @@ -1089,12 +1141,13 @@ For the most up-to-date information, refer to the official Claude Code documenta **Memory Hierarchy Precedence:** 1. Managed Policy (highest precedence) -2. Project Memory -3. Project Rules (`.claude/rules/`) -4. User Memory -5. User-Level Rules (`~/.claude/rules/`) -6. Local Project Memory -7. Auto Memory (lowest precedence) +2. Managed Drop-ins (`managed-settings.d/`, v2.1.83+) +3. Project Memory +4. Project Rules (`.claude/rules/`) +5. User Memory +6. User-Level Rules (`~/.claude/rules/`) +7. Local Project Memory +8. Auto Memory (lowest precedence) ## Related Concepts Links diff --git a/03-skills/README.md b/03-skills/README.md index ae1e3c5..9d628fa 100644 --- a/03-skills/README.md +++ b/03-skills/README.md @@ -94,9 +94,13 @@ sequenceDiagram When skills share the same name across levels, higher-priority locations win: **enterprise > personal > project**. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict. -### Automatic Discovery from Nested Directories +### Automatic Discovery -When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills. +**Nested directories**: When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills. + +**`--add-dir` directories**: Skills from directories added via `--add-dir` are loaded automatically with live change detection. Any edits to skill files in those directories take effect immediately without restarting Claude Code. + +**Description budget**: Skill descriptions (Level 1 metadata) are capped at **2% of the context window** (fallback: **16,000 characters**). If you have many skills installed, some may be excluded. Run `/context` to check for warnings. Override the budget with the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. ## Creating Custom Skills @@ -145,8 +149,10 @@ disable-model-invocation: true # Only user can invoke user-invocable: false # Hide from slash menu allowed-tools: Read, Grep, Glob # Restrict tool access model: opus # Specific model to use +effort: high # Effort level override (low, medium, high, max) context: fork # Run in isolated subagent agent: Explore # Which agent type (with context: fork) +shell: bash # Shell for commands: bash (default) or powershell hooks: # Skill-scoped hooks PreToolUse: - matcher: "Bash" @@ -156,6 +162,21 @@ hooks: # Skill-scoped hooks --- ``` +| Field | Description | +|-------|-------------| +| `name` | Lowercase letters, numbers, hyphens only (max 64 chars). Cannot contain "anthropic" or "claude". | +| `description` | What the Skill does AND when to use it (max 1024 chars). Critical for auto-invocation matching. | +| `argument-hint` | Hint shown in the `/` autocomplete menu (e.g., `"[filename] [format]"`). | +| `disable-model-invocation` | `true` = only the user can invoke via `/name`. Claude will never auto-invoke. | +| `user-invocable` | `false` = hidden from the `/` menu. Only Claude can invoke it automatically. | +| `allowed-tools` | Comma-separated list of tools the skill may use without permission prompts. | +| `model` | Model override while the skill is active (e.g., `opus`, `sonnet`). | +| `effort` | Effort level override while the skill is active: `low`, `medium`, `high`, or `max`. | +| `context` | `fork` to run the skill in a forked subagent context with its own context window. | +| `agent` | Subagent type when `context: fork` (e.g., `Explore`, `Plan`, `general-purpose`). | +| `shell` | Shell used for `!`command`` substitutions and scripts: `bash` (default) or `powershell`. | +| `hooks` | Hooks scoped to this skill's lifecycle (same format as global hooks). | + ## Skill Content Types Skills can contain two types of content, each suited for different purposes: @@ -210,7 +231,7 @@ By default, both you and Claude can invoke any skill. Two frontmatter fields con ## String Substitutions -Skills support dynamic values: +Skills support dynamic values that are resolved before the skill content reaches Claude: | Variable | Description | |----------|-------------| @@ -218,6 +239,7 @@ Skills support dynamic values: | `$ARGUMENTS[N]` or `$N` | Access specific argument by index (0-based) | | `${CLAUDE_SESSION_ID}` | Current session ID | | `${CLAUDE_SKILL_DIR}` | Directory containing the skill's SKILL.md file | +| `` !`command` `` | Dynamic context injection — runs a shell command and inlines the output | **Example:** @@ -257,7 +279,7 @@ agent: Explore Summarize this pull request... ``` -Commands execute immediately; Claude only sees the final output. +Commands execute immediately; Claude only sees the final output. By default, commands run in `bash`. Set `shell: powershell` in frontmatter to use PowerShell instead. ## Running Skills in Subagents diff --git a/03-skills/claude-md/SKILL.md b/03-skills/claude-md/SKILL.md index eaab945..2b3c1b4 100644 --- a/03-skills/claude-md/SKILL.md +++ b/03-skills/claude-md/SKILL.md @@ -1,4 +1,5 @@ --- +name: claude-md description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding --- diff --git a/04-subagents/README.md b/04-subagents/README.md index 7645976..3d5d8b1 100644 --- a/04-subagents/README.md +++ b/04-subagents/README.md @@ -24,13 +24,14 @@ Subagents are specialized AI assistants that Claude Code can delegate tasks to. 13. [Restrict Spawnable Subagents](#restrict-spawnable-subagents) 14. [`claude agents` CLI Command](#claude-agents-cli-command) 15. [Agent Teams (Experimental)](#agent-teams-experimental) -16. [Architecture](#architecture) -17. [Context Management](#context-management) -18. [When to Use Subagents](#when-to-use-subagents) -19. [Best Practices](#best-practices) -20. [Example Subagents in This Folder](#example-subagents-in-this-folder) -21. [Installation Instructions](#installation-instructions) -22. [Related Concepts](#related-concepts) +16. [Plugin Subagent Security](#plugin-subagent-security) +17. [Architecture](#architecture) +18. [Context Management](#context-management) +19. [When to Use Subagents](#when-to-use-subagents) +20. [Best Practices](#best-practices) +21. [Example Subagents in This Folder](#example-subagents-in-this-folder) +22. [Installation Instructions](#installation-instructions) +23. [Related Concepts](#related-concepts) --- @@ -66,14 +67,14 @@ Each subagent operates independently with a clean slate, receiving only the spec Subagent files can be stored in multiple locations with different scopes: -| Type | Location | Scope | Priority | -|------|----------|-------|----------| -| **Project subagents** | `.claude/agents/` | Current project | Highest | -| **User subagents** | `~/.claude/agents/` | All projects | Lower | -| **Plugin agents** | `plugins/agents/` | Via plugins | Varies | -| **CLI-defined** | Via `--agents` flag | Session-specific | Medium | +| Priority | Type | Location | Scope | +|----------|------|----------|-------| +| 1 (highest) | **CLI-defined** | Via `--agents` flag (JSON) | Session only | +| 2 | **Project subagents** | `.claude/agents/` | Current project | +| 3 | **User subagents** | `~/.claude/agents/` | All projects | +| 4 (lowest) | **Plugin agents** | Plugin `agents/` directory | Via plugins | -When duplicate names exist, project-level subagents take priority over user-level ones. +When duplicate names exist, higher-priority sources take precedence. --- @@ -96,7 +97,9 @@ skills: skill1, skill2 # Optional - skills to preload into context mcpServers: server1 # Optional - MCP servers to make available memory: user # Optional - persistent memory scope (user, project, local) background: false # Optional - run as background task +effort: high # Optional - reasoning effort (low, medium, high, max) isolation: worktree # Optional - git worktree isolation +initialPrompt: "Start by analyzing the codebase" # Optional - auto-submitted first turn hooks: # Optional - component-scoped hooks PreToolUse: - matcher: "Bash" @@ -116,17 +119,19 @@ to solving problems. |-------|----------|-------------| | `name` | Yes | Unique identifier (lowercase letters and hyphens) | | `description` | Yes | Natural language description of purpose. Include "use PROACTIVELY" to encourage automatic invocation | -| `tools` | No | Comma-separated list of specific tools. Omit to inherit all tools. Supports `Task(agent_name)` syntax to restrict spawnable subagents | +| `tools` | No | Comma-separated list of specific tools. Omit to inherit all tools. Supports `Agent(agent_name)` syntax to restrict spawnable subagents | | `disallowedTools` | No | Comma-separated list of tools the subagent must not use | -| `model` | No | Model to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to configured subagent model | -| `permissionMode` | No | `default`, `acceptEdits`, `bypassPermissions`, `plan`, `ignore` | +| `model` | No | Model to use: `sonnet`, `opus`, `haiku`, full model ID, or `inherit`. Defaults to configured subagent model | +| `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` | | `maxTurns` | No | Maximum number of agentic turns the subagent can take | | `skills` | No | Comma-separated list of skills to preload. Injects full skill content into the subagent's context at startup | | `mcpServers` | No | MCP servers to make available to the subagent | | `hooks` | No | Component-scoped hooks (PreToolUse, PostToolUse, Stop) | | `memory` | No | Persistent memory directory scope: `user`, `project`, or `local` | | `background` | No | Set to `true` to always run this subagent as a background task | +| `effort` | No | Reasoning effort level: `low`, `medium`, `high`, or `max` | | `isolation` | No | Set to `worktree` to give the subagent its own git worktree | +| `initialPrompt` | No | Auto-submitted first turn when the subagent runs as the main agent | ### Tool Configuration Options @@ -187,11 +192,12 @@ claude --agents '{ **Priority of Agent Definitions:** Agent definitions are loaded with this priority order (first match wins): -1. **CLI-defined** - `--agents` flag (session-specific) -2. **User-level** - `~/.claude/agents/` (all projects) -3. **Project-level** - `.claude/agents/` (current project) +1. **CLI-defined** - `--agents` flag (session only, JSON) +2. **Project-level** - `.claude/agents/` (current project) +3. **User-level** - `~/.claude/agents/` (all projects) +4. **Plugin-level** - Plugin `agents/` directory -This allows CLI definitions to override both user and project agents for a single session. +This allows CLI definitions to override all other sources for a single session. --- @@ -341,6 +347,36 @@ You can explicitly request a specific subagent: > Ask the debugger subagent to investigate this error ``` +### @-Mention Invocation + +Use the `@` prefix to guarantee a specific subagent is invoked (bypasses automatic delegation heuristics): + +``` +> @"code-reviewer (agent)" review the auth module +``` + +### Session-Wide Agent + +Run an entire session using a specific agent as the main agent: + +```bash +# Via CLI flag +claude --agent code-reviewer + +# Via settings.json +{ + "agent": "code-reviewer" +} +``` + +### Listing Available Agents + +Use the `claude agents` command to list all configured agents from all sources: + +```bash +claude agents +``` + --- ## Resumable Agents @@ -591,8 +627,24 @@ Control how teammate activity is displayed: claude --teammate-mode tmux ``` +You can also set the display mode in `settings.json`: + +```json +{ + "teammateMode": "tmux" +} +``` + > **Note**: Split-pane mode requires tmux or iTerm2. It is not available in VS Code terminal, Windows Terminal, or Ghostty. +### Navigation + +Use `Shift+Down` to navigate between teammates in split-pane mode. + +### Team Configuration + +Team configurations are stored at `~/.claude/teams/{team-name}/config.json`. + ### Architecture ```mermaid @@ -673,6 +725,18 @@ Agent Teams introduce two additional [hook events](../06-hooks/): --- +## Plugin Subagent Security + +Plugin-provided subagents have restricted frontmatter capabilities for security. The following fields are **not allowed** in plugin subagent definitions: + +- `hooks` - Cannot define lifecycle hooks +- `mcpServers` - Cannot configure MCP servers +- `permissionMode` - Cannot override permission settings + +This prevents plugins from escalating privileges or executing arbitrary commands through subagent hooks. + +--- + ## Architecture ### High-Level Architecture @@ -752,6 +816,14 @@ graph TB - **Context efficiency** - Agents preserve main context, enabling longer sessions - **Latency** - Subagents start with clean slate and may add latency gathering initial context +### Key Behaviors + +- **No nested spawning** - Subagents cannot spawn other subagents +- **Background permissions** - Background subagents auto-deny any permissions that are not pre-approved +- **Backgrounding** - Press `Ctrl+B` to background a currently running task +- **Transcripts** - Subagent transcripts are stored at `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl` +- **Auto-compaction** - Subagent context auto-compacts at ~95% capacity (override with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` environment variable) + --- ## When to Use Subagents @@ -1064,6 +1136,6 @@ graph TD --- -*Last updated: February 2026* +*Last updated: March 2026* *This guide covers complete subagent configuration, delegation patterns, and best practices for Claude Code.* diff --git a/05-mcp/README.md b/05-mcp/README.md index f361b07..efc0b96 100644 --- a/05-mcp/README.md +++ b/05-mcp/README.md @@ -99,12 +99,20 @@ claude mcp add --transport stdio myserver --env KEY=value -- npx server ### SSE Transport (Deprecated) -Server-Sent Events transport is deprecated but still supported: +Server-Sent Events transport is deprecated in favor of `http` but still supported: ```bash claude mcp add --transport sse legacy-server https://example.com/sse ``` +### WebSocket Transport + +WebSocket transport for persistent bidirectional connections: + +```bash +claude mcp add --transport ws realtime-server wss://example.com/mcp +``` + ### Windows-Specific Note On native Windows (not WSL), use `cmd /c` for npx commands: @@ -131,6 +139,7 @@ claude mcp add --transport http my-service https://my-service.example.com/mcp \ | Feature | Description | |---------|-------------| | **Interactive OAuth** | Use `/mcp` to trigger the browser-based OAuth flow | +| **Pre-configured OAuth clients** | Built-in OAuth clients for common services like Notion, Stripe, and others (v2.1.30+) | | **Pre-configured credentials** | `--client-id`, `--client-secret`, `--callback-port` flags for automated setup | | **Token storage** | Tokens are stored securely in your system keychain | | **Step-up auth** | Supports step-up authentication for privileged operations | @@ -161,6 +170,8 @@ The URL must use `https://`. This option requires Claude Code v2.1.64 or later. MCP servers configured in your Claude.ai account are automatically available in Claude Code. This means any MCP connections you set up through the Claude.ai web interface will be accessible without additional configuration. +Claude.ai MCP connectors are also available in `--print` mode (v2.1.83+), enabling non-interactive and scripted usage. + To disable Claude.ai MCP servers in Claude Code, set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`: ```bash @@ -206,6 +217,28 @@ When MCP tool descriptions exceed 10% of the context window, Claude Code automat Claude Code supports MCP `list_changed` notifications. When an MCP server dynamically adds, removes, or modifies its available tools, Claude Code receives the update and adjusts its tool list automatically -- no reconnection or restart required. +## MCP Elicitation + +MCP servers can request structured input from the user via interactive dialogs (v2.1.49+). This allows an MCP server to ask for additional information mid-workflow -- for example, prompting for a confirmation, selecting from a list of options, or filling in required fields -- adding interactivity to MCP server interactions. + +## Tool Description and Instruction Cap + +As of v2.1.84, Claude Code enforces a **2 KB cap** on tool descriptions and instructions per MCP server. This prevents individual servers from consuming excessive context with overly verbose tool definitions, reducing context bloat and keeping interactions efficient. + +## MCP Prompts as Slash Commands + +MCP servers can expose prompts that appear as slash commands in Claude Code. Prompts are accessible using the naming convention: + +``` +/mcp____ +``` + +For example, if a server named `github` exposes a prompt called `review`, you can invoke it as `/mcp__github__review`. + +## Server Deduplication + +When the same MCP server is defined at multiple scopes (local, project, user), the local configuration takes precedence. This allows you to override project-level or user-level MCP settings with local customizations without conflicts. + ## MCP Resources via @ Mentions You can reference MCP resources directly in your prompts using the `@` mention syntax: @@ -662,6 +695,23 @@ Use the `${CLAUDE_PLUGIN_ROOT}` variable to reference paths relative to the plug } ``` +## Subagent-Scoped MCP + +MCP servers can be defined inline within agent frontmatter using the `mcpServers:` key, scoping them to a specific subagent rather than the entire project. This is useful when an agent needs access to a particular MCP server that other agents in the workflow do not require. + +```yaml +--- +mcpServers: + my-tool: + type: http + url: https://my-tool.example.com/mcp +--- + +You are an agent with access to my-tool for specialized operations. +``` + +Subagent-scoped MCP servers are only available within that agent's execution context and are not shared with the parent or sibling agents. + ## MCP Output Limits Claude Code enforces limits on MCP tool output to prevent context overflow: diff --git a/06-hooks/README.md b/06-hooks/README.md index 990f511..74b988f 100644 --- a/06-hooks/README.md +++ b/06-hooks/README.md @@ -9,21 +9,24 @@ Hooks are automated scripts that execute in response to specific events during C ## Overview -Hooks are shell commands or LLM prompts that execute automatically when specific events occur in Claude Code. They receive JSON input via stdin and communicate results via exit codes and JSON stdout output. +Hooks are automated actions (shell commands, HTTP webhooks, LLM prompts, or subagent evaluations) that execute automatically when specific events occur in Claude Code. They receive JSON input and communicate results via exit codes and JSON output. **Key features:** - Event-driven automation - JSON-based input/output -- Support for command, prompt, and HTTP hook types +- Support for command, prompt, HTTP, and agent hook types - Pattern matching for tool-specific hooks ## Configuration Hooks are configured in settings files with a specific structure: -- `~/.claude/settings.json` - User settings (global) -- `.claude/settings.json` - Project settings (committed) +- `~/.claude/settings.json` - User settings (all projects) +- `.claude/settings.json` - Project settings (shareable, committed) - `.claude/settings.local.json` - Local project settings (not committed) +- Managed policy - Organization-wide settings +- Plugin `hooks/hooks.json` - Plugin-scoped hooks +- Skill/Agent frontmatter - Component lifetime hooks ### Basic Configuration Structure @@ -52,7 +55,7 @@ Hooks are configured in settings files with a specific structure: |-------|-------------|---------| | `matcher` | Pattern to match tool names (case-sensitive) | `"Write"`, `"Edit\|Write"`, `"*"` | | `hooks` | Array of hook definitions | `[{ "type": "command", ... }]` | -| `type` | Hook type: `"command"` (bash), `"prompt"` (LLM), or `"http"` (webhook) | `"command"` | +| `type` | Hook type: `"command"` (bash), `"prompt"` (LLM), `"http"` (webhook), or `"agent"` (subagent) | `"command"` | | `command` | Shell command to execute | `"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"` | | `timeout` | Optional timeout in seconds (default 60) | `30` | | `once` | If `true`, run the hook only once per session | `true` | @@ -68,7 +71,7 @@ Hooks are configured in settings files with a specific structure: ## Hook Types -Claude Code supports three hook types: +Claude Code supports four hook types: ### Command Hooks @@ -120,30 +123,55 @@ LLM-evaluated prompts where the hook content is a prompt that Claude evaluates. The LLM evaluates the prompt and returns a structured decision (see [Prompt-Based Hooks](#prompt-based-hooks) for details). +### Agent Hooks + +Subagent-based verification hooks that spawn a dedicated agent to evaluate conditions or perform complex checks. Unlike prompt hooks (single-turn LLM evaluation), agent hooks can use tools and perform multi-step reasoning. + +```json +{ + "type": "agent", + "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.", + "timeout": 120 +} +``` + +**Key properties:** +- `"type": "agent"` -- identifies this as an agent hook +- `"prompt"` -- the task description for the subagent +- The agent can use tools (Read, Grep, Bash, etc.) to perform its evaluation +- Returns a structured decision similar to prompt hooks + ## Hook Events -Claude Code supports **18 hook events**: +Claude Code supports **25 hook events**: | Event | When Triggered | Matcher Input | Can Block | Common Use | |-------|---------------|---------------|-----------|------------| -| **InstructionsLoaded** | After CLAUDE.md files loaded | (none) | No | Modify/filter instructions | -| **Setup** | During initial setup | (none) | No | One-time initialization | -| **PreToolUse** | Before tool execution | Tool name | Yes | Validate, modify inputs | -| **PostToolUse** | After tool completion | Tool name | Yes (block) | Add context, feedback | +| **SessionStart** | Session begins/resumes/clear/compact | startup/resume/clear/compact | No | Environment setup | +| **InstructionsLoaded** | After CLAUDE.md or rules file loaded | (none) | No | Modify/filter instructions | +| **UserPromptSubmit** | User submits prompt | (none) | Yes | Validate prompts | +| **PreToolUse** | Before tool execution | Tool name | Yes (allow/deny/ask) | Validate, modify inputs | | **PermissionRequest** | Permission dialog shown | Tool name | Yes | Auto-approve/deny | +| **PostToolUse** | After tool succeeds | Tool name | No | Add context, feedback | +| **PostToolUseFailure** | Tool execution fails | Tool name | No | Error handling, logging | | **Notification** | Notification sent | Notification type | No | Custom notifications | -| **UserPromptSubmit** | Before prompt processed | (none) | Yes | Validate prompts | -| **Stop** | Session or subagent finishes | (none) | Yes | Task completion check | -| **SubagentStart** | Subagent begins execution | Agent type name | No | Subagent setup | -| **SubagentStop** | Subagent completes | Agent type name | Yes | Subagent validation | -| **PreCompact** | Before compact operation | manual/auto | No | Pre-compact actions | -| **SessionStart** | Session begins/resumes | startup/resume/clear/compact | No | Environment setup | -| **SessionEnd** | Session ends (cleanup only) | (none) | No | Cleanup, final logging | -| **WorktreeCreate** | Worktree created | (none) | No | Worktree initialization | -| **WorktreeRemove** | Worktree removed | (none) | No | Worktree cleanup | -| **ConfigChange** | Configuration files change | (none) | No | React to config updates | -| **TeammateIdle** | Agent team teammate about to idle | (none) | No | Teammate coordination | -| **TaskCompleted** | Task being marked complete | (none) | No | Post-task actions | +| **SubagentStart** | Subagent spawned | Agent type name | No | Subagent setup | +| **SubagentStop** | Subagent finishes | Agent type name | Yes | Subagent validation | +| **Stop** | Claude finishes responding | (none) | Yes | Task completion check | +| **StopFailure** | API error ends turn | (none) | No | Error recovery, logging | +| **TeammateIdle** | Agent team teammate idle | (none) | Yes | Teammate coordination | +| **TaskCompleted** | Task marked complete | (none) | Yes | Post-task actions | +| **TaskCreated** | Task created via TaskCreate | (none) | No | Task tracking, logging | +| **ConfigChange** | Config file changes | (none) | Yes (except policy) | React to config updates | +| **CwdChanged** | Working directory changes | (none) | No | Directory-specific setup | +| **FileChanged** | Watched file changes | (none) | No | File monitoring, rebuild | +| **PreCompact** | Before context compaction | manual/auto | No | Pre-compact actions | +| **PostCompact** | After compaction completes | (none) | No | Post-compact actions | +| **WorktreeCreate** | Worktree being created | (none) | Yes (path return) | Worktree initialization | +| **WorktreeRemove** | Worktree being removed | (none) | No | Worktree cleanup | +| **Elicitation** | MCP server requests user input | (none) | Yes | Input validation | +| **ElicitationResult** | User responds to elicitation | (none) | Yes | Response processing | +| **SessionEnd** | Session terminates | (none) | No | Cleanup, final logging | ### PreToolUse @@ -283,7 +311,7 @@ Runs when session starts or resumes. Can persist environment variables. **Matchers:** `startup`, `resume`, `clear`, `compact` -**Special feature:** Use `CLAUDE_ENV_FILE` to persist environment variables: +**Special feature:** Use `CLAUDE_ENV_FILE` to persist environment variables (also available in `CwdChanged` and `FileChanged` hooks): ```bash #!/bin/bash @@ -457,9 +485,10 @@ All hooks receive JSON input via stdin: | Variable | Availability | Description | |----------|-------------|-------------| | `CLAUDE_PROJECT_DIR` | All hooks | Absolute path to project root | -| `CLAUDE_ENV_FILE` | SessionStart only | File path for persisting env vars | -| `CLAUDE_CODE_REMOTE` | All hooks | `"true"` if running in web environment | +| `CLAUDE_ENV_FILE` | SessionStart, CwdChanged, FileChanged | File path for persisting env vars | +| `CLAUDE_CODE_REMOTE` | All hooks | `"true"` if running in remote environments | | `${CLAUDE_PLUGIN_ROOT}` | Plugin hooks | Path to plugin directory | +| `${CLAUDE_PLUGIN_DATA}` | Plugin hooks | Path to plugin data directory | | `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | SessionEnd hooks | Configurable timeout in milliseconds for SessionEnd hooks (overrides default) | ## Prompt-Based Hooks @@ -888,6 +917,7 @@ Plugins can include hooks in their `hooks/hooks.json` file: **Environment Variables in Plugin Hooks:** - `${CLAUDE_PLUGIN_ROOT}` - Path to the plugin directory +- `${CLAUDE_PLUGIN_DATA}` - Path to the plugin data directory This allows plugins to include custom validation and automation hooks. diff --git a/07-plugins/README.md b/07-plugins/README.md index b8b7a3f..e7d92f5 100644 --- a/07-plugins/README.md +++ b/07-plugins/README.md @@ -211,6 +211,66 @@ Once configured, LSP servers provide: - **Hover information** — type signatures and documentation on hover - **Symbol listing** — browse symbols in the current file or workspace +## Plugin Options (v2.1.83+) + +Plugins can declare user-configurable options in the manifest via `userConfig`. Values marked `sensitive: true` are stored in the system keychain rather than plain-text settings files: + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "userConfig": { + "apiKey": { + "description": "API key for the service", + "sensitive": true + }, + "region": { + "description": "Deployment region", + "default": "us-east-1" + } + } +} +``` + +## Persistent Plugin Data (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+) + +Plugins have access to a persistent state directory via the `${CLAUDE_PLUGIN_DATA}` environment variable. This directory is unique per plugin and survives across sessions, making it suitable for caches, databases, and other persistent state: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" + } + ] + } +} +``` + +The directory is created automatically when the plugin is installed. Files stored here persist until the plugin is uninstalled. + +## Inline Plugin via Settings (`source: 'settings'`) (v2.1.80+) + +Plugins can be defined inline in settings files as marketplace entries using the `source: 'settings'` field. This allows embedding a plugin definition directly without requiring a separate repository or marketplace: + +```json +{ + "pluginMarketplaces": [ + { + "name": "inline-tools", + "source": "settings", + "plugins": [ + { + "name": "quick-lint", + "source": "./local-plugins/quick-lint" + } + ] + } + ] +} +``` + ## Plugin Settings Plugins can ship a `settings.json` file to provide default configuration. This currently supports the `agent` key, which sets the main thread agent for the plugin: @@ -394,8 +454,8 @@ Enterprise and advanced users can control marketplace behavior through settings: | Setting | Description | |---------|-------------| | `extraKnownMarketplaces` | Add additional marketplace sources beyond the defaults | -| `blockedMarketplaces` | Admin-managed setting to restrict specific marketplaces | | `strictKnownMarketplaces` | Control which marketplaces users are allowed to add | +| `deniedPlugins` | Admin-managed blocklist to prevent specific plugins from being installed | ### Additional Marketplace Features @@ -534,11 +594,26 @@ graph LR | **Marketplace** | No | No | No | Yes | | **Distribution** | Repository | Repository | Repository | Marketplace | +## Plugin CLI Commands + +All plugin operations are available as CLI commands: + +```bash +claude plugin install @ # Install from a marketplace +claude plugin uninstall # Remove a plugin +claude plugin list # List installed plugins +claude plugin enable # Enable a disabled plugin +claude plugin disable # Disable a plugin +claude plugin validate # Validate plugin structure +``` + ## Installation Methods ### From Marketplace ```bash /plugin install plugin-name +# or from CLI: +claude plugin install plugin-name@marketplace-name ``` ### Enable / Disable (with auto-detected scope) @@ -604,6 +679,40 @@ This launches Claude Code with your plugin loaded, allowing you to: - Check LSP server configurations - Check for any configuration errors +## Hot-Reload + +Plugins support hot-reload during development. When you modify plugin files, Claude Code can detect changes automatically. You can also force a reload with: + +```bash +/reload-plugins +``` + +This re-reads all plugin manifests, commands, agents, skills, hooks, and MCP/LSP configurations without restarting the session. + +## Managed Settings for Plugins + +Administrators can control plugin behavior across an organization using managed settings: + +| Setting | Description | +|---------|-------------| +| `enabledPlugins` | Allowlist of plugins that are enabled by default | +| `deniedPlugins` | Blocklist of plugins that cannot be installed | +| `extraKnownMarketplaces` | Add additional marketplace sources beyond the defaults | +| `strictKnownMarketplaces` | Restrict which marketplaces users are allowed to add | +| `allowedChannelPlugins` | Control which plugins are permitted per release channel | + +These settings can be applied at the organization level via managed configuration files and take precedence over user-level settings. + +## Plugin Security + +Plugin subagents run in a restricted sandbox. The following frontmatter keys are **not allowed** in plugin subagent definitions: + +- `hooks` -- Subagents cannot register event handlers +- `mcpServers` -- Subagents cannot configure MCP servers +- `permissionMode` -- Subagents cannot override the permission model + +This ensures that plugins cannot escalate privileges or modify the host environment beyond their declared scope. + ## Publishing a Plugin **Steps to publish:** diff --git a/08-checkpoints/README.md b/08-checkpoints/README.md index 0f1adb4..0026185 100644 --- a/08-checkpoints/README.md +++ b/08-checkpoints/README.md @@ -33,11 +33,14 @@ You can access and manage checkpoints in two primary ways: Press `Esc` twice (`Esc` + `Esc`) to open the checkpoint interface and browse saved checkpoints. ### Using Slash Command -Use the `/rewind` command for quick access: +Use the `/rewind` command (alias: `/checkpoint`) for quick access: ```bash # Open rewind interface /rewind + +# Or use the alias +/checkpoint ``` ## Rewind Options @@ -274,6 +277,7 @@ Use both together: - **`Esc` + `Esc`** - Open checkpoint browser - **`/rewind`** - Alternative way to access checkpoints +- **`/checkpoint`** - Alias for `/rewind` ## Related Concepts diff --git a/09-advanced-features/README.md b/09-advanced-features/README.md index 4583a07..44b512f 100644 --- a/09-advanced-features/README.md +++ b/09-advanced-features/README.md @@ -5,31 +5,34 @@ # Advanced Features -Comprehensive guide to Claude Code's advanced capabilities including planning mode, extended thinking, background tasks, permission modes, print mode (non-interactive), session management, interactive features, remote control, web sessions, desktop app, task list, prompt suggestions, git worktrees, sandboxing, managed settings, and configuration. +Comprehensive guide to Claude Code's advanced capabilities including planning mode, extended thinking, auto mode, background tasks, permission modes, print mode (non-interactive), session management, interactive features, channels, voice dictation, remote control, web sessions, desktop app, task list, prompt suggestions, git worktrees, sandboxing, managed settings, and configuration. ## Table of Contents 1. [Overview](#overview) 2. [Planning Mode](#planning-mode) 3. [Extended Thinking](#extended-thinking) -4. [Background Tasks](#background-tasks) -5. [Scheduled Tasks](#scheduled-tasks) -6. [Permission Mode](#permission-mode) -7. [Headless Mode](#headless-mode) -8. [Session Management](#session-management) -9. [Interactive Features](#interactive-features) -10. [Chrome Integration](#chrome-integration) -11. [Remote Control](#remote-control) -12. [Web Sessions](#web-sessions) -13. [Desktop App](#desktop-app) -14. [Task List](#task-list) -15. [Prompt Suggestions](#prompt-suggestions) -16. [Git Worktrees](#git-worktrees) -17. [Sandboxing](#sandboxing) -18. [Managed Settings (Enterprise)](#managed-settings-enterprise) -19. [Configuration and Settings](#configuration-and-settings) -20. [Best Practices](#best-practices) -21. [Related Concepts](#related-concepts) +4. [Auto Mode](#auto-mode) +5. [Background Tasks](#background-tasks) +6. [Scheduled Tasks](#scheduled-tasks) +7. [Permission Modes](#permission-modes) +8. [Headless Mode](#headless-mode) +9. [Session Management](#session-management) +10. [Interactive Features](#interactive-features) +11. [Voice Dictation](#voice-dictation) +12. [Channels](#channels) +13. [Chrome Integration](#chrome-integration) +14. [Remote Control](#remote-control) +15. [Web Sessions](#web-sessions) +16. [Desktop App](#desktop-app) +17. [Task List](#task-list) +18. [Prompt Suggestions](#prompt-suggestions) +19. [Git Worktrees](#git-worktrees) +20. [Sandboxing](#sandboxing) +21. [Managed Settings (Enterprise)](#managed-settings-enterprise) +22. [Configuration and Settings](#configuration-and-settings) +23. [Best Practices](#best-practices) +24. [Related Concepts](#related-concepts) --- @@ -40,11 +43,14 @@ Advanced features in Claude Code extend the core capabilities with planning, rea **Key advanced features include:** - **Planning Mode**: Create detailed implementation plans before coding - **Extended Thinking**: Deep reasoning for complex problems +- **Auto Mode**: Background safety classifier reviews each action before execution (Research Preview) - **Background Tasks**: Run long operations without blocking the conversation -- **Permission Modes**: Control what Claude can do (`default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions`) +- **Permission Modes**: Control what Claude can do (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`) - **Print Mode**: Run Claude Code non-interactively for automation and CI/CD (`claude -p`) - **Session Management**: Manage multiple work sessions - **Interactive Features**: Keyboard shortcuts, multi-line input, and command history +- **Voice Dictation**: Push-to-talk voice input with 20-language STT support +- **Channels**: MCP servers push messages into running sessions (Research Preview) - **Remote Control**: Control Claude Code from Claude.ai or the Claude app - **Web Sessions**: Run Claude Code in the browser at claude.ai/code - **Desktop App**: Standalone app for visual diff review and multiple sessions @@ -211,12 +217,13 @@ Extended thinking is a deliberate, step-by-step reasoning process where Claude: **Automatic activation**: - Enabled by default for all models (Opus 4.6, Sonnet 4.6, Haiku 4.5) -- Opus 4.6: Adaptive reasoning with effort levels: low (○), medium (◐), high (●) +- Opus 4.6: Adaptive reasoning with effort levels: `low` (○), `medium` (◐), `high` (●), `max` (Opus 4.6 only) - Other models: Fixed budget up to 31,999 tokens **Configuration methods**: - Toggle: `Alt+T` / `Option+T`, or via `/config` - View reasoning: `Ctrl+O` (verbose mode) +- Set effort: `/effort` command or `--effort` flag **Custom budget**: ```bash @@ -225,10 +232,20 @@ export MAX_THINKING_TOKENS=1024 **Effort level** (Opus 4.6 only): ```bash -export CLAUDE_CODE_EFFORT_LEVEL=high # low (○), medium (◐), or high (●) +export CLAUDE_CODE_EFFORT_LEVEL=high # low (○), medium (◐), high (●), or max (Opus 4.6 only) ``` -> **Note:** Words like "think" or "ultrathink" in prompts are interpreted as regular prompt instructions, not special keywords or triggers. +**CLI flag**: +```bash +claude --effort high "complex architectural review" +``` + +**Slash command**: +``` +/effort high +``` + +> **Note:** The keyword "ultrathink" in prompts activates deep reasoning mode. Effort levels `low`, `medium`, `high`, and `max` (Opus 4.6 only) control how much reasoning Claude performs. ### Benefits of Extended Thinking @@ -310,17 +327,101 @@ This approach balances your current constraints (team size, timeline, DevOps res ### Extended Thinking Configuration -Extended thinking is controlled via environment variables and keyboard shortcuts rather than JSON config: +Extended thinking is controlled via environment variables, keyboard shortcuts, and CLI flags: ```bash # Set thinking token budget export MAX_THINKING_TOKENS=16000 -# Set effort level (Opus 4.6 only): low (○), medium (◐), or high (●) +# Set effort level (Opus 4.6 only): low (○), medium (◐), high (●), or max (Opus 4.6 only) export CLAUDE_CODE_EFFORT_LEVEL=high ``` -Toggle during a session with `Alt+T` / `Option+T`, or configure via `/config`. +Toggle during a session with `Alt+T` / `Option+T`, set effort with `/effort`, or configure via `/config`. + +--- + +## Auto Mode + +Auto Mode is a Research Preview permission mode (March 2026) that uses a background safety classifier to review each action before execution. It allows Claude to work autonomously while blocking dangerous operations. + +### Requirements + +- **Plan**: Team plan (Enterprise and API rolling out) +- **Model**: Claude Sonnet 4.6 or Opus 4.6 +- **Classifier**: Runs on Claude Sonnet 4.6 (adds extra token cost) + +### Enabling Auto Mode + +```bash +# Unlock auto mode with CLI flag +claude --enable-auto-mode + +# Then cycle to it with Shift+Tab in the REPL +``` + +Or set it as the default permission mode: + +```bash +claude --permission-mode auto +``` + +Setting via config: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### How the Classifier Works + +The background classifier evaluates each action using the following decision order: + +1. **Allow/deny rules** -- Explicit permission rules are checked first +2. **Read-only/edits auto-approved** -- File reads and edits pass automatically +3. **Classifier** -- The background classifier reviews the action +4. **Fallback** -- Falls back to prompting after 3 consecutive or 20 total blocks + +### Default Blocked Actions + +Auto mode blocks the following by default: + +| Blocked Action | Example | +|----------------|---------| +| Pipe-to-shell installs | `curl \| bash` | +| Sending sensitive data externally | API keys, credentials over network | +| Production deploys | Deploy commands targeting production | +| Mass deletion | `rm -rf` on large directories | +| IAM changes | Permission and role modifications | +| Force push to main | `git push --force origin main` | + +### Default Allowed Actions + +| Allowed Action | Example | +|----------------|---------| +| Local file operations | Read, write, edit project files | +| Declared dependency installs | `npm install`, `pip install` from manifest | +| Read-only HTTP | `curl` for fetching documentation | +| Pushing to current branch | `git push origin feature-branch` | + +### Configuring Auto Mode + +**Print default rules as JSON**: +```bash +claude auto-mode defaults +``` + +**Configure trusted infrastructure** via the `autoMode.environment` managed setting for enterprise deployments. This allows administrators to define trusted CI/CD environments, deployment targets, and infrastructure patterns. + +### Fallback Behavior + +When the classifier is uncertain, auto mode falls back to prompting the user: +- After **3 consecutive** classifier blocks +- After **20 total** classifier blocks in a session + +This ensures the user always retains control when the classifier cannot confidently approve an action. --- @@ -497,6 +598,16 @@ in 45 minutes, run the integration tests | **Missed fires** | No catch-up — skipped if Claude Code was not running | | **Persistence** | Not persisted across restarts | +### Cloud Scheduled Tasks + +Use `/schedule` to create Cloud scheduled tasks that run on Anthropic infrastructure: + +``` +/schedule daily at 9am run the test suite and report failures +``` + +Cloud scheduled tasks persist across restarts and do not require Claude Code to be running locally. + ### Disabling scheduled tasks ```bash @@ -523,17 +634,20 @@ Permission modes control what actions Claude can take without explicit approval. | Mode | Behavior | |---|---| -| `default` | Standard: prompts for permission | -| `acceptEdits` | Auto-accepts file edits | -| `plan` | Read-only analysis mode | -| `dontAsk` | Auto-denies unless pre-approved | -| `bypassPermissions` | Skips all checks (dangerous) | +| `default` | Read files only; prompts for all other actions | +| `acceptEdits` | Read and edit files; prompts for commands | +| `plan` | Read files only (research mode, no edits) | +| `auto` | All actions with background safety classifier checks (Research Preview) | +| `bypassPermissions` | All actions, no permission checks (dangerous) | +| `dontAsk` | Only pre-approved tools execute; all others denied | + +Cycle through modes with `Shift+Tab` in the CLI. Set a default with the `--permission-mode` flag or the `permissions.defaultMode` setting. ### Activation Methods **Keyboard shortcut**: ```bash -Shift + Tab # or Alt + M on Windows/Linux +Shift + Tab # Cycle through all 6 modes ``` **Slash command**: @@ -544,11 +658,16 @@ Shift + Tab # or Alt + M on Windows/Linux **CLI flag**: ```bash claude --permission-mode plan +claude --permission-mode auto ``` -**Environment variable**: -```bash -export CLAUDE_PERMISSION_MODE=plan +**Setting**: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} ``` ### Permission Mode Examples @@ -989,6 +1108,70 @@ Use this for quick command execution without switching contexts. --- +## Voice Dictation + +Voice Dictation provides push-to-talk voice input for Claude Code, allowing you to speak your prompts instead of typing them. + +### Activating Voice Dictation + +``` +/voice +``` + +### Features + +| Feature | Description | +|---------|-------------| +| **Push-to-talk** | Hold a key to record, release to send | +| **20 languages** | Speech-to-text supports 20 languages | +| **Custom keybinding** | Configure the push-to-talk key via `/keybindings` | +| **Account requirement** | Requires a Claude.ai account for STT processing | + +### Configuration + +Customize the push-to-talk keybinding in your keybindings file (`/keybindings`). Voice dictation uses your Claude.ai account for speech-to-text processing. + +--- + +## Channels + +Channels (Research Preview) allow MCP servers to push messages into running Claude Code sessions, enabling real-time integrations with external services. + +### Subscribing to Channels + +```bash +# Subscribe to channel plugins at startup +claude --channels discord,telegram +``` + +### Supported Integrations + +| Integration | Description | +|-------------|-------------| +| **Discord** | Receive and respond to Discord messages in your session | +| **Telegram** | Receive and respond to Telegram messages in your session | + +### Configuration + +**Managed setting** for enterprise deployments: + +```json +{ + "allowedChannelPlugins": ["discord", "telegram"] +} +``` + +The `allowedChannelPlugins` managed setting controls which channel plugins are permitted across the organization. + +### How It Works + +1. MCP servers act as channel plugins that connect to external services +2. Incoming messages are pushed into the active Claude Code session +3. Claude can read and respond to messages within the session context +4. Channel plugins must be approved via the `allowedChannelPlugins` managed setting + +--- + ## Chrome Integration Chrome Integration connects Claude Code to your Chrome or Microsoft Edge browser for live web automation and debugging. This is a beta feature available since v2.0.73+ (Edge support added in v1.0.36+). @@ -1291,6 +1474,26 @@ Worktrees are created at: /.claude/worktrees/ ``` +### Sparse Checkout for Monorepos + +Use the `worktree.sparsePaths` setting to perform sparse-checkout in monorepos, reducing disk usage and clone time: + +```json +{ + "worktree": { + "sparsePaths": ["packages/my-package", "shared/"] + } +} +``` + +### Worktree Tools and Hooks + +| Item | Description | +|------|-------------| +| `ExitWorktree` | Tool to exit and clean up the current worktree | +| `WorktreeCreate` | Hook event fired when a worktree is created | +| `WorktreeRemove` | Hook event fired when a worktree is removed | + ### Auto-Cleanup If no changes are made in the worktree, it is automatically cleaned up when the session ends. @@ -1300,6 +1503,7 @@ If no changes are made in the worktree, it is automatically cleaned up when the - Work on a feature branch while keeping main branch untouched - Run tests in isolation without affecting the working directory - Try experimental changes in a disposable environment +- Sparse-checkout specific packages in monorepos for faster startup --- @@ -1307,11 +1511,53 @@ If no changes are made in the worktree, it is automatically cleaned up when the Sandboxing provides OS-level filesystem and network isolation for Bash commands executed by Claude Code. This is complementary to permission rules and provides an additional security layer. +### Enabling Sandboxing + +**Slash command**: +``` +/sandbox +``` + +**CLI flags**: +```bash +claude --sandbox # Enable sandboxing +claude --no-sandbox # Disable sandboxing +``` + +### Configuration Settings + +| Setting | Description | +|---------|-------------| +| `sandbox.enabled` | Enable or disable sandboxing | +| `sandbox.failIfUnavailable` | Fail if sandboxing cannot be activated | +| `sandbox.filesystem.allowWrite` | Paths allowed for write access | +| `sandbox.filesystem.allowRead` | Paths allowed for read access | +| `sandbox.filesystem.denyRead` | Paths denied for read access | +| `sandbox.enableWeakerNetworkIsolation` | Enable weaker network isolation on macOS | + +### Example Configuration + +```json +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true, + "filesystem": { + "allowWrite": ["/Users/me/project"], + "allowRead": ["/Users/me/project", "/usr/local/lib"], + "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] + }, + "enableWeakerNetworkIsolation": true + } +} +``` + ### How It Works - Bash commands run in a sandboxed environment with restricted filesystem access - Network access can be isolated to prevent unintended external connections - Works alongside permission rules for defense in depth +- On macOS, use `sandbox.enableWeakerNetworkIsolation` for network restrictions (full network isolation is not available on macOS) ### Use Cases @@ -1327,11 +1573,23 @@ Managed Settings enable enterprise administrators to deploy Claude Code configur ### Deployment Methods -| Platform | Method | -|----------|--------| -| macOS | Managed plist files (MDM) | -| Windows | Windows Registry | -| Cross-platform | Managed configuration files | +| Platform | Method | Since | +|----------|--------|-------| +| macOS | Managed plist files (MDM) | v2.1.51+ | +| Windows | Windows Registry | v2.1.51+ | +| Cross-platform | Managed configuration files | v2.1.51+ | +| Cross-platform | Managed drop-ins (`managed-settings.d/` directory) | v2.1.83+ | + +### Managed Drop-ins + +Since v2.1.83, administrators can deploy multiple managed settings files into a `managed-settings.d/` directory. Files are merged in alphabetical order, allowing modular configuration across teams: + +``` +~/.claude/managed-settings.d/ + 00-org-defaults.json + 10-team-policies.json + 20-project-overrides.json +``` ### Available Managed Settings @@ -1339,6 +1597,8 @@ Managed Settings enable enterprise administrators to deploy Claude Code configur |---------|-------------| | `disableBypassPermissionsMode` | Prevent users from enabling bypass permissions | | `availableModels` | Restrict which models users can select | +| `allowedChannelPlugins` | Control which channel plugins are permitted | +| `autoMode.environment` | Configure trusted infrastructure for auto mode | | Custom policies | Organization-specific permission and tool policies | ### Example: macOS Plist @@ -1447,8 +1707,14 @@ export CLAUDE_CODE_EFFORT_LEVEL=high # Feature toggles export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true +export CLAUDE_CODE_DISABLE_CRON=1 +export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true +export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true +export CLAUDE_CODE_DISABLE_1M_CONTEXT=true +export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false export CLAUDE_CODE_ENABLE_TASKS=true +export CLAUDE_CODE_SIMPLE=true # Set by --bare flag # MCP configuration export MAX_MCP_OUTPUT_TOKENS=50000 @@ -1459,6 +1725,18 @@ export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks # Agent teams (experimental) export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true + +# Subagent and plugin configuration +export CLAUDE_CODE_SUBAGENT_MODEL=sonnet +export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins +export CLAUDE_CODE_NEW_INIT=true + +# Subprocess and streaming +export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD" +export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 +export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000 +export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model +export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 ``` ### Configuration Management Commands @@ -1525,6 +1803,7 @@ Create `.claude/config.json` in your project: - ✅ Use `plan` for code review (read-only) - ✅ Use `default` for interactive development - ✅ Use `acceptEdits` for automation workflows +- ✅ Use `auto` for autonomous work with safety guardrails - ❌ Don't use `bypassPermissions` unless absolutely necessary ### Sessions diff --git a/09-advanced-features/config-examples.json b/09-advanced-features/config-examples.json index 9adefa5..30b53ff 100644 --- a/09-advanced-features/config-examples.json +++ b/09-advanced-features/config-examples.json @@ -39,7 +39,7 @@ "temperature": 0.3 }, "permissions": { - "mode": "readonly" + "mode": "plan" }, "extendedThinking": { "enabled": true, @@ -140,7 +140,7 @@ "temperature": 0.2 }, "permissions": { - "mode": "readonly" + "mode": "plan" }, "extendedThinking": { "enabled": true, @@ -228,6 +228,28 @@ } }, + "autonomous": { + "name": "Autonomous Development", + "description": "Configuration for autonomous work with auto mode safety checks", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.5 + }, + "permissions": { + "mode": "auto" + }, + "sandbox": { + "enabled": true, + "failIfUnavailable": false + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 3 + } + } + }, + "documentation": { "name": "Documentation Writing", "description": "Configuration for writing documentation", diff --git a/10-cli/README.md b/10-cli/README.md index 2989efe..1003c2e 100644 --- a/10-cli/README.md +++ b/10-cli/README.md @@ -39,7 +39,9 @@ graph TD | `claude mcp` | Configure MCP servers | See [MCP documentation](../05-mcp/) | | `claude mcp serve` | Run Claude Code as an MCP server | `claude mcp serve` | | `claude agents` | List all configured subagents | `claude agents` | -| `claude remote-control` | Start Remote Control session | `claude remote-control` | +| `claude auto-mode defaults` | Print auto mode default rules as JSON | `claude auto-mode defaults` | +| `claude remote-control` | Start Remote Control server | `claude remote-control` | +| `claude plugin` | Manage plugins (install, enable, disable) | `claude plugin install my-plugin` | | `claude auth login` | Log in (supports `--email`, `--sso`) | `claude auth login --email user@example.com` | | `claude auth logout` | Log out of current account | `claude auth logout` | | `claude auth status` | Check auth status (exit 0 if logged in, 1 if not) | `claude auth status` | @@ -53,10 +55,17 @@ graph TD | `-r, --resume` | Resume specific session by ID or name | `claude --resume auth-refactor` | | `-v, --version` | Output version number | `claude -v` | | `-w, --worktree` | Start in isolated git worktree | `claude -w` | +| `-n, --name` | Session display name | `claude -n "auth-refactor"` | | `--from-pr ` | Resume sessions linked to GitHub PR | `claude --from-pr 42` | | `--remote "task"` | Create web session on claude.ai | `claude --remote "implement API"` | +| `--remote-control, --rc` | Interactive session with Remote Control | `claude --rc` | | `--teleport` | Resume web session locally | `claude --teleport` | | `--teammate-mode` | Agent team display mode | `claude --teammate-mode tmux` | +| `--bare` | Minimal mode (skip hooks, skills, plugins, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--enable-auto-mode` | Unlock auto permission mode | `claude --enable-auto-mode` | +| `--channels` | Subscribe to MCP channel plugins | `claude --channels discord,telegram` | +| `--chrome` / `--no-chrome` | Enable/disable Chrome browser integration | `claude --chrome` | +| `--effort` | Set thinking effort level | `claude --effort high` | | `--init` / `--init-only` | Run initialization hooks | `claude --init` | | `--maintenance` | Run maintenance hooks and exit | `claude --maintenance` | | `--disable-slash-commands` | Disable all skills and slash commands | `claude --disable-slash-commands` | @@ -98,9 +107,10 @@ claude -p "list todos" | grep "URGENT" | Flag | Description | Example | |------|-------------|---------| | `--model` | Set model (sonnet, opus, haiku, or full name) | `claude --model opus` | -| `--fallback-model` | Fallback when overloaded (print mode) | `claude -p --fallback-model sonnet "query"` | +| `--fallback-model` | Automatic model fallback when overloaded | `claude -p --fallback-model sonnet "query"` | | `--agent` | Specify agent for session | `claude --agent my-custom-agent` | | `--agents` | Define custom subagents via JSON | See [Agents Configuration](#agents-configuration) | +| `--effort` | Set effort level (low, medium, high, max) | `claude --effort high` | ### Model Selection Examples @@ -156,12 +166,13 @@ claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py" | Flag | Description | Example | |------|-------------|---------| -| `--tools` | Specify available tools | `claude -p --tools "Bash,Edit,Read" "query"` | +| `--tools` | Restrict available built-in tools | `claude -p --tools "Bash,Edit,Read" "query"` | | `--allowedTools` | Tools that execute without prompting | `"Bash(git log:*)" "Read"` | | `--disallowedTools` | Tools removed from context | `"Bash(rm:*)" "Edit"` | | `--dangerously-skip-permissions` | Skip all permission prompts | `claude --dangerously-skip-permissions` | -| `--permission-mode` | Begin in specified permission mode | `claude --permission-mode plan` | +| `--permission-mode` | Begin in specified permission mode | `claude --permission-mode auto` | | `--permission-prompt-tool` | MCP tool for permission handling | `claude -p --permission-prompt-tool mcp_auth "query"` | +| `--enable-auto-mode` | Unlock auto permission mode | `claude --enable-auto-mode` | ### Permission Examples @@ -183,11 +194,12 @@ claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" | Flag | Description | Options | Example | |------|-------------|---------|---------| -| `--output-format` | Specify output format (print mode) | text, json, stream-json | `claude -p --output-format json "query"` | -| `--input-format` | Specify input format (print mode) | text, stream-json | `claude -p --input-format stream-json` | +| `--output-format` | Specify output format (print mode) | `text`, `json`, `stream-json` | `claude -p --output-format json "query"` | +| `--input-format` | Specify input format (print mode) | `text`, `stream-json` | `claude -p --input-format stream-json` | | `--verbose` | Enable verbose logging | | `claude --verbose` | -| `--include-partial-messages` | Include streaming events | Requires stream-json | `claude -p --output-format stream-json --include-partial-messages "query"` | +| `--include-partial-messages` | Include streaming events | Requires `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` | | `--json-schema` | Get validated JSON matching schema | | `claude -p --json-schema '{"type":"object"}' "query"` | +| `--max-budget-usd` | Maximum spend for print mode | | `claude -p --max-budget-usd 5.00 "query"` | ### Output Format Examples @@ -211,8 +223,9 @@ claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}} | Flag | Description | Example | |------|-------------|---------| | `--add-dir` | Add additional working directories | `claude --add-dir ../apps ../lib` | -| `--setting-sources` | Load setting sources | `claude --setting-sources user,project` | +| `--setting-sources` | Comma-separated setting sources | `claude --setting-sources user,project` | | `--settings` | Load settings from file or JSON | `claude --settings ./settings.json` | +| `--plugin-dir` | Load plugins from directory (repeatable) | `claude --plugin-dir ./my-plugin` | ### Multi-Directory Example @@ -229,7 +242,8 @@ claude --settings '{"model":"opus","verbose":true}' "complex task" | Flag | Description | Example | |------|-------------|---------| | `--mcp-config` | Load MCP servers from JSON | `claude --mcp-config ./mcp.json` | -| `--strict-mcp-config` | Only use specified MCP servers | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--strict-mcp-config` | Only use specified MCP config | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--channels` | Subscribe to MCP channel plugins | `claude --channels discord,telegram` | ### MCP Examples @@ -296,6 +310,13 @@ The original session remains unchanged, and the fork becomes a new independent s | `--enable-lsp-logging` | Enable verbose LSP logging | `claude --enable-lsp-logging` | | `--betas` | Beta headers for API requests | `claude --betas interleaved-thinking` | | `--plugin-dir` | Load plugins from directory (repeatable) | `claude --plugin-dir ./my-plugin` | +| `--enable-auto-mode` | Unlock auto permission mode | `claude --enable-auto-mode` | +| `--effort` | Set thinking effort level | `claude --effort high` | +| `--bare` | Minimal mode (skip hooks, skills, plugins, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--channels` | Subscribe to MCP channel plugins | `claude --channels discord` | +| `--fork-session` | Create new session ID when resuming | `claude --resume abc --fork-session` | +| `--max-budget-usd` | Maximum spend (print mode) | `claude -p --max-budget-usd 5.00 "query"` | +| `--json-schema` | Validated JSON output | `claude -p --json-schema '{"type":"object"}' "q"` | ### Advanced Examples @@ -659,10 +680,18 @@ claude --model opusplan "design and implement the API" Opus 4.6 supports adaptive reasoning with effort levels: ```bash +# Set effort level via CLI flag +claude --effort high "complex review" + +# Set effort level via slash command +/effort high + # Set effort level via environment variable -export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, or high +export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, high, or max (Opus 4.6 only) ``` +The "ultrathink" keyword in prompts activates deep reasoning. The `max` effort level is exclusive to Opus 4.6. + --- ## Key Environment Variables @@ -671,17 +700,31 @@ export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, or high |----------|-------------| | `ANTHROPIC_API_KEY` | API key for authentication | | `ANTHROPIC_MODEL` | Override default model | +| `ANTHROPIC_CUSTOM_MODEL_OPTION` | Custom model option for API | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Override default Opus model ID | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | Override default Sonnet model ID | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Override default Haiku model ID | | `MAX_THINKING_TOKENS` | Set extended thinking token budget | -| `CLAUDE_CODE_EFFORT_LEVEL` | Set effort level for Opus 4.6 (`low`/`medium`/`high`) | +| `CLAUDE_CODE_EFFORT_LEVEL` | Set effort level (`low`/`medium`/`high`/`max`) | +| `CLAUDE_CODE_SIMPLE` | Minimal mode, set by `--bare` flag | | `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Disable automatic CLAUDE.md updates | | `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background task execution | +| `CLAUDE_CODE_DISABLE_CRON` | Disable scheduled/cron tasks | +| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Disable git-related instructions | +| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Disable terminal title updates | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Disable 1M token context window | +| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Disable non-streaming fallback | | `CLAUDE_CODE_ENABLE_TASKS` | Enable task list feature | | `CLAUDE_CODE_TASK_LIST_ID` | Named task directory shared across sessions | | `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Toggle prompt suggestions (`true`/`false`) | | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Enable experimental agent teams | +| `CLAUDE_CODE_NEW_INIT` | Use new initialization flow | +| `CLAUDE_CODE_SUBAGENT_MODEL` | Model for subagent execution | +| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Directory for plugin seed files | +| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Env vars to scrub from subprocesses | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Override auto-compaction percentage | +| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Stream idle timeout in milliseconds | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Character budget for slash command tools | | `ENABLE_TOOL_SEARCH` | Enable tool search capability | | `MAX_MCP_OUTPUT_TOKENS` | Maximum tokens for MCP tool output | @@ -715,9 +758,12 @@ claude -p --output-format json "query" | Quick code review | `cat file | claude -p "review"` | | Structured output | `claude -p --output-format json "query"` | | Safe exploration | `claude --permission-mode plan` | +| Autonomous with safety | `claude --enable-auto-mode --permission-mode auto` | | CI/CD integration | `claude -p --max-turns 3 --output-format json` | | Resume work | `claude -r "session-name"` | | Custom model | `claude --model opus "complex task"` | +| Minimal mode | `claude --bare "quick query"` | +| Budget-capped run | `claude -p --max-budget-usd 2.00 "analyze code"` | --- diff --git a/CATALOG.md b/CATALOG.md index 97b46fd..f1410b5 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -7,7 +7,7 @@ > Quick reference guide to all Claude Code features: commands, agents, skills, plugins, and hooks. -**Navigation**: [Commands](#slash-commands) | [Subagents](#subagents) | [Skills](#skills) | [Plugins](#plugins) | [MCP Servers](#mcp-servers) | [Hooks](#hooks) | [Memory](#memory-files) | [New Features](#new-features-march-2026) +**Navigation**: [Commands](#slash-commands) | [Permission Modes](#permission-modes) | [Subagents](#subagents) | [Skills](#skills) | [Plugins](#plugins) | [MCP Servers](#mcp-servers) | [Hooks](#hooks) | [Memory](#memory-files) | [New Features](#new-features-march-2026) --- @@ -15,14 +15,14 @@ | Feature | Built-in | Examples | Total | Reference | |---------|----------|----------|-------|-----------| -| **Slash Commands** | 55 | 8 | 63 | [01-slash-commands/](01-slash-commands/) | +| **Slash Commands** | 55+ | 8 | 63+ | [01-slash-commands/](01-slash-commands/) | | **Subagents** | 6 | 10 | 16 | [04-subagents/](04-subagents/) | | **Skills** | 5 bundled | 4 | 9 | [03-skills/](03-skills/) | | **Plugins** | - | 3 | 3 | [07-plugins/](07-plugins/) | | **MCP Servers** | 1 | 8 | 9 | [05-mcp/](05-mcp/) | -| **Hooks** | 18 events | 7 | 7 | [06-hooks/](06-hooks/) | +| **Hooks** | 25 events | 7 | 7 | [06-hooks/](06-hooks/) | | **Memory** | 7 types | 3 | 3 | [02-memory/](02-memory/) | -| **Total** | **92** | **43** | **110** | | +| **Total** | **99** | **43** | **117** | | --- @@ -111,6 +111,25 @@ cp 01-slash-commands/*.md .claude/commands/ --- +## Permission Modes + +Claude Code supports 6 permission modes that control how tool use is authorized. + +| Mode | Description | When to Use | +|------|-------------|-------------| +| `default` | Prompt for each tool call | Standard interactive use | +| `acceptEdits` | Auto-accept file edits, prompt for others | Trusted editing workflows | +| `plan` | Read-only tools only, no writes | Planning and exploration | +| `auto` | Accept all tools without prompting | Fully autonomous operation (Research Preview) | +| `bypassPermissions` | Skip all permission checks | CI/CD, headless environments | +| `dontAsk` | Skip tools that would require permission | Non-interactive scripting | + +> **Note**: `auto` mode is a Research Preview feature (March 2026). Use `bypassPermissions` only in trusted, sandboxed environments. + +**Reference**: [Official Docs](https://code.claude.com/docs/en/permissions) + +--- + ## Subagents Specialized AI assistants with isolated contexts for specific tasks. @@ -126,6 +145,18 @@ Specialized AI assistants with isolated contexts for specific tasks. | **statusline-setup** | Status line configuration | Bash, Read, Write | Sonnet 4.6 | Configure status line display | | **Claude Code Guide** | Help and documentation | Read, Glob, Grep | Haiku 4.5 | Getting help, learning features | +### Subagent Configuration Fields + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Agent identifier | +| `description` | string | What the agent does | +| `model` | string | Model override (e.g., `haiku-4.5`) | +| `tools` | array | Allowed tools list | +| `effort` | string | Reasoning effort level (`low`, `medium`, `high`) | +| `initialPrompt` | string | System prompt injected at agent start | +| `disallowedTools` | array | Tools explicitly denied to this agent | + ### Custom Subagents (Examples) | Agent | Description | When to Use | Scope | Installation | @@ -176,6 +207,18 @@ Auto-invoked capabilities with instructions, scripts, and templates. └── templates/ # Output templates ``` +### Skill Frontmatter Fields + +Skills support YAML frontmatter in `SKILL.md` for configuration: + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Skill display name | +| `description` | string | What the skill does | +| `autoInvoke` | array | Trigger phrases for auto-invocation | +| `effort` | string | Reasoning effort level (`low`, `medium`, `high`) | +| `shell` | string | Shell to use for scripts (`bash`, `zsh`, `sh`) | + **Reference**: [03-skills/](03-skills/) | [Official Docs](https://code.claude.com/docs/en/skills) **Quick Install (All Skills)**: @@ -287,24 +330,31 @@ Event-driven automation that executes shell commands on Claude Code events. | Event | Description | When Triggered | Use Cases | |-------|-------------|----------------|-----------| -| `PreToolUse` | Before tool execution | Before any tool runs | Validation, logging | -| `PostToolUse` | After tool completion | After any tool completes | Formatting, notifications | -| `PermissionRequest` | Permission dialog shown | Before sensitive actions | Custom approval flows | -| `Notification` | Notification sent | Claude sends notification | External alerts | +| `SessionStart` | Session begins/resumes | Session initialization | Setup tasks | +| `InstructionsLoaded` | Instructions loaded | CLAUDE.md or rules file loaded | Custom instruction handling | | `UserPromptSubmit` | Before prompt processing | User sends message | Input validation | -| `Stop` | Agent finishes responding | Response complete | Cleanup, reporting | -| `SubagentStart` | Subagent begins | Subagent task starts | Initialize subagent context | +| `PreToolUse` | Before tool execution | Before any tool runs | Validation, logging | +| `PermissionRequest` | Permission dialog shown | Before sensitive actions | Custom approval flows | +| `PostToolUse` | After tool succeeds | After any tool completes | Formatting, notifications | +| `PostToolUseFailure` | Tool execution fails | After tool error | Error handling, logging | +| `Notification` | Notification sent | Claude sends notification | External alerts | +| `SubagentStart` | Subagent spawned | Subagent task starts | Initialize subagent context | | `SubagentStop` | Subagent finishes | Subagent task complete | Chain actions | -| `PreCompact` | Before compact operation | Context compression | State preservation | -| `SessionStart` | Session begins | Session initialization | Setup tasks | -| `SessionEnd` | Session ends | Session termination | Cleanup, save state | -| `WorktreeCreate` | Worktree created | Git worktree created | Setup worktree environment | -| `WorktreeRemove` | Worktree removed | Git worktree removed | Cleanup worktree resources | -| `ConfigChange` | Configuration updated | Settings modified | React to config changes | -| `InstructionsLoaded` | Instructions loaded | Memory files processed | Custom instruction handling | -| `Setup` | Agent setup | Agent initialization | Environment configuration | +| `Stop` | Claude finishes responding | Response complete | Cleanup, reporting | +| `StopFailure` | API error ends turn | API error occurs | Error recovery, logging | | `TeammateIdle` | Teammate agent idle | Agent team coordination | Distribute work | -| `TaskCompleted` | Task finished | Background task done | Post-task processing | +| `TaskCompleted` | Task marked complete | Task done | Post-task processing | +| `TaskCreated` | Task created via TaskCreate | New task created | Task tracking, logging | +| `ConfigChange` | Configuration updated | Settings modified | React to config changes | +| `CwdChanged` | Working directory changes | Directory changed | Directory-specific setup | +| `FileChanged` | Watched file changes | File modified | File monitoring, rebuild | +| `PreCompact` | Before compact operation | Context compression | State preservation | +| `PostCompact` | After compaction completes | Compaction done | Post-compact actions | +| `WorktreeCreate` | Worktree being created | Git worktree created | Setup worktree environment | +| `WorktreeRemove` | Worktree being removed | Git worktree removed | Cleanup worktree resources | +| `Elicitation` | MCP server requests input | MCP elicitation | Input validation | +| `ElicitationResult` | User responds to elicitation | User responds | Response processing | +| `SessionEnd` | Session terminates | Session termination | Cleanup, save state | ### Example Hooks @@ -395,6 +445,15 @@ cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md | **Scheduled Tasks** | Set up recurring tasks with `/loop` and cron tools | Use `/loop 5m /command` or CronCreate tool | | **Chrome Integration** | Browser automation with headless Chromium | Use `--chrome` flag or `/chrome` command | | **Keyboard Customization** | Customize keybindings including chord support | Use `/keybindings` or edit `~/.claude/keybindings.json` | +| **Auto Mode** | Fully autonomous operation without permission prompts (Research Preview) | Use `--mode auto` or `/permissions auto`; March 2026 | +| **Channels** | Multi-channel communication (Telegram, Slack, etc.) (Research Preview) | Configure channel plugins; March 2026 | +| **Voice Dictation** | Voice input for prompts | Use microphone icon or voice keybinding | +| **Agent Hook Type** | Hooks that spawn a subagent instead of running a shell command | Set `"type": "agent"` in hook configuration | +| **Prompt Hook Type** | Hooks that inject prompt text into the conversation | Set `"type": "prompt"` in hook configuration | +| **MCP Elicitation** | MCP servers can request user input during tool execution | Handle via `Elicitation` and `ElicitationResult` hook events | +| **WebSocket MCP Transport** | WebSocket-based transport for MCP server connections | Use `"transport": "websocket"` in MCP server config | +| **Plugin LSP Support** | Language Server Protocol integration via plugins | Configure LSP servers in `plugin.json` for editor features | +| **Managed Drop-ins** | Organization-managed drop-in configurations (v2.1.83) | Admin-configured via managed policies; auto-applied to all users | --- diff --git a/INDEX.md b/INDEX.md index 4bdd537..704a75e 100644 --- a/INDEX.md +++ b/INDEX.md @@ -218,11 +218,11 @@ Event-driven automation scripts that execute automatically. **Usage**: Configured in settings, executed automatically -**Hook Types**: -- Tool Hooks: PreToolUse:*, PostToolUse:* -- Session Hooks: Stop, SubagentStop, SubagentStart -- Agent Hooks: InstructionsLoaded, Setup -- Lifecycle Hooks: Notification, ConfigChange, WorktreeCreate, WorktreeRemove +**Hook Types** (4 types, 25 events): +- Tool Hooks: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest +- Session Hooks: SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop +- Task Hooks: UserPromptSubmit, TaskCompleted, TaskCreated, TeammateIdle +- Lifecycle Hooks: ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResult --- @@ -395,6 +395,7 @@ Advanced capabilities for complex workflows. - **default**: Ask for approval on risky actions - **acceptEdits**: Auto-accept file edits, ask for others - **plan**: Read-only analysis, no modifications +- **auto**: Automatically approve safe actions, prompt for risky ones - **dontAsk**: Accept all actions except risky ones - **bypassPermissions**: Accept all (requires `--dangerously-skip-permissions`) @@ -741,6 +742,7 @@ chmod +x ~/.claude/hooks/*.sh # Use permission modes claude --permission-mode plan # For code review (read-only) claude --permission-mode acceptEdits # Auto-accept edits +claude --permission-mode auto # Auto-approve safe actions # Run in headless mode for CI/CD claude -p "Run tests and report results" diff --git a/LEARNING-ROADMAP.md b/LEARNING-ROADMAP.md index 1e9eea8..dfc27c3 100644 --- a/LEARNING-ROADMAP.md +++ b/LEARNING-ROADMAP.md @@ -97,15 +97,15 @@ graph TD | Step | Feature | Complexity | Time | Level | Dependencies | Why Learn This | Key Benefits | |------|---------|-----------|------|-------|--------------|----------------|--------------| -| **1** | [Slash Commands](01-slash-commands/) | ⭐ Beginner | 30 min | Level 1 | None | Quick productivity wins | Instant automation, team standards | +| **1** | [Slash Commands](01-slash-commands/) | ⭐ Beginner | 30 min | Level 1 | None | Quick productivity wins (55+ built-in + 5 bundled skills) | Instant automation, team standards | | **2** | [Memory](02-memory/) | ⭐⭐ Beginner+ | 45 min | Level 1 | None | Essential for all features | Persistent context, preferences | | **3** | [Checkpoints](08-checkpoints/) | ⭐⭐ Intermediate | 45 min | Level 1 | Session management | Safe exploration | Experimentation, recovery | | **4** | [CLI Basics](10-cli/) | ⭐⭐ Beginner+ | 30 min | Level 1 | None | Core CLI usage | Interactive & print mode | | **5** | [Skills](03-skills/) | ⭐⭐ Intermediate | 1 hour | Level 2 | Slash Commands | Automatic expertise | Reusable capabilities, consistency | -| **6** | [Hooks](06-hooks/) | ⭐⭐ Intermediate | 1 hour | Level 2 | Tools, Commands | Workflow automation | Validation, quality gates | +| **6** | [Hooks](06-hooks/) | ⭐⭐ Intermediate | 1 hour | Level 2 | Tools, Commands | Workflow automation (25 events, 4 types) | Validation, quality gates | | **7** | [MCP](05-mcp/) | ⭐⭐⭐ Intermediate+ | 1 hour | Level 2 | Configuration | Live data access | Real-time integration, APIs | -| **8** | [Subagents](04-subagents/) | ⭐⭐⭐ Intermediate+ | 1.5 hours | Level 2 | Memory, Commands | Complex task handling | Delegation, specialized expertise | -| **9** | [Advanced Features](09-advanced-features/) | ⭐⭐⭐⭐⭐ Advanced | 2-3 hours | Level 3 | All previous | Power user tools | Planning, headless, permissions | +| **8** | [Subagents](04-subagents/) | ⭐⭐⭐ Intermediate+ | 1.5 hours | Level 2 | Memory, Commands | Complex task handling (6 built-in including Bash) | Delegation, specialized expertise | +| **9** | [Advanced Features](09-advanced-features/) | ⭐⭐⭐⭐⭐ Advanced | 2-3 hours | Level 3 | All previous | Power user tools | Planning, Auto Mode, Channels, Voice Dictation, permissions | | **10** | [Plugins](07-plugins/) | ⭐⭐⭐⭐ Advanced | 2 hours | Level 3 | All previous | Complete solutions | Team onboarding, distribution | | **11** | [CLI Mastery](10-cli/) | ⭐⭐⭐ Advanced | 1 hour | Level 3 | Recommended: All | Master command-line usage | Scripting, CI/CD, automation | @@ -234,8 +234,9 @@ Before starting Level 2, make sure you're comfortable with these Level 1 concept **Goal**: Automate common workflows and quality checks #### What You'll Achieve -✅ Auto-invoke specialized capabilities -✅ Set up event-driven automation +✅ Auto-invoke specialized capabilities with YAML frontmatter (including `effort` and `shell` fields) +✅ Set up event-driven automation across 25 hook events +✅ Use all 4 hook types (command, http, prompt, agent) ✅ Enforce code quality standards ✅ Create custom hooks for your workflow @@ -357,17 +358,20 @@ Before starting Level 3, make sure you're comfortable with these Level 2 concept ### Milestone 3A: Advanced Features -**Topics**: Advanced Features (Planning, Permissions, Extended Thinking, Remote/Desktop/Web) +**Topics**: Advanced Features (Planning, Permissions, Extended Thinking, Auto Mode, Channels, Voice Dictation, Remote/Desktop/Web) **Time**: 2-3 hours **Complexity**: ⭐⭐⭐⭐⭐ Advanced **Goal**: Master advanced workflows and power user tools #### What You'll Achieve ✅ Planning mode for complex features -✅ Fine-grained permission control (default, acceptEdits, plan, dontAsk, bypassPermissions) +✅ Fine-grained permission control with 6 modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) ✅ Extended thinking via Alt+T / Option+T toggle ✅ Background task management ✅ Auto Memory for learned preferences +✅ Auto Mode with background safety classifier +✅ Channels for structured multi-session workflows +✅ Voice Dictation for hands-free interaction ✅ Remote control, desktop app, and web sessions ✅ Agent Teams for multi-agent collaboration @@ -377,9 +381,10 @@ Before starting Level 3, make sure you're comfortable with these Level 2 concept # Exercise 1: Use planning mode /plan Implement user authentication system -# Exercise 2: Try permission modes +# Exercise 2: Try permission modes (6 available: default, acceptEdits, plan, auto, dontAsk, bypassPermissions) claude --permission-mode plan "analyze this codebase" claude --permission-mode acceptEdits "refactor the auth module" +claude --permission-mode auto "implement the feature" # Exercise 3: Enable extended thinking # Press Alt+T (Option+T on macOS) during a session to toggle @@ -392,20 +397,32 @@ claude --permission-mode acceptEdits "refactor the auth module" # 5. If tests fail, rewind to checkpoint # 6. Try alternative approach -# Exercise 5: Enable agent teams +# Exercise 5: Try auto mode (background safety classifier) +claude --permission-mode auto "implement user settings page" + +# Exercise 6: Enable agent teams export CLAUDE_AGENT_TEAMS=1 # Ask Claude: "Implement feature X using a team approach" -# Exercise 6: Scheduled tasks +# Exercise 7: Scheduled tasks /loop 5m /check-status # Or use CronCreate for persistent scheduled tasks + +# Exercise 8: Channels for multi-session workflows +# Use channels to organize work across sessions + +# Exercise 9: Voice Dictation +# Use voice input for hands-free interaction with Claude Code ``` #### Success Criteria - [ ] Used planning mode for a complex feature -- [ ] Configured permission modes (plan, acceptEdits, dontAsk) +- [ ] Configured permission modes (plan, acceptEdits, auto, dontAsk) - [ ] Toggled extended thinking with Alt+T / Option+T +- [ ] Used auto mode with background safety classifier - [ ] Used background tasks for long operations +- [ ] Explored Channels for multi-session workflows +- [ ] Tried Voice Dictation for hands-free input - [ ] Understand Remote Control, Desktop App, and Web sessions - [ ] Enabled and used Agent Teams for collaborative tasks - [ ] Used `/loop` for recurring tasks or scheduled monitoring @@ -638,8 +655,10 @@ Use these checklists to track your progress by level. Run `/self-assessment` any ### 🔴 Level 3: Advanced - [ ] Completed [09-advanced-features](09-advanced-features/) - [ ] Used planning mode successfully -- [ ] Configured permission modes +- [ ] Configured permission modes (6 modes including auto) +- [ ] Used auto mode with safety classifier - [ ] Used extended thinking toggle +- [ ] Explored Channels and Voice Dictation - [ ] **Milestone 3A achieved** - [ ] Completed [07-plugins](07-plugins/) - [ ] Completed [10-cli](10-cli/) advanced usage @@ -682,13 +701,16 @@ Once you've completed all milestones: 3. **Explore Remote Control** - Control Claude Code sessions programmatically from external tools 4. **Try Web Sessions** - Use Claude Code through browser-based interfaces for remote development 5. **Use the Desktop App** - Access Claude Code features through the native desktop application -6. **Leverage Auto Memory** - Let Claude learn your preferences automatically over time -7. **Set up Agent Teams** - Coordinate multiple agents on complex, multi-faceted tasks -8. **Use Scheduled Tasks** - Automate recurring checks with `/loop` and cron tools -9. **Contribute examples** - Share with the community -10. **Mentor others** - Help teammates learn -11. **Optimize workflows** - Continuously improve based on usage -12. **Stay updated** - Follow Claude Code releases and new features +6. **Use Auto Mode** - Let Claude work autonomously with a background safety classifier +7. **Leverage Auto Memory** - Let Claude learn your preferences automatically over time +8. **Set up Agent Teams** - Coordinate multiple agents on complex, multi-faceted tasks +9. **Use Channels** - Organize work across structured multi-session workflows +10. **Try Voice Dictation** - Use hands-free voice input for interaction with Claude Code +11. **Use Scheduled Tasks** - Automate recurring checks with `/loop` and cron tools +12. **Contribute examples** - Share with the community +13. **Mentor others** - Help teammates learn +14. **Optimize workflows** - Continuously improve based on usage +15. **Stay updated** - Follow Claude Code releases and new features --- diff --git a/QUICK_REFERENCE.md b/QUICK_REFERENCE.md index caada64..f81759b 100644 --- a/QUICK_REFERENCE.md +++ b/QUICK_REFERENCE.md @@ -96,6 +96,7 @@ chmod +x ~/.claude/hooks/*.sh # acceptEdits - Auto-accept file edits, ask for others # plan - Read-only analysis, no modifications # dontAsk - Accept all actions except risky ones +# auto - Background classifier decides permissions automatically # bypassPermissions - Accept all actions (requires --dangerously-skip-permissions) # Session management @@ -112,16 +113,16 @@ claude -r "session" # Resume session by name/ID | Feature | Install Path | Usage | |---------|-------------|-------| -| **Slash Commands** | `.claude/commands/*.md` | `/command-name` | +| **Slash Commands (55+)** | `.claude/commands/*.md` | `/command-name` | | **Memory** | `./CLAUDE.md` | Auto-loaded | | **Skills** | `.claude/skills/*/SKILL.md` | Auto-invoked | | **Subagents** | `.claude/agents/*.md` | Auto-delegated | | **MCP** | `.mcp.json` (project) or `~/.claude.json` (user) | `/mcp__server__action` | -| **Hooks** | `~/.claude/hooks/*.sh` | Event-triggered | +| **Hooks (25 events)** | `~/.claude/hooks/*.sh` | Event-triggered (4 types) | | **Plugins** | Via `/plugin install` | Bundles all | | **Checkpoints** | Built-in | `Esc+Esc` or `/rewind` | | **Planning Mode** | Built-in | `/plan ` | -| **Permission Modes** | Built-in | `--allowedTools`, `--permission-mode` | +| **Permission Modes (6)** | Built-in | `--allowedTools`, `--permission-mode` | | **Sessions** | Built-in | `/session ` | | **Background Tasks** | Built-in | Run in background | | **Remote Control** | Built-in | WebSocket API | @@ -129,7 +130,7 @@ claude -r "session" # Resume session by name/ID | **Git Worktrees** | Built-in | `/worktree` | | **Auto Memory** | Built-in | Auto-saves to CLAUDE.md | | **Task List** | Built-in | `/task list` | -| **Bundled Skills** | Built-in | `/simplify`, `/loop`, `/claude-api` | +| **Bundled Skills (5)** | Built-in | `/simplify`, `/loop`, `/claude-api`, `/voice`, `/browse` | --- @@ -188,7 +189,7 @@ vim CLAUDE.md ### Automation & Hooks ```bash -# Install hooks +# Install hooks (25 events, 4 types: command, http, prompt, agent) mkdir -p ~/.claude/hooks cp 06-hooks/*.sh ~/.claude/hooks/ chmod +x ~/.claude/hooks/*.sh @@ -197,6 +198,10 @@ chmod +x ~/.claude/hooks/*.sh # - Pre-commit tests: pre-commit.sh # - Auto-format code: format-code.sh # - Security scanning: security-scan.sh + +# Auto Mode for fully autonomous workflows +claude --enable-auto-mode -p "Refactor and test the auth module" +# Or cycle modes interactively with Shift+Tab ``` ### Safe Refactoring @@ -225,6 +230,9 @@ claude -p "Run all tests and generate report" # With permission mode for CI claude -p "Run tests" --permission-mode dontAsk +# With Auto Mode for fully autonomous CI tasks +claude --enable-auto-mode -p "Run tests and fix failures" + # With hooks for automation # See 09-advanced-features/README.md ``` @@ -265,25 +273,26 @@ export CLAUDE_AGENT_TEAMS=1 ``` Your Project/ ├── .claude/ -│ ├── commands/ # Slash commands go here -│ ├── agents/ # Subagents go here -│ ├── skills/ # Project skills go here -│ └── settings.json # Project settings (hooks, etc.) -├── .mcp.json # MCP configuration (project scope) -├── CLAUDE.md # Project memory +│ ├── commands/ # Slash commands go here +│ ├── agents/ # Subagents go here +│ ├── skills/ # Project skills go here +│ └── settings.json # Project settings (hooks, etc.) +├── .mcp.json # MCP configuration (project scope) +├── CLAUDE.md # Project memory └── src/ └── api/ - └── CLAUDE.md # Directory-specific memory + └── CLAUDE.md # Directory-specific memory User Home/ ├── .claude/ -│ ├── commands/ # Personal commands -│ ├── agents/ # Personal agents -│ ├── skills/ # Personal skills -│ ├── hooks/ # Hook scripts -│ ├── settings.json # User settings -│ └── CLAUDE.md # Personal memory -└── .claude.json # Personal MCP config (user scope) +│ ├── commands/ # Personal commands +│ ├── agents/ # Personal agents +│ ├── skills/ # Personal skills +│ ├── hooks/ # Hook scripts +│ ├── settings.json # User settings +│ ├── managed-settings.d/ # Managed settings (enterprise/org) +│ └── CLAUDE.md # Personal memory +└── .claude.json # Personal MCP config (user scope) ``` --- @@ -377,6 +386,13 @@ cp -r 03-skills/code-review ~/.claude/skills/ | Feature | Description | Usage | |---------|-------------|-------| +| **Auto Mode** | Fully autonomous operation with background classifier | `--enable-auto-mode` flag, `Shift+Tab` to cycle modes | +| **Channels** | Discord and Telegram integration | `--channels` flag, Discord/Telegram bots | +| **Voice Dictation** | Speak commands and context to Claude | `/voice` command | +| **Hooks (25 events)** | Expanded hook system with 4 types | command, http, prompt, agent hook types | +| **MCP Elicitation** | MCP servers can request user input at runtime | Auto-prompted when server needs clarification | +| **WebSocket MCP** | WebSocket transport for MCP connections | Configure in `.mcp.json` with `ws://` URLs | +| **Plugin LSP** | Language Server Protocol support for plugins | `userConfig`, `${CLAUDE_PLUGIN_DATA}` variable | | **Remote Control** | Control Claude Code via WebSocket API | `claude --remote` for external integrations | | **Web Sessions** | Browser-based Claude Code interface | `claude web` to launch | | **Desktop App** | Native desktop application | Download from claude.ai/download | @@ -424,14 +440,16 @@ echo $GITHUB_TOKEN | Need | Use This | Example | |------|----------|---------| -| Quick shortcut | Slash Command | `01-slash-commands/optimize.md` | +| Quick shortcut | Slash Command (55+) | `01-slash-commands/optimize.md` | | Team standards | Memory | `02-memory/project-CLAUDE.md` | | Auto workflow | Skill | `03-skills/code-review/` | | Specialized task | Subagent | `04-subagents/code-reviewer.md` | -| External data | MCP | `05-mcp/github-mcp.json` | -| Event automation | Hook | `06-hooks/pre-commit.sh` | -| Complete solution | Plugin | `07-plugins/pr-review/` | +| External data | MCP (+ Elicitation, WebSocket) | `05-mcp/github-mcp.json` | +| Event automation | Hook (25 events, 4 types) | `06-hooks/pre-commit.sh` | +| Complete solution | Plugin (+ LSP support) | `07-plugins/pr-review/` | | Safe experiment | Checkpoint | `08-checkpoints/checkpoint-examples.md` | +| Fully autonomous | Auto Mode | `--enable-auto-mode` or `Shift+Tab` | +| Chat integrations | Channels | `--channels` (Discord, Telegram) | | CI/CD pipeline | CLI | `10-cli/README.md` | --- diff --git a/README.md b/README.md index d5383a6..e150447 100644 --- a/README.md +++ b/README.md @@ -458,10 +458,11 @@ Configure hooks in `~/.claude/settings.json`: **Usage**: Hooks execute automatically on events -**Hook Types**: -- **Tool Hooks**: `PreToolUse:*`, `PostToolUse:*` -- **Session Hooks**: `Stop`, `SubagentStop`, `SubagentStart` -- **Lifecycle Hooks**: `Notification`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove` +**Hook Types** (4 types, 25 events): +- **Tool Hooks**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` +- **Session Hooks**: `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop` +- **Task Hooks**: `UserPromptSubmit`, `TaskCompleted`, `TaskCreated`, `TeammateIdle` +- **Lifecycle Hooks**: `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact`, `WorktreeCreate`, `WorktreeRemove`, `Notification`, `InstructionsLoaded`, `Elicitation`, `ElicitationResult` diff --git a/claude_concepts_guide.md b/claude_concepts_guide.md index 6f37f71..65eb161 100644 --- a/claude_concepts_guide.md +++ b/claude_concepts_guide.md @@ -1349,6 +1349,8 @@ tags: - quality - security when_to_use: When users ask to review code, analyze code quality, or evaluate pull requests +effort: high +shell: bash --- # Code Review Skill @@ -2807,19 +2809,35 @@ Hooks are event-driven shell commands that execute automatically in response to ### Hook Events +Claude Code supports **25 hook events** across four hook types (command, http, prompt, agent): + | Hook Event | Trigger | Use Cases | |------------|---------|-----------| +| **SessionStart** | Session begins/resumes/clear/compact | Environment setup, initialization | +| **InstructionsLoaded** | CLAUDE.md or rules file loaded | Validation, transformation, augmentation | +| **UserPromptSubmit** | User submits prompt | Input validation, prompt filtering | | **PreToolUse** | Before any tool runs | Validation, approval gates, logging | -| **PostToolUse** | After any tool runs | Auto-formatting, notifications, cleanup | -| **Stop** | When the main agent stops | Summary generation, cleanup tasks | -| **SubagentStop** | When a subagent stops | Result validation, logging | -| **SubagentStart** | When a subagent starts | Context injection, initialization | -| **Notification** | On notification events | Alerting, external integrations | -| **WorktreeCreate** | When a worktree is created | Environment setup, dependency install | -| **WorktreeRemove** | When a worktree is removed | Cleanup, resource deallocation | -| **ConfigChange** | When configuration changes | Validation, propagation | -| **InstructionsLoaded** | When memory/instruction files are loaded | Validation, transformation, augmentation | -| **Setup** | During agent initialization | Environment preparation, dependency checks | +| **PermissionRequest** | Permission dialog shown | Auto-approve/deny flows | +| **PostToolUse** | After tool succeeds | Auto-formatting, notifications, cleanup | +| **PostToolUseFailure** | Tool execution fails | Error handling, logging | +| **Notification** | Notification sent | Alerting, external integrations | +| **SubagentStart** | Subagent spawned | Context injection, initialization | +| **SubagentStop** | Subagent finishes | Result validation, logging | +| **Stop** | Claude finishes responding | Summary generation, cleanup tasks | +| **StopFailure** | API error ends turn | Error recovery, logging | +| **TeammateIdle** | Agent team teammate idle | Work distribution, coordination | +| **TaskCompleted** | Task marked complete | Post-task processing | +| **TaskCreated** | Task created via TaskCreate | Task tracking, logging | +| **ConfigChange** | Config file changes | Validation, propagation | +| **CwdChanged** | Working directory changes | Directory-specific setup | +| **FileChanged** | Watched file changes | File monitoring, rebuild triggers | +| **PreCompact** | Before context compaction | State preservation | +| **PostCompact** | After compaction completes | Post-compact actions | +| **WorktreeCreate** | Worktree being created | Environment setup, dependency install | +| **WorktreeRemove** | Worktree being removed | Cleanup, resource deallocation | +| **Elicitation** | MCP server requests user input | Input validation | +| **ElicitationResult** | User responds to elicitation | Response processing | +| **SessionEnd** | Session terminates | Cleanup, final logging | ### Common Hooks @@ -2994,6 +3012,7 @@ Control what Claude can do. | **default** | Standard permissions with prompts for sensitive actions | General development | | **acceptEdits** | Automatically accept file edits without confirmation | Trusted editing workflows | | **plan** | Analysis and planning only, no file modifications | Code review, architecture planning | +| **auto** | Automatically approve safe actions, prompt only for risky ones | Balanced autonomy with safety | | **dontAsk** | Execute all actions without confirmation prompts | Experienced users, automation | | **bypassPermissions** | Full unrestricted access, no safety checks | CI/CD pipelines, trusted scripts | @@ -3001,6 +3020,7 @@ Control what Claude can do. ```bash claude --permission-mode plan # Read-only analysis claude --permission-mode acceptEdits # Auto-accept edits +claude --permission-mode auto # Auto-approve safe actions claude --permission-mode dontAsk # No confirmation prompts ``` @@ -3109,4 +3129,4 @@ Complete configuration example: *Last updated: March 2026* *For Claude Haiku 4.5, Sonnet 4.6, and Opus 4.6* -*Now includes: Hooks, Checkpoints, Planning Mode, Extended Thinking, Background Tasks, Permission Modes, Headless Mode, Session Management, Auto Memory, Agent Teams, Scheduled Tasks, Chrome Integration, and Bundled Skills* +*Now includes: Hooks, Checkpoints, Planning Mode, Extended Thinking, Background Tasks, Permission Modes (6 modes), Headless Mode, Session Management, Auto Memory, Agent Teams, Scheduled Tasks, Chrome Integration, Channels, Voice Dictation, and Bundled Skills* diff --git a/resources.md b/resources.md index 8f81e6e..d27d4fc 100644 --- a/resources.md +++ b/resources.md @@ -21,6 +21,9 @@ | Keybindings | Keyboard shortcut customization | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | | Desktop App | Native desktop application | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | | Remote Control | Remote session control | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | +| Auto Mode | Automatic permission management | [code.claude.com/docs/en/auto-mode](https://code.claude.com/docs/en/auto-mode) | +| Channels | Multi-channel communication | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | +| Voice Dictation | Voice input for Claude Code | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | ## Anthropic Engineering Blog @@ -236,9 +239,9 @@ These steps capture the core recommendations for smooth workflows with Claude Co | **Web Sessions** | Access Claude Code through browser-based interfaces for remote development | [CLI Reference](10-cli/) | | **Desktop App** | Native desktop application for Claude Code with enhanced UI | [Claude Code Docs](https://code.claude.com/docs/en/desktop) | | **Extended Thinking** | Deep reasoning toggle via `Alt+T`/`Option+T` or `MAX_THINKING_TOKENS` env var | [Advanced Features](09-advanced-features/) | -| **Permission Modes** | Fine-grained control: default, acceptEdits, plan, dontAsk, bypassPermissions | [Advanced Features](09-advanced-features/) | +| **Permission Modes** | Fine-grained control: default, acceptEdits, plan, auto, dontAsk, bypassPermissions | [Advanced Features](09-advanced-features/) | | **7-Tier Memory** | Managed Policy, Project, Project Rules, User, User Rules, Local, Auto Memory | [Memory Guide](02-memory/) | -| **Hook Events** | PreToolUse, PostToolUse, Stop, SubagentStop, SubagentStart, Notification, and more | [Hooks Guide](06-hooks/) | +| **Hook Events** | 25 events: PreToolUse, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStart, SubagentStop, Notification, Elicitation, and more | [Hooks Guide](06-hooks/) | | **Agent Teams** | Coordinate multiple agents working together on complex tasks | [Subagents Guide](04-subagents/) | | **Scheduled Tasks** | Set up recurring tasks with `/loop` and cron tools | [Advanced Features](09-advanced-features/) | | **Chrome Integration** | Browser automation with headless Chromium | [Advanced Features](09-advanced-features/) |