[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CASQK67ATWX3J2PPNFHTC2":3,"skill-same:01M6CASQK67ATWX3J2PPNFHTC2":103},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":64,"commitSha":65,"skillDirectory":66,"forksCount":67,"repositoryHtmlUrl":68,"repositoryHomepageUrl":6,"ownerHtmlUrl":69,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":70,"install":71,"resources":84},"01M6CASQK67ATWX3J2PPNFHTC2","claude-code",null,"Delegate coding to Claude Code CLI (features, PRs).","adnichols\u002Fai-configs","adnichols","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F493746?v=4","01M6C33VRY9WF6XWYPT1AFA7JJ","Aaron Nichols","01M6C33VWTNKGRM92E9G643V4W",5,"MIT","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fautonomous-ai-agents\u002Fclaude-code\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"code","code-review","PTY","Coding-Agent","opencode","delegate","hermes agent","hermes","coding","refactoring","macos","windows","automation","codex","linux","cli","review","2026-11-10 10:12:30",false,"---\nname: claude-code\ndescription: \"Delegate coding to Claude Code CLI (features, PRs).\"\nversion: 2.2.1\nauthor: Hermes Agent + Teknium\nlicense: MIT\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    tags: [Coding-Agent, Claude, Anthropic, Code-Review, Refactoring, PTY, Automation]\n    related_skills: [codex, hermes-agent, opencode]\n---\n\n# Claude Code — Hermes Orchestration Guide\n\nDelegate coding tasks to [Claude Code](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcli-reference) (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.\n\n## Prerequisites\n\n- **Install:** `npm install -g @anthropic-ai\u002Fclaude-code`\n- **Auth:** run `claude` once to log in (browser OAuth for Pro\u002FMax, or set `ANTHROPIC_API_KEY`)\n- **Console auth:** `claude auth login --console` for API key billing\n- **SSO auth:** `claude auth login --sso` for Enterprise\n- **Check status:** `claude auth status` (JSON) or `claude auth status --text` (human-readable)\n- **Health check:** `claude doctor` — checks auto-updater and installation health\n- **Version check:** `claude --version` (requires v2.x+)\n- **Update:** `claude update` or `claude upgrade`\n\n## Two Orchestration Modes\n\nHermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.\n\n### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)\n\nPrint mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.\n\n```\nterminal(command=\"claude -p 'Add error handling to all API calls in src\u002F' --allowedTools 'Read,Edit' --max-turns 10\", workdir=\"\u002Fpath\u002Fto\u002Fproject\", timeout=120)\n```\n\n**When to use print mode:**\n- One-shot coding tasks (fix a bug, add a feature, refactor)\n- CI\u002FCD automation and scripting\n- Structured data extraction with `--json-schema`\n- Piped input processing (`cat file | claude -p \"analyze this\"`)\n- Any task where you don't need multi-turn conversation\n\n**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.\n\n### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions\n\nInteractive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. **Requires tmux orchestration.**\n\n```\n# Start a tmux session\nterminal(command=\"tmux new-session -d -s claude-work -x 140 -y 40\")\n\n# Launch Claude Code inside it\nterminal(command=\"tmux send-keys -t claude-work 'cd \u002Fpath\u002Fto\u002Fproject && claude' Enter\")\n\n# Wait for startup, then send your task\n# (after ~3-5 seconds for the welcome screen)\nterminal(command=\"sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter\")\n\n# Monitor progress by capturing the pane\nterminal(command=\"sleep 15 && tmux capture-pane -t claude-work -p -S -50\")\n\n# Send follow-up tasks\nterminal(command=\"tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter\")\n\n# Exit when done\nterminal(command=\"tmux send-keys -t claude-work '\u002Fexit' Enter\")\n```\n\n**When to use interactive mode:**\n- Multi-turn iterative work (refactor → review → fix → test cycle)\n- Tasks requiring human-in-the-loop decisions\n- Exploratory coding sessions\n- When you need to use Claude's slash commands (`\u002Fcompact`, `\u002Freview`, `\u002Fmodel`)\n\n## PTY Dialog Handling (CRITICAL for Interactive Mode)\n\nClaude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:\n\n### Dialog 1: Workspace Trust (first visit to a directory)\n```\n❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)\n  2. No, exit\n```\n**Handling:** `tmux send-keys -t \u003Csession> Enter` — default selection is correct.\n\n### Dialog 2: Individual Permission Prompts (normal flow)\n\nEach tool use that needs approval (file write, shell command, network) shows a prompt. Answer that one prompt — this is different from disabling prompts for the whole run:\n```\n# Read the prompt before answering it\nterminal(command=\"tmux capture-pane -t \u003Csession> -p -S -30\")\n# Allow this one action (Enter = default \"Yes\"); Esc declines it\nterminal(command=\"tmux send-keys -t \u003Csession> Enter\")\n```\nNever send a blind `Enter` on a timer to approve prompts you have not read — that is the bypass flag with extra steps.\n\nA narrower opt-in than the full bypass is `--permission-mode acceptEdits`: file edits in the working directory are accepted, shell and other tool calls still prompt. Use it only in a dedicated worktree after reviewing the task.\n\n### Robust Dialog Handling Pattern\n```\n# Default launch — keep permission prompts enabled\nterminal(command=\"tmux send-keys -t claude-work 'claude \\\"your task\\\"' Enter\")\n\n# Handle trust dialog (Enter for default \"Yes\")\nterminal(command=\"sleep 4 && tmux send-keys -t claude-work Enter\")\n\n# Now wait for Claude to work\nterminal(command=\"sleep 15 && tmux capture-pane -t claude-work -p -S -60\")\n```\n\n**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again.\n\n### Opt-in: --dangerously-skip-permissions (isolated environments only)\n\nThis disables permission prompts for the whole run — grants filesystem, shell, and network access with no prompts. Acceptable only in a throwaway worktree or isolated container.\n```\n❯ 1. No, exit                    ← DEFAULT (safe choice)\n  2. Yes, I accept\n```\nTo accept: `tmux send-keys -t \u003Csession> Down && sleep 0.3 && tmux send-keys -t \u003Csession> Enter`\n\n## CLI Subcommands\n\n| Subcommand | Purpose |\n|------------|---------|\n| `claude` | Start interactive REPL |\n| `claude \"query\"` | Start REPL with initial prompt |\n| `claude -p \"query\"` | Print mode (non-interactive, exits when done) |\n| `cat file \\| claude -p \"query\"` | Pipe content as stdin context |\n| `claude -c` | Continue the most recent conversation in this directory |\n| `claude -r \"id\"` | Resume a specific session by ID or name |\n| `claude auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |\n| `claude auth status` | Check login status (returns JSON; `--text` for human-readable) |\n| `claude mcp add \u003Cname> -- \u003Ccmd>` | Add an MCP server |\n| `claude mcp list` | List configured MCP servers |\n| `claude mcp remove \u003Cname>` | Remove an MCP server |\n| `claude agents` | List configured agents |\n| `claude doctor` | Run health checks on installation and auto-updater |\n| `claude update` \u002F `claude upgrade` | Update Claude Code to latest version |\n| `claude remote-control` | Start server to control Claude from claude.ai or mobile app |\n| `claude install [target]` | Install native build (stable, latest, or specific version) |\n| `claude setup-token` | Set up long-lived auth token (requires subscription) |\n| `claude plugin` \u002F `claude plugins` | Manage Claude Code plugins |\n| `claude auto-mode` | Inspect auto mode classifier configuration |\n\n## Print Mode Deep Dive\n\n### Structured JSON Output\n```\nterminal(command=\"claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5\", workdir=\"\u002Fproject\", timeout=120)\n```\n\nReturns a JSON object with:\n```json\n{\n  \"type\": \"result\",\n  \"subtype\": \"success\",\n  \"result\": \"The analysis text...\",\n  \"session_id\": \"75e2167f-...\",\n  \"num_turns\": 3,\n  \"total_cost_usd\": 0.0787,\n  \"duration_ms\": 10276,\n  \"stop_reason\": \"end_turn\",\n  \"terminal_reason\": \"completed\",\n  \"usage\": { \"input_tokens\": 5, \"output_tokens\": 603, ... },\n  \"modelUsage\": { \"claude-sonnet-4-6\": { \"costUSD\": 0.078, \"contextWindow\": 200000 } }\n}\n```\n\n**Key fields:** `session_id` for resumption, `num_turns` for agentic loop count, `total_cost_usd` for spend tracking, `subtype` for success\u002Ferror detection (`success`, `error_max_turns`, `error_budget`).\n\n### Streaming JSON Output\nFor real-time token streaming, use `stream-json` with `--verbose`:\n```\nterminal(command=\"claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages\", timeout=60)\n```\n\nReturns newline-delimited JSON events. Filter with jq for live text:\n```\nclaude -p \"Explain X\" --output-format stream-json --verbose --include-partial-messages | \\\n  jq -rj 'select(.type == \"stream_event\" and .event.delta.type? == \"text_delta\") | .event.delta.text'\n```\n\nStream events include `system\u002Fapi_retry` with `attempt`, `max_retries`, and `error` fields (e.g., `rate_limit`, `billing_error`).\n\n### Bidirectional Streaming\nFor real-time input AND output streaming:\n```\nclaude -p \"task\" --input-format stream-json --output-format stream-json --replay-user-messages\n```\n`--replay-user-messages` re-emits user messages on stdout for acknowledgment.\n\n### Piped Input\n```\n# Pipe a file for analysis\nterminal(command=\"cat src\u002Fauth.py | claude -p 'Review this code for bugs' --max-turns 1\", timeout=60)\n\n# Pipe multiple files\nterminal(command=\"cat src\u002F*.py | claude -p 'Find all TODO comments' --max-turns 1\", timeout=60)\n\n# Pipe command output\nterminal(command=\"git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1\", timeout=60)\n```\n\n### JSON Schema for Structured Extraction\n```\nterminal(command=\"claude -p 'List all functions in src\u002F' --output-format json --json-schema '{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"functions\\\":{\\\"type\\\":\\\"array\\\",\\\"items\\\":{\\\"type\\\":\\\"string\\\"}}},\\\"required\\\":[\\\"functions\\\"]}' --max-turns 5\", workdir=\"\u002Fproject\", timeout=90)\n```\n\nParse `structured_output` from the JSON result. Claude validates output against the schema before returning.\n\n### Session Continuation\n```\n# Start a task\nterminal(command=\"claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fsession.json\", workdir=\"\u002Fproject\", timeout=180)\n\n# Resume with session ID\nterminal(command=\"claude -p 'Continue and add connection pooling' --resume $(cat ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fsession.json | python -c 'import json,sys; print(json.load(sys.stdin)[\\\"session_id\\\"])') --max-turns 5\", workdir=\"\u002Fproject\", timeout=120)\n\n# Or resume the most recent session in the same directory\nterminal(command=\"claude -p 'What did you do last time?' --continue --max-turns 1\", workdir=\"\u002Fproject\", timeout=30)\n\n# Fork a session (new ID, keeps history)\nterminal(command=\"claude -p 'Try a different approach' --resume \u003Cid> --fork-session --max-turns 10\", workdir=\"\u002Fproject\", timeout=120)\n```\n\n### Bare Mode for CI\u002FScripting\n```\nterminal(command=\"claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10\", workdir=\"\u002Fproject\", timeout=180)\n```\n\n`--bare` skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires `ANTHROPIC_API_KEY` (skips OAuth).\n\nTo selectively load context in bare mode:\n| To load | Flag |\n|---------|------|\n| System prompt additions | `--append-system-prompt \"text\"` or `--append-system-prompt-file path` |\n| Settings | `--settings \u003Cfile-or-json>` |\n| MCP servers | `--mcp-config \u003Cfile-or-json>` |\n| Custom agents | `--agents '\u003Cjson>'` |\n\n### Fallback Model for Overload\n```\nterminal(command=\"claude -p 'task' --fallback-model haiku --max-turns 5\", timeout=90)\n```\nAutomatically falls back to the specified model when the default is overloaded (print mode only).\n\n## Complete CLI Flags Reference\n\n### Session & Environment\n| Flag | Effect |\n|------|--------|\n| `-p, --print` | Non-interactive one-shot mode (exits when done) |\n| `-c, --continue` | Resume most recent conversation in current directory |\n| `-r, --resume \u003Cid>` | Resume specific session by ID or name (interactive picker if no ID) |\n| `--fork-session` | When resuming, create new session ID instead of reusing original |\n| `--session-id \u003Cuuid>` | Use a specific UUID for the conversation |\n| `--no-session-persistence` | Don't save session to disk (print mode only) |\n| `--add-dir \u003Cpaths...>` | Grant Claude access to additional working directories |\n| `-w, --worktree [name]` | Run in an isolated git worktree at `.claude\u002Fworktrees\u002F\u003Cname>` |\n| `--tmux` | Create a tmux session for the worktree (requires `--worktree`) |\n| `--ide` | Auto-connect to a valid IDE on startup |\n| `--chrome` \u002F `--no-chrome` | Enable\u002Fdisable Chrome browser integration for web testing |\n| `--from-pr [number]` | Resume session linked to a specific GitHub PR |\n| `--file \u003Cspecs...>` | File resources to download at startup (format: `file_id:relative_path`) |\n\n### Model & Performance\n| Flag | Effect |\n|------|--------|\n| `--model \u003Calias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |\n| `--effort \u003Clevel>` | Reasoning depth: `low`, `medium`, `high`, `xhigh`, `max` |\n| `--max-turns \u003Cn>` | Limit agentic loops (print mode only; prevents runaway) |\n| `--max-budget-usd \u003Cn>` | Cap API spend in dollars (print mode only) |\n| `--fallback-model \u003Cmodel>` | Auto-fallback when default model is overloaded (print mode only) |\n| `--betas \u003Cbetas...>` | Beta headers to include in API requests (API key users only) |\n\n### Permission & Safety\n| Flag | Effect |\n|------|--------|\n| `--dangerously-skip-permissions` | Opt-in only: disables ALL permission prompts (file writes, bash, network). Throwaway worktree \u002F isolated container only — see \"Opt-in\" above |\n| `--allow-dangerously-skip-permissions` | Enable bypass as an *option* without enabling it by default |\n| `--permission-mode \u003Cmode>` | `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` |\n| `--allowedTools \u003Ctools...>` | Whitelist specific tools (comma or space-separated) |\n| `--disallowedTools \u003Ctools...>` | Blacklist specific tools |\n| `--tools \u003Ctools...>` | Override built-in tool set (`\"\"` = none, `\"default\"` = all, or tool names) |\n\n### Output & Input Format\n| Flag | Effect |\n|------|--------|\n| `--output-format \u003Cfmt>` | `text` (default), `json` (single result object), `stream-json` (newline-delimited) |\n| `--input-format \u003Cfmt>` | `text` (default) or `stream-json` (real-time streaming input) |\n| `--json-schema \u003Cschema>` | Force structured JSON output matching a schema |\n| `--verbose` | Full turn-by-turn output |\n| `--include-partial-messages` | Include partial message chunks as they arrive (stream-json + print) |\n| `--replay-user-messages` | Re-emit user messages on stdout (stream-json bidirectional) |\n\n### System Prompt & Context\n| Flag | Effect |\n|------|--------|\n| `--append-system-prompt \u003Ctext>` | **Add** to the default system prompt (preserves built-in capabilities) |\n| `--append-system-prompt-file \u003Cpath>` | **Add** file contents to the default system prompt |\n| `--system-prompt \u003Ctext>` | **Replace** the entire system prompt (use --append instead usually) |\n| `--system-prompt-file \u003Cpath>` | **Replace** the system prompt with file contents |\n| `--bare` | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |\n| `--agents '\u003Cjson>'` | Define custom subagents dynamically as JSON |\n| `--mcp-config \u003Cpath>` | Load MCP servers from JSON file (repeatable) |\n| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configs |\n| `--settings \u003Cfile-or-json>` | Load additional settings from a JSON file or inline JSON |\n| `--setting-sources \u003Csources>` | Comma-separated sources to load: `user`, `project`, `local` |\n| `--plugin-dir \u003Cpaths...>` | Load plugins from directories for this session only |\n| `--disable-slash-commands` | Disable all skills\u002Fslash commands |\n\n### Debugging\n| Flag | Effect |\n|------|--------|\n| `-d, --debug [filter]` | Enable debug logging with optional category filter (e.g., `\"api,hooks\"`, `\"!1p,!file\"`) |\n| `--debug-file \u003Cpath>` | Write debug logs to file (implicitly enables debug mode) |\n\n### Agent Teams\n| Flag | Effect |\n|------|--------|\n| `--teammate-mode \u003Cmode>` | How agent teams display: `auto`, `in-process`, or `tmux` |\n| `--brief` | Enable `SendUserMessage` tool for agent-to-user communication |\n\n### Tool Name Syntax for --allowedTools \u002F --disallowedTools\n```\nRead                    # All file reading\nEdit                    # File editing (existing files)\nWrite                   # File creation (new files)\nBash                    # All shell commands\nBash(git *)             # Only git commands\nBash(git commit *)      # Only git commit commands\nBash(npm run lint:*)    # Pattern matching with wildcards\nWebSearch               # Web search capability\nWebFetch                # Web page fetching\nmcp__\u003Cserver>__\u003Ctool>   # Specific MCP tool\n```\n\n## Settings & Configuration\n\n### Settings Hierarchy (highest to lowest priority)\n1. **CLI flags** — override everything\n2. **Local project:** `.claude\u002Fsettings.local.json` (personal, gitignored)\n3. **Project:** `.claude\u002Fsettings.json` (shared, git-tracked)\n4. **User:** `~\u002F.claude\u002Fsettings.json` (global)\n\n### Permissions in Settings\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"Bash(npm run lint:*)\", \"WebSearch\", \"Read\"],\n    \"ask\": [\"Write(*.ts)\", \"Bash(git push*)\"],\n    \"deny\": [\"Read(.env)\", \"Bash(rm -rf *)\"]\n  }\n}\n```\n\n### Memory Files (CLAUDE.md) Hierarchy\n1. **Global:** `~\u002F.claude\u002FCLAUDE.md` — applies to all projects\n2. **Project:** `.\u002FCLAUDE.md` — project-specific context (git-tracked)\n3. **Local:** `.claude\u002FCLAUDE.local.md` — personal project overrides (gitignored)\n\nUse the `#` prefix in interactive mode to quickly add to memory: `# Always use 2-space indentation`.\n\n## Interactive Session: Slash Commands\n\n### Session & Context\n| Command | Purpose |\n|---------|---------|\n| `\u002Fhelp` | Show all commands (including custom and MCP commands) |\n| `\u002Fcompact [focus]` | Compress context to save tokens; CLAUDE.md survives compaction. E.g., `\u002Fcompact focus on auth logic` |\n| `\u002Fclear` | Wipe conversation history for a fresh start |\n| `\u002Fcontext` | Visualize context usage as a colored grid with optimization tips |\n| `\u002Fcost` | View token usage with per-model and cache-hit breakdowns |\n| `\u002Fresume` | Switch to or resume a different session |\n| `\u002Frewind` | Revert to a previous checkpoint in conversation or code |\n| `\u002Fbtw \u003Cquestion>` | Ask a side question without adding to context cost |\n| `\u002Fstatus` | Show version, connectivity, and session info |\n| `\u002Ftodos` | List tracked action items from the conversation |\n| `\u002Fexit` or `Ctrl+D` | End session |\n\n### Development & Review\n| Command | Purpose |\n|---------|---------|\n| `\u002Freview` | Request code review of current changes |\n| `\u002Fsecurity-review` | Perform security analysis of current changes |\n| `\u002Fplan [description]` | Enter Plan mode with auto-start for task planning |\n| `\u002Floop [interval]` | Schedule recurring tasks within the session |\n| `\u002Fbatch` | Auto-create worktrees for large parallel changes (5-30 worktrees) |\n\n### Configuration & Tools\n| Command | Purpose |\n|---------|---------|\n| `\u002Fmodel [model]` | Switch models mid-session (use arrow keys to adjust effort) |\n| `\u002Feffort [level]` | Set reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max` |\n| `\u002Finit` | Create a CLAUDE.md file for project memory |\n| `\u002Fmemory` | Open CLAUDE.md for editing |\n| `\u002Fconfig` | Open interactive settings configuration |\n| `\u002Fpermissions` | View\u002Fupdate tool permissions |\n| `\u002Fagents` | Manage specialized subagents |\n| `\u002Fmcp` | Interactive UI to manage MCP servers |\n| `\u002Fadd-dir` | Add additional working directories (useful for monorepos) |\n| `\u002Fusage` | Show plan limits and rate limit status |\n| `\u002Fvoice` | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |\n| `\u002Frelease-notes` | Interactive picker for version release notes |\n\n### Custom Slash Commands\nCreate `.claude\u002Fcommands\u002F\u003Cname>.md` (project-shared) or `~\u002F.claude\u002Fcommands\u002F\u003Cname>.md` (personal):\n\n```markdown\n# .claude\u002Fcommands\u002Fdeploy.md\nRun the deploy pipeline:\n1. Run all tests\n2. Build the Docker image\n3. Push to registry\n4. Update the $ARGUMENTS environment (default: staging)\n```\n\nUsage: `\u002Fdeploy production` — `$ARGUMENTS` is replaced with the user's input.\n\n### Skills (Natural Language Invocation)\nUnlike slash commands (manually invoked), skills in `.claude\u002Fskills\u002F` are markdown guides that Claude invokes automatically via natural language when the task matches:\n\n```markdown\n# .claude\u002Fskills\u002Fdatabase-migration.md\nWhen asked to create or modify database migrations:\n1. Use Alembic for migration generation\n2. Always create a rollback function\n3. Test migrations against a local database copy\n```\n\n## Interactive Session: Keyboard Shortcuts\n\n### General Controls\n| Key | Action |\n|-----|--------|\n| `Ctrl+C` | Cancel current input or generation |\n| `Ctrl+D` | Exit session |\n| `Ctrl+R` | Reverse search command history |\n| `Ctrl+B` | Background a running task |\n| `Ctrl+V` | Paste image into conversation |\n| `Ctrl+O` | Transcript mode — see Claude's thinking process |\n| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open prompt in external editor |\n| `Esc Esc` | Rewind conversation or code state \u002F summarize |\n\n### Mode Toggles\n| Key | Action |\n|-----|--------|\n| `Shift+Tab` | Cycle permission modes (Normal → Auto-Accept → Plan) |\n| `Alt+P` | Switch model |\n| `Alt+T` | Toggle thinking mode |\n| `Alt+O` | Toggle Fast Mode |\n\n### Multiline Input\n| Key | Action |\n|-----|--------|\n| `\\` + `Enter` | Quick newline |\n| `Shift+Enter` | Newline (alternative) |\n| `Ctrl+J` | Newline (alternative) |\n\n### Input Prefixes\n| Prefix | Action |\n|--------|--------|\n| `!` | Execute bash directly, bypassing AI (e.g., `!npm test`). Use `!` alone to toggle shell mode. |\n| `@` | Reference files\u002Fdirectories with autocomplete (e.g., `@.\u002Fsrc\u002Fapi\u002F`) |\n| `#` | Quick add to CLAUDE.md memory (e.g., `# Use 2-space indentation`) |\n| `\u002F` | Slash commands |\n\n### Pro Tip: \"ultrathink\"\nUse the keyword \"ultrathink\" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current `\u002Feffort` setting.\n\n## PR Review Pattern\n\n### Quick Review (Print Mode)\n```\nterminal(command=\"cd \u002Fpath\u002Fto\u002Frepo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1\", timeout=60)\n```\n\n### Deep Review (Interactive + Worktree)\n```\nterminal(command=\"tmux new-session -d -s review -x 140 -y 40\")\nterminal(command=\"tmux send-keys -t review 'cd \u002Fpath\u002Fto\u002Frepo && claude -w pr-review' Enter\")\nterminal(command=\"sleep 5 && tmux send-keys -t review Enter\")  # Trust dialog\nterminal(command=\"sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter\")\nterminal(command=\"sleep 30 && tmux capture-pane -t review -p -S -60\")\n```\n\n### PR Review from Number\n```\nterminal(command=\"claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10\", workdir=\"\u002Fpath\u002Fto\u002Frepo\", timeout=120)\n```\n\n### Claude Worktree with tmux\n```\nterminal(command=\"claude -w feature-x --tmux\", workdir=\"\u002Fpath\u002Fto\u002Frepo\")\n```\nCreates an isolated git worktree at `.claude\u002Fworktrees\u002Ffeature-x` AND a tmux session for it. Uses iTerm2 native panes when available; add `--tmux=classic` for traditional tmux.\n\n## Parallel Claude Instances\n\nRun multiple independent Claude tasks simultaneously:\n\n```\n# Task 1: Fix backend\nterminal(command=\"tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~\u002Fproject && claude -p \\\"Fix the auth bug in src\u002Fauth.py\\\" --allowedTools \\\"Read,Edit\\\" --max-turns 10' Enter\")\n\n# Task 2: Write tests\nterminal(command=\"tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~\u002Fproject && claude -p \\\"Write integration tests for the API endpoints\\\" --allowedTools \\\"Read,Write,Bash\\\" --max-turns 15' Enter\")\n\n# Task 3: Update docs\nterminal(command=\"tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~\u002Fproject && claude -p \\\"Update README.md with the new API endpoints\\\" --allowedTools \\\"Read,Edit\\\" --max-turns 5' Enter\")\n\n# Monitor all\nterminal(command=\"sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>\u002Fdev\u002Fnull; done\")\n```\n\n## CLAUDE.md — Project Context File\n\nClaude Code auto-loads `CLAUDE.md` from the project root. Use it to persist project context:\n\n```markdown\n# Project: My API\n\n## Architecture\n- FastAPI backend with SQLAlchemy ORM\n- PostgreSQL database, Redis cache\n- pytest for testing with 90% coverage target\n\n## Key Commands\n- `make test` — run full test suite\n- `make lint` — ruff + mypy\n- `make dev` — start dev server on :8000\n\n## Code Standards\n- Type hints on all public functions\n- Docstrings in Google style\n- 2-space indentation for YAML, 4-space for Python\n- No wildcard imports\n```\n\n**Be specific.** Instead of \"Write good code\", use \"Use 2-space indentation for JS\" or \"Name test files with `.test.ts` suffix.\" Specific instructions save correction cycles.\n\n### Rules Directory (Modular CLAUDE.md)\nFor projects with many rules, use the rules directory instead of one massive CLAUDE.md:\n- **Project rules:** `.claude\u002Frules\u002F*.md` — team-shared, git-tracked\n- **User rules:** `~\u002F.claude\u002Frules\u002F*.md` — personal, global\n\nEach `.md` file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.\n\n### Auto-Memory\nClaude automatically stores learned project context in `~\u002F.claude\u002Fprojects\u002F\u003Cproject>\u002Fmemory\u002F`.\n- **Limit:** 25KB or 200 lines per project\n- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions\n\n## Custom Subagents\n\nDefine specialized agents in `.claude\u002Fagents\u002F` (project), `~\u002F.claude\u002Fagents\u002F` (personal), or via `--agents` CLI flag (session):\n\n### Agent Location Priority\n1. `.claude\u002Fagents\u002F` — project-level, team-shared\n2. `--agents` CLI flag — session-specific, dynamic\n3. `~\u002F.claude\u002Fagents\u002F` — user-level, personal\n\n### Creating an Agent\n```markdown\n# .claude\u002Fagents\u002Fsecurity-reviewer.md\n---\nname: security-reviewer\ndescription: Security-focused code review\nmodel: opus\ntools: [Read, Bash]\n---\nYou are a senior security engineer. Review code for:\n- Injection vulnerabilities (SQL, XSS, command injection)\n- Authentication\u002Fauthorization flaws\n- Secrets in code\n- Unsafe deserialization\n```\n\nInvoke via: `@security-reviewer review the auth module`\n\n### Dynamic Agents via CLI\n```\nterminal(command=\"claude --agents '{\\\"reviewer\\\": {\\\"description\\\": \\\"Reviews code\\\", \\\"prompt\\\": \\\"You are a code reviewer focused on performance\\\"}}' -p 'Use @reviewer to check auth.py'\", timeout=120)\n```\n\nClaude can orchestrate multiple agents: \"Use @db-expert to optimize queries, then @security to audit the changes.\"\n\n## Hooks — Automation on Events\n\nConfigure in `.claude\u002Fsettings.json` (project) or `~\u002F.claude\u002Fsettings.json` (global):\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"Write(*.py)\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"ruff check --fix $CLAUDE_FILE_PATHS\"}]\n    }],\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"if echo \\\"$CLAUDE_TOOL_INPUT\\\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi\"}]\n    }],\n    \"Stop\": [{\n      \"hooks\": [{\"type\": \"command\", \"command\": \"echo 'Claude finished a response' >> ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fclaude-activity.log\"}]\n    }]\n  }\n}\n```\n\n### All 8 Hook Types\n| Hook | When it fires | Common use |\n|------|--------------|------------|\n| `UserPromptSubmit` | Before Claude processes a user prompt | Input validation, logging |\n| `PreToolUse` | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |\n| `PostToolUse` | After a tool finishes | Auto-format code, run linters |\n| `Notification` | On permission requests or input waits | Desktop notifications, alerts |\n| `Stop` | When Claude finishes a response | Completion logging, status updates |\n| `SubagentStop` | When a subagent completes | Agent orchestration |\n| `PreCompact` | Before context memory is cleared | Backup session transcripts |\n| `SessionStart` | When a session begins | Load dev context (e.g., `git status`) |\n\n### Hook Environment Variables\n| Variable | Content |\n|----------|---------|\n| `CLAUDE_PROJECT_DIR` | Current project path |\n| `CLAUDE_FILE_PATHS` | Files being modified |\n| `CLAUDE_TOOL_INPUT` | Tool parameters as JSON |\n\n### Security Hook Examples\n```json\n{\n  \"PreToolUse\": [{\n    \"matcher\": \"Bash\",\n    \"hooks\": [{\"type\": \"command\", \"command\": \"if echo \\\"$CLAUDE_TOOL_INPUT\\\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi\"}]\n  }]\n}\n```\n\n## MCP Integration\n\nAdd external tool servers for databases, APIs, and services:\n\n```\n# GitHub integration\nterminal(command=\"claude mcp add -s user github -- npx @modelcontextprotocol\u002Fserver-github\", timeout=30)\n\n# PostgreSQL queries\nterminal(command=\"claude mcp add -s local postgres -- npx @anthropic-ai\u002Fserver-postgres --connection-string postgresql:\u002F\u002Flocalhost\u002Fmydb\", timeout=30)\n\n# Puppeteer for web testing\nterminal(command=\"claude mcp add puppeteer -- npx @anthropic-ai\u002Fserver-puppeteer\", timeout=30)\n```\n\n### MCP Scopes\n| Flag | Scope | Storage |\n|------|-------|---------|\n| `-s user` | Global (all projects) | `~\u002F.claude.json` |\n| `-s local` | This project (personal) | `.claude\u002Fsettings.local.json` (gitignored) |\n| `-s project` | This project (team-shared) | `.claude\u002Fsettings.json` (git-tracked) |\n\n### MCP in Print\u002FCI Mode\n```\nterminal(command=\"claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config\", timeout=60)\n```\n`--strict-mcp-config` ignores all MCP servers except those from `--mcp-config`.\n\nReference MCP resources in chat: `@github:issue:\u002F\u002F123`\n\n### MCP Limits & Tuning\n- **Tool descriptions:** 2KB cap per server for tool descriptions and server instructions\n- **Result size:** Default capped; use `maxResultSizeChars` annotation to allow up to **500K** characters for large outputs\n- **Output tokens:** `export MAX_MCP_OUTPUT_TOKENS=50000` — cap output from MCP servers to prevent context flooding\n- **Transports:** `stdio` (local process), `http` (remote), `sse` (server-sent events)\n\n## Monitoring Interactive Sessions\n\n### Reading the TUI Status\n```\n# Periodic capture to check if Claude is still working or waiting for input\nterminal(command=\"tmux capture-pane -t dev -p -S -10\")\n```\n\nLook for these indicators:\n- `❯` at bottom = waiting for your input (Claude is done or asking a question)\n- `●` lines = Claude is actively using tools (reading, writing, running commands)\n- `⏵⏵ bypass permissions on` = status bar showing permissions mode\n- `◐ medium · \u002Feffort` = current effort level in status bar\n- `ctrl+o to expand` = tool output was truncated (can be expanded interactively)\n\n### Context Window Health\nUse `\u002Fcontext` in interactive mode to see a colored grid of context usage. Key thresholds:\n- **\u003C 70%** — Normal operation, full precision\n- **70-85%** — Precision starts dropping, consider `\u002Fcompact`\n- **> 85%** — Hallucination risk spikes significantly, use `\u002Fcompact` or `\u002Fclear`\n\n## Environment Variables\n\n| Variable | Effect |\n|----------|--------|\n| `ANTHROPIC_API_KEY` | API key for authentication (alternative to OAuth) |\n| `CLAUDE_CODE_EFFORT_LEVEL` | Default effort: `low`, `medium`, `high`, `max`, or `auto` |\n| `MAX_THINKING_TOKENS` | Cap thinking tokens (set to `0` to disable thinking entirely) |\n| `MAX_MCP_OUTPUT_TOKENS` | Cap output from MCP servers (default varies; set e.g., `50000`) |\n| `CLAUDE_CODE_NO_FLICKER=1` | Enable alt-screen rendering to eliminate terminal flicker |\n| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from sub-processes for security |\n\n## Cost & Performance Tips\n\n1. **Use `--max-turns`** in print mode to prevent runaway loops. Start with 5-10 for most tasks.\n2. **Use `--max-budget-usd`** for cost caps. Note: minimum ~$0.05 for system prompt cache creation.\n3. **Use `--effort low`** for simple tasks (faster, cheaper). `high` or `max` for complex reasoning.\n4. **Use `--bare`** for CI\u002Fscripting to skip plugin\u002Fhook discovery overhead.\n5. **Use `--allowedTools`** to restrict to only what's needed (e.g., `Read` only for reviews).\n6. **Use `\u002Fcompact`** in interactive sessions when context gets large.\n7. **Pipe input** instead of having Claude read files when you just need analysis of known content.\n8. **Use `--model haiku`** for simple tasks (cheaper) and `--model opus` for complex multi-step work.\n9. **Use `--fallback-model haiku`** in print mode to gracefully handle model overload.\n10. **Start new sessions for distinct tasks** — sessions last 5 hours; fresh context is more efficient.\n11. **Use `--no-session-persistence`** in CI to avoid accumulating saved sessions on disk.\n\n## Pitfalls & Gotchas\n\n1. **Interactive mode REQUIRES tmux** — Claude Code is a full TUI app. Using `pty=true` alone in Hermes terminal works but tmux gives you `capture-pane` for monitoring and `send-keys` for input, which is essential for orchestration.\n2. **The `--dangerously-skip-permissions` warning dialog defaults to \"No, exit\"** — that default is the safe answer; only send Down then Enter when you deliberately opted into the bypass in an isolated environment. Print mode (`-p`) skips the dialog entirely.\n3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately.\n4. **`--max-turns` is print-mode only** — ignored in interactive sessions.\n5. **Claude may use `python` instead of `python`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects.\n6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory.\n7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns.\n8. **Trust dialog only appears once per directory** — first-time only, then cached.\n9. **Background tmux sessions persist** — always clean up with `tmux kill-session -t \u003Cname>` when done.\n10. **Slash commands (like `\u002Fcommit`) only work in interactive mode** — in `-p` mode, describe the task in natural language instead.\n11. **`--bare` skips OAuth** — requires `ANTHROPIC_API_KEY` env var or an `apiKeyHelper` in settings.\n12. **Context degradation is real** — AI output quality measurably degrades above 70% context window usage. Monitor with `\u002Fcontext` and proactively `\u002Fcompact`.\n\n## Rules for Hermes Agents\n\n1. **Prefer print mode (`-p`) for single tasks** — cleaner, no dialog handling, structured output\n2. **Use tmux for multi-turn interactive work** — the only reliable way to orchestrate the TUI\n3. **Always set `workdir`** — keep Claude focused on the right project directory\n4. **Set `--max-turns` in print mode** — prevents infinite loops and runaway costs\n5. **Monitor tmux sessions** — use `tmux capture-pane -t \u003Csession> -p -S -50` to check progress\n6. **Look for the `❯` prompt** — indicates Claude is waiting for input (done or asking a question)\n7. **Clean up tmux sessions** — kill them when done to avoid resource leaks\n8. **Report results to user** — after completion, summarize what Claude did and what changed\n9. **Don't kill slow sessions** — Claude may be doing multi-step work; check progress instead\n10. **Use `--allowedTools`** — restrict capabilities to what the task actually needs\n","# Claude Code — Hermes Orchestration Guide\n\nDelegate coding tasks to [Claude Code](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcli-reference) (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.\n\n## Prerequisites\n\n- **Install:** `npm install -g @anthropic-ai\u002Fclaude-code`\n- **Auth:** run `claude` once to log in (browser OAuth for Pro\u002FMax, or set `ANTHROPIC_API_KEY`)\n- **Console auth:** `claude auth login --console` for API key billing\n- **SSO auth:** `claude auth login --sso` for Enterprise\n- **Check status:** `claude auth status` (JSON) or `claude auth status --text` (human-readable)\n- **Health check:** `claude doctor` — checks auto-updater and installation health\n- **Version check:** `claude --version` (requires v2.x+)\n- **Update:** `claude update` or `claude upgrade`\n\n## Two Orchestration Modes\n\nHermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.\n\n### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)\n\nPrint mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.\n\n```\nterminal(command=\"claude -p 'Add error handling to all API calls in src\u002F' --allowedTools 'Read,Edit' --max-turns 10\", workdir=\"\u002Fpath\u002Fto\u002Fproject\", timeout=120)\n```\n\n**When to use print mode:**\n- One-shot coding tasks (fix a bug, add a feature, refactor)\n- CI\u002FCD automation and scripting\n- Structured data extraction with `--json-schema`\n- Piped input processing (`cat file | claude -p \"analyze this\"`)\n- Any task where you don't need multi-turn conversation\n\n**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.\n\n### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions\n\nInteractive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. **Requires tmux orchestration.**\n\n```\n# Start a tmux session\nterminal(command=\"tmux new-session -d -s claude-work -x 140 -y 40\")\n\n# Launch Claude Code inside it\nterminal(command=\"tmux send-keys -t claude-work 'cd \u002Fpath\u002Fto\u002Fproject && claude' Enter\")\n\n# Wait for startup, then send your task\n# (after ~3-5 seconds for the welcome screen)\nterminal(command=\"sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter\")\n\n# Monitor progress by capturing the pane\nterminal(command=\"sleep 15 && tmux capture-pane -t claude-work -p -S -50\")\n\n# Send follow-up tasks\nterminal(command=\"tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter\")\n\n# Exit when done\nterminal(command=\"tmux send-keys -t claude-work '\u002Fexit' Enter\")\n```\n\n**When to use interactive mode:**\n- Multi-turn iterative work (refactor → review → fix → test cycle)\n- Tasks requiring human-in-the-loop decisions\n- Exploratory coding sessions\n- When you need to use Claude's slash commands (`\u002Fcompact`, `\u002Freview`, `\u002Fmodel`)\n\n## PTY Dialog Handling (CRITICAL for Interactive Mode)\n\nClaude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:\n\n### Dialog 1: Workspace Trust (first visit to a directory)\n```\n❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)\n  2. No, exit\n```\n**Handling:** `tmux send-keys -t \u003Csession> Enter` — default selection is correct.\n\n### Dialog 2: Individual Permission Prompts (normal flow)\n\nEach tool use that needs approval (file write, shell command, network) shows a prompt. Answer that one prompt — this is different from disabling prompts for the whole run:\n```\n# Read the prompt before answering it\nterminal(command=\"tmux capture-pane -t \u003Csession> -p -S -30\")\n# Allow this one action (Enter = default \"Yes\"); Esc declines it\nterminal(command=\"tmux send-keys -t \u003Csession> Enter\")\n```\nNever send a blind `Enter` on a timer to approve prompts you have not read — that is the bypass flag with extra steps.\n\nA narrower opt-in than the full bypass is `--permission-mode acceptEdits`: file edits in the working directory are accepted, shell and other tool calls still prompt. Use it only in a dedicated worktree after reviewing the task.\n\n### Robust Dialog Handling Pattern\n```\n# Default launch — keep permission prompts enabled\nterminal(command=\"tmux send-keys -t claude-work 'claude \\\"your task\\\"' Enter\")\n\n# Handle trust dialog (Enter for default \"Yes\")\nterminal(command=\"sleep 4 && tmux send-keys -t claude-work Enter\")\n\n# Now wait for Claude to work\nterminal(command=\"sleep 15 && tmux capture-pane -t claude-work -p -S -60\")\n```\n\n**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again.\n\n### Opt-in: --dangerously-skip-permissions (isolated environments only)\n\nThis disables permission prompts for the whole run — grants filesystem, shell, and network access with no prompts. Acceptable only in a throwaway worktree or isolated container.\n```\n❯ 1. No, exit                    ← DEFAULT (safe choice)\n  2. Yes, I accept\n```\nTo accept: `tmux send-keys -t \u003Csession> Down && sleep 0.3 && tmux send-keys -t \u003Csession> Enter`\n\n## CLI Subcommands\n\n| Subcommand | Purpose |\n|------------|---------|\n| `claude` | Start interactive REPL |\n| `claude \"query\"` | Start REPL with initial prompt |\n| `claude -p \"query\"` | Print mode (non-interactive, exits when done) |\n| `cat file \\| claude -p \"query\"` | Pipe content as stdin context |\n| `claude -c` | Continue the most recent conversation in this directory |\n| `claude -r \"id\"` | Resume a specific session by ID or name |\n| `claude auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |\n| `claude auth status` | Check login status (returns JSON; `--text` for human-readable) |\n| `claude mcp add \u003Cname> -- \u003Ccmd>` | Add an MCP server |\n| `claude mcp list` | List configured MCP servers |\n| `claude mcp remove \u003Cname>` | Remove an MCP server |\n| `claude agents` | List configured agents |\n| `claude doctor` | Run health checks on installation and auto-updater |\n| `claude update` \u002F `claude upgrade` | Update Claude Code to latest version |\n| `claude remote-control` | Start server to control Claude from claude.ai or mobile app |\n| `claude install [target]` | Install native build (stable, latest, or specific version) |\n| `claude setup-token` | Set up long-lived auth token (requires subscription) |\n| `claude plugin` \u002F `claude plugins` | Manage Claude Code plugins |\n| `claude auto-mode` | Inspect auto mode classifier configuration |\n\n## Print Mode Deep Dive\n\n### Structured JSON Output\n```\nterminal(command=\"claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5\", workdir=\"\u002Fproject\", timeout=120)\n```\n\nReturns a JSON object with:\n```json\n{\n  \"type\": \"result\",\n  \"subtype\": \"success\",\n  \"result\": \"The analysis text...\",\n  \"session_id\": \"75e2167f-...\",\n  \"num_turns\": 3,\n  \"total_cost_usd\": 0.0787,\n  \"duration_ms\": 10276,\n  \"stop_reason\": \"end_turn\",\n  \"terminal_reason\": \"completed\",\n  \"usage\": { \"input_tokens\": 5, \"output_tokens\": 603, ... },\n  \"modelUsage\": { \"claude-sonnet-4-6\": { \"costUSD\": 0.078, \"contextWindow\": 200000 } }\n}\n```\n\n**Key fields:** `session_id` for resumption, `num_turns` for agentic loop count, `total_cost_usd` for spend tracking, `subtype` for success\u002Ferror detection (`success`, `error_max_turns`, `error_budget`).\n\n### Streaming JSON Output\nFor real-time token streaming, use `stream-json` with `--verbose`:\n```\nterminal(command=\"claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages\", timeout=60)\n```\n\nReturns newline-delimited JSON events. Filter with jq for live text:\n```\nclaude -p \"Explain X\" --output-format stream-json --verbose --include-partial-messages | \\\n  jq -rj 'select(.type == \"stream_event\" and .event.delta.type? == \"text_delta\") | .event.delta.text'\n```\n\nStream events include `system\u002Fapi_retry` with `attempt`, `max_retries`, and `error` fields (e.g., `rate_limit`, `billing_error`).\n\n### Bidirectional Streaming\nFor real-time input AND output streaming:\n```\nclaude -p \"task\" --input-format stream-json --output-format stream-json --replay-user-messages\n```\n`--replay-user-messages` re-emits user messages on stdout for acknowledgment.\n\n### Piped Input\n```\n# Pipe a file for analysis\nterminal(command=\"cat src\u002Fauth.py | claude -p 'Review this code for bugs' --max-turns 1\", timeout=60)\n\n# Pipe multiple files\nterminal(command=\"cat src\u002F*.py | claude -p 'Find all TODO comments' --max-turns 1\", timeout=60)\n\n# Pipe command output\nterminal(command=\"git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1\", timeout=60)\n```\n\n### JSON Schema for Structured Extraction\n```\nterminal(command=\"claude -p 'List all functions in src\u002F' --output-format json --json-schema '{\\\"type\\\":\\\"object\\\",\\\"properties\\\":{\\\"functions\\\":{\\\"type\\\":\\\"array\\\",\\\"items\\\":{\\\"type\\\":\\\"string\\\"}}},\\\"required\\\":[\\\"functions\\\"]}' --max-turns 5\", workdir=\"\u002Fproject\", timeout=90)\n```\n\nParse `structured_output` from the JSON result. Claude validates output against the schema before returning.\n\n### Session Continuation\n```\n# Start a task\nterminal(command=\"claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fsession.json\", workdir=\"\u002Fproject\", timeout=180)\n\n# Resume with session ID\nterminal(command=\"claude -p 'Continue and add connection pooling' --resume $(cat ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fsession.json | python -c 'import json,sys; print(json.load(sys.stdin)[\\\"session_id\\\"])') --max-turns 5\", workdir=\"\u002Fproject\", timeout=120)\n\n# Or resume the most recent session in the same directory\nterminal(command=\"claude -p 'What did you do last time?' --continue --max-turns 1\", workdir=\"\u002Fproject\", timeout=30)\n\n# Fork a session (new ID, keeps history)\nterminal(command=\"claude -p 'Try a different approach' --resume \u003Cid> --fork-session --max-turns 10\", workdir=\"\u002Fproject\", timeout=120)\n```\n\n### Bare Mode for CI\u002FScripting\n```\nterminal(command=\"claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10\", workdir=\"\u002Fproject\", timeout=180)\n```\n\n`--bare` skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires `ANTHROPIC_API_KEY` (skips OAuth).\n\nTo selectively load context in bare mode:\n| To load | Flag |\n|---------|------|\n| System prompt additions | `--append-system-prompt \"text\"` or `--append-system-prompt-file path` |\n| Settings | `--settings \u003Cfile-or-json>` |\n| MCP servers | `--mcp-config \u003Cfile-or-json>` |\n| Custom agents | `--agents '\u003Cjson>'` |\n\n### Fallback Model for Overload\n```\nterminal(command=\"claude -p 'task' --fallback-model haiku --max-turns 5\", timeout=90)\n```\nAutomatically falls back to the specified model when the default is overloaded (print mode only).\n\n## Complete CLI Flags Reference\n\n### Session & Environment\n| Flag | Effect |\n|------|--------|\n| `-p, --print` | Non-interactive one-shot mode (exits when done) |\n| `-c, --continue` | Resume most recent conversation in current directory |\n| `-r, --resume \u003Cid>` | Resume specific session by ID or name (interactive picker if no ID) |\n| `--fork-session` | When resuming, create new session ID instead of reusing original |\n| `--session-id \u003Cuuid>` | Use a specific UUID for the conversation |\n| `--no-session-persistence` | Don't save session to disk (print mode only) |\n| `--add-dir \u003Cpaths...>` | Grant Claude access to additional working directories |\n| `-w, --worktree [name]` | Run in an isolated git worktree at `.claude\u002Fworktrees\u002F\u003Cname>` |\n| `--tmux` | Create a tmux session for the worktree (requires `--worktree`) |\n| `--ide` | Auto-connect to a valid IDE on startup |\n| `--chrome` \u002F `--no-chrome` | Enable\u002Fdisable Chrome browser integration for web testing |\n| `--from-pr [number]` | Resume session linked to a specific GitHub PR |\n| `--file \u003Cspecs...>` | File resources to download at startup (format: `file_id:relative_path`) |\n\n### Model & Performance\n| Flag | Effect |\n|------|--------|\n| `--model \u003Calias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |\n| `--effort \u003Clevel>` | Reasoning depth: `low`, `medium`, `high`, `xhigh`, `max` |\n| `--max-turns \u003Cn>` | Limit agentic loops (print mode only; prevents runaway) |\n| `--max-budget-usd \u003Cn>` | Cap API spend in dollars (print mode only) |\n| `--fallback-model \u003Cmodel>` | Auto-fallback when default model is overloaded (print mode only) |\n| `--betas \u003Cbetas...>` | Beta headers to include in API requests (API key users only) |\n\n### Permission & Safety\n| Flag | Effect |\n|------|--------|\n| `--dangerously-skip-permissions` | Opt-in only: disables ALL permission prompts (file writes, bash, network). Throwaway worktree \u002F isolated container only — see \"Opt-in\" above |\n| `--allow-dangerously-skip-permissions` | Enable bypass as an *option* without enabling it by default |\n| `--permission-mode \u003Cmode>` | `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` |\n| `--allowedTools \u003Ctools...>` | Whitelist specific tools (comma or space-separated) |\n| `--disallowedTools \u003Ctools...>` | Blacklist specific tools |\n| `--tools \u003Ctools...>` | Override built-in tool set (`\"\"` = none, `\"default\"` = all, or tool names) |\n\n### Output & Input Format\n| Flag | Effect |\n|------|--------|\n| `--output-format \u003Cfmt>` | `text` (default), `json` (single result object), `stream-json` (newline-delimited) |\n| `--input-format \u003Cfmt>` | `text` (default) or `stream-json` (real-time streaming input) |\n| `--json-schema \u003Cschema>` | Force structured JSON output matching a schema |\n| `--verbose` | Full turn-by-turn output |\n| `--include-partial-messages` | Include partial message chunks as they arrive (stream-json + print) |\n| `--replay-user-messages` | Re-emit user messages on stdout (stream-json bidirectional) |\n\n### System Prompt & Context\n| Flag | Effect |\n|------|--------|\n| `--append-system-prompt \u003Ctext>` | **Add** to the default system prompt (preserves built-in capabilities) |\n| `--append-system-prompt-file \u003Cpath>` | **Add** file contents to the default system prompt |\n| `--system-prompt \u003Ctext>` | **Replace** the entire system prompt (use --append instead usually) |\n| `--system-prompt-file \u003Cpath>` | **Replace** the system prompt with file contents |\n| `--bare` | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |\n| `--agents '\u003Cjson>'` | Define custom subagents dynamically as JSON |\n| `--mcp-config \u003Cpath>` | Load MCP servers from JSON file (repeatable) |\n| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configs |\n| `--settings \u003Cfile-or-json>` | Load additional settings from a JSON file or inline JSON |\n| `--setting-sources \u003Csources>` | Comma-separated sources to load: `user`, `project`, `local` |\n| `--plugin-dir \u003Cpaths...>` | Load plugins from directories for this session only |\n| `--disable-slash-commands` | Disable all skills\u002Fslash commands |\n\n### Debugging\n| Flag | Effect |\n|------|--------|\n| `-d, --debug [filter]` | Enable debug logging with optional category filter (e.g., `\"api,hooks\"`, `\"!1p,!file\"`) |\n| `--debug-file \u003Cpath>` | Write debug logs to file (implicitly enables debug mode) |\n\n### Agent Teams\n| Flag | Effect |\n|------|--------|\n| `--teammate-mode \u003Cmode>` | How agent teams display: `auto`, `in-process`, or `tmux` |\n| `--brief` | Enable `SendUserMessage` tool for agent-to-user communication |\n\n### Tool Name Syntax for --allowedTools \u002F --disallowedTools\n```\nRead                    # All file reading\nEdit                    # File editing (existing files)\nWrite                   # File creation (new files)\nBash                    # All shell commands\nBash(git *)             # Only git commands\nBash(git commit *)      # Only git commit commands\nBash(npm run lint:*)    # Pattern matching with wildcards\nWebSearch               # Web search capability\nWebFetch                # Web page fetching\nmcp__\u003Cserver>__\u003Ctool>   # Specific MCP tool\n```\n\n## Settings & Configuration\n\n### Settings Hierarchy (highest to lowest priority)\n1. **CLI flags** — override everything\n2. **Local project:** `.claude\u002Fsettings.local.json` (personal, gitignored)\n3. **Project:** `.claude\u002Fsettings.json` (shared, git-tracked)\n4. **User:** `~\u002F.claude\u002Fsettings.json` (global)\n\n### Permissions in Settings\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"Bash(npm run lint:*)\", \"WebSearch\", \"Read\"],\n    \"ask\": [\"Write(*.ts)\", \"Bash(git push*)\"],\n    \"deny\": [\"Read(.env)\", \"Bash(rm -rf *)\"]\n  }\n}\n```\n\n### Memory Files (CLAUDE.md) Hierarchy\n1. **Global:** `~\u002F.claude\u002FCLAUDE.md` — applies to all projects\n2. **Project:** `.\u002FCLAUDE.md` — project-specific context (git-tracked)\n3. **Local:** `.claude\u002FCLAUDE.local.md` — personal project overrides (gitignored)\n\nUse the `#` prefix in interactive mode to quickly add to memory: `# Always use 2-space indentation`.\n\n## Interactive Session: Slash Commands\n\n### Session & Context\n| Command | Purpose |\n|---------|---------|\n| `\u002Fhelp` | Show all commands (including custom and MCP commands) |\n| `\u002Fcompact [focus]` | Compress context to save tokens; CLAUDE.md survives compaction. E.g., `\u002Fcompact focus on auth logic` |\n| `\u002Fclear` | Wipe conversation history for a fresh start |\n| `\u002Fcontext` | Visualize context usage as a colored grid with optimization tips |\n| `\u002Fcost` | View token usage with per-model and cache-hit breakdowns |\n| `\u002Fresume` | Switch to or resume a different session |\n| `\u002Frewind` | Revert to a previous checkpoint in conversation or code |\n| `\u002Fbtw \u003Cquestion>` | Ask a side question without adding to context cost |\n| `\u002Fstatus` | Show version, connectivity, and session info |\n| `\u002Ftodos` | List tracked action items from the conversation |\n| `\u002Fexit` or `Ctrl+D` | End session |\n\n### Development & Review\n| Command | Purpose |\n|---------|---------|\n| `\u002Freview` | Request code review of current changes |\n| `\u002Fsecurity-review` | Perform security analysis of current changes |\n| `\u002Fplan [description]` | Enter Plan mode with auto-start for task planning |\n| `\u002Floop [interval]` | Schedule recurring tasks within the session |\n| `\u002Fbatch` | Auto-create worktrees for large parallel changes (5-30 worktrees) |\n\n### Configuration & Tools\n| Command | Purpose |\n|---------|---------|\n| `\u002Fmodel [model]` | Switch models mid-session (use arrow keys to adjust effort) |\n| `\u002Feffort [level]` | Set reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max` |\n| `\u002Finit` | Create a CLAUDE.md file for project memory |\n| `\u002Fmemory` | Open CLAUDE.md for editing |\n| `\u002Fconfig` | Open interactive settings configuration |\n| `\u002Fpermissions` | View\u002Fupdate tool permissions |\n| `\u002Fagents` | Manage specialized subagents |\n| `\u002Fmcp` | Interactive UI to manage MCP servers |\n| `\u002Fadd-dir` | Add additional working directories (useful for monorepos) |\n| `\u002Fusage` | Show plan limits and rate limit status |\n| `\u002Fvoice` | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |\n| `\u002Frelease-notes` | Interactive picker for version release notes |\n\n### Custom Slash Commands\nCreate `.claude\u002Fcommands\u002F\u003Cname>.md` (project-shared) or `~\u002F.claude\u002Fcommands\u002F\u003Cname>.md` (personal):\n\n```markdown\n# .claude\u002Fcommands\u002Fdeploy.md\nRun the deploy pipeline:\n1. Run all tests\n2. Build the Docker image\n3. Push to registry\n4. Update the $ARGUMENTS environment (default: staging)\n```\n\nUsage: `\u002Fdeploy production` — `$ARGUMENTS` is replaced with the user's input.\n\n### Skills (Natural Language Invocation)\nUnlike slash commands (manually invoked), skills in `.claude\u002Fskills\u002F` are markdown guides that Claude invokes automatically via natural language when the task matches:\n\n```markdown\n# .claude\u002Fskills\u002Fdatabase-migration.md\nWhen asked to create or modify database migrations:\n1. Use Alembic for migration generation\n2. Always create a rollback function\n3. Test migrations against a local database copy\n```\n\n## Interactive Session: Keyboard Shortcuts\n\n### General Controls\n| Key | Action |\n|-----|--------|\n| `Ctrl+C` | Cancel current input or generation |\n| `Ctrl+D` | Exit session |\n| `Ctrl+R` | Reverse search command history |\n| `Ctrl+B` | Background a running task |\n| `Ctrl+V` | Paste image into conversation |\n| `Ctrl+O` | Transcript mode — see Claude's thinking process |\n| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open prompt in external editor |\n| `Esc Esc` | Rewind conversation or code state \u002F summarize |\n\n### Mode Toggles\n| Key | Action |\n|-----|--------|\n| `Shift+Tab` | Cycle permission modes (Normal → Auto-Accept → Plan) |\n| `Alt+P` | Switch model |\n| `Alt+T` | Toggle thinking mode |\n| `Alt+O` | Toggle Fast Mode |\n\n### Multiline Input\n| Key | Action |\n|-----|--------|\n| `\\` + `Enter` | Quick newline |\n| `Shift+Enter` | Newline (alternative) |\n| `Ctrl+J` | Newline (alternative) |\n\n### Input Prefixes\n| Prefix | Action |\n|--------|--------|\n| `!` | Execute bash directly, bypassing AI (e.g., `!npm test`). Use `!` alone to toggle shell mode. |\n| `@` | Reference files\u002Fdirectories with autocomplete (e.g., `@.\u002Fsrc\u002Fapi\u002F`) |\n| `#` | Quick add to CLAUDE.md memory (e.g., `# Use 2-space indentation`) |\n| `\u002F` | Slash commands |\n\n### Pro Tip: \"ultrathink\"\nUse the keyword \"ultrathink\" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current `\u002Feffort` setting.\n\n## PR Review Pattern\n\n### Quick Review (Print Mode)\n```\nterminal(command=\"cd \u002Fpath\u002Fto\u002Frepo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1\", timeout=60)\n```\n\n### Deep Review (Interactive + Worktree)\n```\nterminal(command=\"tmux new-session -d -s review -x 140 -y 40\")\nterminal(command=\"tmux send-keys -t review 'cd \u002Fpath\u002Fto\u002Frepo && claude -w pr-review' Enter\")\nterminal(command=\"sleep 5 && tmux send-keys -t review Enter\")  # Trust dialog\nterminal(command=\"sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter\")\nterminal(command=\"sleep 30 && tmux capture-pane -t review -p -S -60\")\n```\n\n### PR Review from Number\n```\nterminal(command=\"claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10\", workdir=\"\u002Fpath\u002Fto\u002Frepo\", timeout=120)\n```\n\n### Claude Worktree with tmux\n```\nterminal(command=\"claude -w feature-x --tmux\", workdir=\"\u002Fpath\u002Fto\u002Frepo\")\n```\nCreates an isolated git worktree at `.claude\u002Fworktrees\u002Ffeature-x` AND a tmux session for it. Uses iTerm2 native panes when available; add `--tmux=classic` for traditional tmux.\n\n## Parallel Claude Instances\n\nRun multiple independent Claude tasks simultaneously:\n\n```\n# Task 1: Fix backend\nterminal(command=\"tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~\u002Fproject && claude -p \\\"Fix the auth bug in src\u002Fauth.py\\\" --allowedTools \\\"Read,Edit\\\" --max-turns 10' Enter\")\n\n# Task 2: Write tests\nterminal(command=\"tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~\u002Fproject && claude -p \\\"Write integration tests for the API endpoints\\\" --allowedTools \\\"Read,Write,Bash\\\" --max-turns 15' Enter\")\n\n# Task 3: Update docs\nterminal(command=\"tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~\u002Fproject && claude -p \\\"Update README.md with the new API endpoints\\\" --allowedTools \\\"Read,Edit\\\" --max-turns 5' Enter\")\n\n# Monitor all\nterminal(command=\"sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>\u002Fdev\u002Fnull; done\")\n```\n\n## CLAUDE.md — Project Context File\n\nClaude Code auto-loads `CLAUDE.md` from the project root. Use it to persist project context:\n\n```markdown\n# Project: My API\n\n## Architecture\n- FastAPI backend with SQLAlchemy ORM\n- PostgreSQL database, Redis cache\n- pytest for testing with 90% coverage target\n\n## Key Commands\n- `make test` — run full test suite\n- `make lint` — ruff + mypy\n- `make dev` — start dev server on :8000\n\n## Code Standards\n- Type hints on all public functions\n- Docstrings in Google style\n- 2-space indentation for YAML, 4-space for Python\n- No wildcard imports\n```\n\n**Be specific.** Instead of \"Write good code\", use \"Use 2-space indentation for JS\" or \"Name test files with `.test.ts` suffix.\" Specific instructions save correction cycles.\n\n### Rules Directory (Modular CLAUDE.md)\nFor projects with many rules, use the rules directory instead of one massive CLAUDE.md:\n- **Project rules:** `.claude\u002Frules\u002F*.md` — team-shared, git-tracked\n- **User rules:** `~\u002F.claude\u002Frules\u002F*.md` — personal, global\n\nEach `.md` file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.\n\n### Auto-Memory\nClaude automatically stores learned project context in `~\u002F.claude\u002Fprojects\u002F\u003Cproject>\u002Fmemory\u002F`.\n- **Limit:** 25KB or 200 lines per project\n- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions\n\n## Custom Subagents\n\nDefine specialized agents in `.claude\u002Fagents\u002F` (project), `~\u002F.claude\u002Fagents\u002F` (personal), or via `--agents` CLI flag (session):\n\n### Agent Location Priority\n1. `.claude\u002Fagents\u002F` — project-level, team-shared\n2. `--agents` CLI flag — session-specific, dynamic\n3. `~\u002F.claude\u002Fagents\u002F` — user-level, personal\n\n### Creating an Agent\n```markdown\n# .claude\u002Fagents\u002Fsecurity-reviewer.md\n---\nname: security-reviewer\ndescription: Security-focused code review\nmodel: opus\ntools: [Read, Bash]\n---\nYou are a senior security engineer. Review code for:\n- Injection vulnerabilities (SQL, XSS, command injection)\n- Authentication\u002Fauthorization flaws\n- Secrets in code\n- Unsafe deserialization\n```\n\nInvoke via: `@security-reviewer review the auth module`\n\n### Dynamic Agents via CLI\n```\nterminal(command=\"claude --agents '{\\\"reviewer\\\": {\\\"description\\\": \\\"Reviews code\\\", \\\"prompt\\\": \\\"You are a code reviewer focused on performance\\\"}}' -p 'Use @reviewer to check auth.py'\", timeout=120)\n```\n\nClaude can orchestrate multiple agents: \"Use @db-expert to optimize queries, then @security to audit the changes.\"\n\n## Hooks — Automation on Events\n\nConfigure in `.claude\u002Fsettings.json` (project) or `~\u002F.claude\u002Fsettings.json` (global):\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"Write(*.py)\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"ruff check --fix $CLAUDE_FILE_PATHS\"}]\n    }],\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{\"type\": \"command\", \"command\": \"if echo \\\"$CLAUDE_TOOL_INPUT\\\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi\"}]\n    }],\n    \"Stop\": [{\n      \"hooks\": [{\"type\": \"command\", \"command\": \"echo 'Claude finished a response' >> ~\u002F.hermes\u002Fcache\u002Fscratch\u002Fclaude-activity.log\"}]\n    }]\n  }\n}\n```\n\n### All 8 Hook Types\n| Hook | When it fires | Common use |\n|------|--------------|------------|\n| `UserPromptSubmit` | Before Claude processes a user prompt | Input validation, logging |\n| `PreToolUse` | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |\n| `PostToolUse` | After a tool finishes | Auto-format code, run linters |\n| `Notification` | On permission requests or input waits | Desktop notifications, alerts |\n| `Stop` | When Claude finishes a response | Completion logging, status updates |\n| `SubagentStop` | When a subagent completes | Agent orchestration |\n| `PreCompact` | Before context memory is cleared | Backup session transcripts |\n| `SessionStart` | When a session begins | Load dev context (e.g., `git status`) |\n\n### Hook Environment Variables\n| Variable | Content |\n|----------|---------|\n| `CLAUDE_PROJECT_DIR` | Current project path |\n| `CLAUDE_FILE_PATHS` | Files being modified |\n| `CLAUDE_TOOL_INPUT` | Tool parameters as JSON |\n\n### Security Hook Examples\n```json\n{\n  \"PreToolUse\": [{\n    \"matcher\": \"Bash\",\n    \"hooks\": [{\"type\": \"command\", \"command\": \"if echo \\\"$CLAUDE_TOOL_INPUT\\\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi\"}]\n  }]\n}\n```\n\n## MCP Integration\n\nAdd external tool servers for databases, APIs, and services:\n\n```\n# GitHub integration\nterminal(command=\"claude mcp add -s user github -- npx @modelcontextprotocol\u002Fserver-github\", timeout=30)\n\n# PostgreSQL queries\nterminal(command=\"claude mcp add -s local postgres -- npx @anthropic-ai\u002Fserver-postgres --connection-string postgresql:\u002F\u002Flocalhost\u002Fmydb\", timeout=30)\n\n# Puppeteer for web testing\nterminal(command=\"claude mcp add puppeteer -- npx @anthropic-ai\u002Fserver-puppeteer\", timeout=30)\n```\n\n### MCP Scopes\n| Flag | Scope | Storage |\n|------|-------|---------|\n| `-s user` | Global (all projects) | `~\u002F.claude.json` |\n| `-s local` | This project (personal) | `.claude\u002Fsettings.local.json` (gitignored) |\n| `-s project` | This project (team-shared) | `.claude\u002Fsettings.json` (git-tracked) |\n\n### MCP in Print\u002FCI Mode\n```\nterminal(command=\"claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config\", timeout=60)\n```\n`--strict-mcp-config` ignores all MCP servers except those from `--mcp-config`.\n\nReference MCP resources in chat: `@github:issue:\u002F\u002F123`\n\n### MCP Limits & Tuning\n- **Tool descriptions:** 2KB cap per server for tool descriptions and server instructions\n- **Result size:** Default capped; use `maxResultSizeChars` annotation to allow up to **500K** characters for large outputs\n- **Output tokens:** `export MAX_MCP_OUTPUT_TOKENS=50000` — cap output from MCP servers to prevent context flooding\n- **Transports:** `stdio` (local process), `http` (remote), `sse` (server-sent events)\n\n## Monitoring Interactive Sessions\n\n### Reading the TUI Status\n```\n# Periodic capture to check if Claude is still working or waiting for input\nterminal(command=\"tmux capture-pane -t dev -p -S -10\")\n```\n\nLook for these indicators:\n- `❯` at bottom = waiting for your input (Claude is done or asking a question)\n- `●` lines = Claude is actively using tools (reading, writing, running commands)\n- `⏵⏵ bypass permissions on` = status bar showing permissions mode\n- `◐ medium · \u002Feffort` = current effort level in status bar\n- `ctrl+o to expand` = tool output was truncated (can be expanded interactively)\n\n### Context Window Health\nUse `\u002Fcontext` in interactive mode to see a colored grid of context usage. Key thresholds:\n- **\u003C 70%** — Normal operation, full precision\n- **70-85%** — Precision starts dropping, consider `\u002Fcompact`\n- **> 85%** — Hallucination risk spikes significantly, use `\u002Fcompact` or `\u002Fclear`\n\n## Environment Variables\n\n| Variable | Effect |\n|----------|--------|\n| `ANTHROPIC_API_KEY` | API key for authentication (alternative to OAuth) |\n| `CLAUDE_CODE_EFFORT_LEVEL` | Default effort: `low`, `medium`, `high`, `max`, or `auto` |\n| `MAX_THINKING_TOKENS` | Cap thinking tokens (set to `0` to disable thinking entirely) |\n| `MAX_MCP_OUTPUT_TOKENS` | Cap output from MCP servers (default varies; set e.g., `50000`) |\n| `CLAUDE_CODE_NO_FLICKER=1` | Enable alt-screen rendering to eliminate terminal flicker |\n| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from sub-processes for security |\n\n## Cost & Performance Tips\n\n1. **Use `--max-turns`** in print mode to prevent runaway loops. Start with 5-10 for most tasks.\n2. **Use `--max-budget-usd`** for cost caps. Note: minimum ~$0.05 for system prompt cache creation.\n3. **Use `--effort low`** for simple tasks (faster, cheaper). `high` or `max` for complex reasoning.\n4. **Use `--bare`** for CI\u002Fscripting to skip plugin\u002Fhook discovery overhead.\n5. **Use `--allowedTools`** to restrict to only what's needed (e.g., `Read` only for reviews).\n6. **Use `\u002Fcompact`** in interactive sessions when context gets large.\n7. **Pipe input** instead of having Claude read files when you just need analysis of known content.\n8. **Use `--model haiku`** for simple tasks (cheaper) and `--model opus` for complex multi-step work.\n9. **Use `--fallback-model haiku`** in print mode to gracefully handle model overload.\n10. **Start new sessions for distinct tasks** — sessions last 5 hours; fresh context is more efficient.\n11. **Use `--no-session-persistence`** in CI to avoid accumulating saved sessions on disk.\n\n## Pitfalls & Gotchas\n\n1. **Interactive mode REQUIRES tmux** — Claude Code is a full TUI app. Using `pty=true` alone in Hermes terminal works but tmux gives you `capture-pane` for monitoring and `send-keys` for input, which is essential for orchestration.\n2. **The `--dangerously-skip-permissions` warning dialog defaults to \"No, exit\"** — that default is the safe answer; only send Down then Enter when you deliberately opted into the bypass in an isolated environment. Print mode (`-p`) skips the dialog entirely.\n3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately.\n4. **`--max-turns` is print-mode only** — ignored in interactive sessions.\n5. **Claude may use `python` instead of `python`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects.\n6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory.\n7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns.\n8. **Trust dialog only appears once per directory** — first-time only, then cached.\n9. **Background tmux sessions persist** — always clean up with `tmux kill-session -t \u003Cname>` when done.\n10. **Slash commands (like `\u002Fcommit`) only work in interactive mode** — in `-p` mode, describe the task in natural language instead.\n11. **`--bare` skips OAuth** — requires `ANTHROPIC_API_KEY` env var or an `apiKeyHelper` in settings.\n12. **Context degradation is real** — AI output quality measurably degrades above 70% context window usage. Monitor with `\u002Fcontext` and proactively `\u002Fcompact`.\n\n## Rules for Hermes Agents\n\n1. **Prefer print mode (`-p`) for single tasks** — cleaner, no dialog handling, structured output\n2. **Use tmux for multi-turn interactive work** — the only reliable way to orchestrate the TUI\n3. **Always set `workdir`** — keep Claude focused on the right project directory\n4. **Set `--max-turns` in print mode** — prevents infinite loops and runaway costs\n5. **Monitor tmux sessions** — use `tmux capture-pane -t \u003Csession> -p -S -50` to check progress\n6. **Look for the `❯` prompt** — indicates Claude is waiting for input (done or asking a question)\n7. **Clean up tmux sessions** — kill them when done to avoid resource leaks\n8. **Report results to user** — after completion, summarize what Claude did and what changed\n9. **Don't kill slow sessions** — Claude may be doing multi-step work; check progress instead\n10. **Use `--allowedTools`** — restrict capabilities to what the task actually needs\n",{"name":5,"author":51,"license":15,"version":52,"metadata":53,"platforms":63,"description":7},"Hermes Agent + Teknium","2.2.1",{"hermes":54},{"tags":55,"related_skills":61},[32,56,57,58,59,31,60],"Claude","Anthropic","Code-Review","Refactoring","Automation",[42,62,33],"hermes-agent",[43,39,40],"main","64e2fc9afa7bb3da1138eb73399144d0e7e73e9d","_hermes\u002Fdefault\u002Fskills\u002Fautonomous-ai-agents\u002Fclaude-code",4,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs","https:\u002F\u002Fgithub.com\u002Fadnichols","2026-11-06 00:28:38",{"source":8,"skillName":5,"commands":72,"prompt":82,"zipAvailable":83},[73,76,79],{"tool":74,"command":75},"npx","npx skills add adnichols\u002Fai-configs --skill claude-code",{"tool":77,"command":78},"bunx","bunx skills add adnichols\u002Fai-configs --skill claude-code",{"tool":80,"command":81},"pnpm","pnpm dlx skills add adnichols\u002Fai-configs --skill claude-code","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fautonomous-ai-agents\u002Fclaude-code\u002FSKILL.md",true,[85,91,95,99],{"path":86,"resourceType":87,"resourceTypeDesc":88,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Famazon_business.md","REFERENCE","参考文档",1228,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fbrunoasm-lab_ordering\u002Freferences\u002Famazon_business.md",{"path":92,"resourceType":87,"resourceTypeDesc":88,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Fconfig.example.yaml",747,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fbrunoasm-lab_ordering\u002Freferences\u002Fconfig.example.yaml",{"path":96,"resourceType":87,"resourceTypeDesc":88,"sizeBytes":97,"sourceHtmlUrl":98},"references\u002Fdirect_vendor.md",1098,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fbrunoasm-lab_ordering\u002Freferences\u002Fdirect_vendor.md",{"path":100,"resourceType":87,"resourceTypeDesc":88,"sizeBytes":101,"sourceHtmlUrl":102},"references\u002Fpritzker_form.md",2076,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fbrunoasm-lab_ordering\u002Freferences\u002Fpritzker_form.md",[104,121,149,173,184,200],{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":46},"01M6CB7RN791P5RRRCJWWC7DAR","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[111,112,113,114,115,116,117,35,36,118,119,40,120,43,39],"recovery","page","blocked page recovery","bot","fallback","use","fetch","Citations","waf","research",{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":134,"publishedAt":46},"01M6CB7NQY2VVYCQJ1QBXACQF4","writing-plans","Use when creating or updating executable software plans. Keep plans as local files unless the user explicitly asks to register them in Doct.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[127,130,131],{"categoryNo":128,"categoryName":129,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":132,"categoryName":133,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者",[135,136,137,138,139,140,141,142,143,144,145,146,116,147,35,36,148],"writing","writing plans","documentation","test","workflow","design","user","development","planning","files","implementation","html","ops","plan",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":164,"publishedAt":46},"01M6CB7JME246KZQHP73Z2STDF","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[155,158,161],{"categoryNo":156,"categoryName":157,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":159,"categoryName":160,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":162,"categoryName":163,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000037","律师与法务",[138,142,165,166,167,35,36,168,148,169,29,170,39,171,43,172,40],"test driven development","red-green-refactor","superpowers","quality","refactor","debugging","tdd","testing",{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":180,"publishedAt":46},"01M6CB7FQ407KQTD4Z9VAWKY54","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[179],{"categoryNo":159,"categoryName":160,"taxonomyType":21,"taxonomyTypeDesc":22},[170,181,142,167,35,36,182,148,183,40,138,43,39],"systematic debugging","troubleshooting","investigation",{"skillNo":185,"name":186,"nameZh":6,"description":187,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":188,"categories":189,"keywords":193,"publishedAt":46},"01M6CB7D57MK88HE5YPZHKH68Q","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[190],{"categoryNo":191,"categoryName":192,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[186,40,194,195,120,196,43,39,197,198,199,35,36,148,143],"validate","experiments","prototype","feasibility","sketch","experiment",{"skillNo":201,"name":202,"nameZh":6,"description":203,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":204,"categories":205,"keywords":208,"publishedAt":46},"01M6CB7APAQ37YE5YE1MAAFT42","simplify-code","Parallel 3-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[206,207],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[209,210,29,211,35,36,212,148,169,30,213,214,142,40,138,43,45,39],"simplify code","simplify","subagent","parallel","delegation","cleanup"]