better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md

@@ -1,763 +0,0 @@
----
-title: "Claude Code — Delegate coding to Claude Code CLI (features, PRs)"
-sidebar_label: "Claude Code"
-description: "Delegate coding to Claude Code CLI (features, PRs)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Claude Code
-
-Delegate coding to Claude Code CLI (features, PRs).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/autonomous-ai-agents\claude-code` |
-| Version | `2.2.1` |
-| Author | Hermes Agent + Teknium |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Coding-Agent`, `Claude`, `Anthropic`, `Code-Review`, `Refactoring`, `PTY`, `Automation` |
-| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Claude Code — Hermes Orchestration Guide
-
-Delegate coding tasks to [Claude Code](https://code.claude.com/docs/en/cli-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.
-
-## Prerequisites
-
-- **Install:** `npm install -g @anthropic-ai/claude-code`
-- **Auth:** run `claude` once to log in (browser OAuth for Pro/Max, or set `ANTHROPIC_API_KEY`)
-- **Console auth:** `claude auth login --console` for API key billing
-- **SSO auth:** `claude auth login --sso` for Enterprise
-- **Check status:** `claude auth status` (JSON) or `claude auth status --text` (human-readable)
-- **Health check:** `claude doctor` — checks auto-updater and installation health
-- **Version check:** `claude --version` (requires v2.x+)
-- **Update:** `claude update` or `claude upgrade`
-
-## Two Orchestration Modes
-
-Hermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.
-
-### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)
-
-Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
-
-```
-terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)
-```
-
-**When to use print mode:**
-- One-shot coding tasks (fix a bug, add a feature, refactor)
-- CI/CD automation and scripting
-- Structured data extraction with `--json-schema`
-- Piped input processing (`cat file | claude -p "analyze this"`)
-- Any task where you don't need multi-turn conversation
-
-**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.
-
-### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions
-
-Interactive 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.**
-
-```
-# Start a tmux session
-terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")
-
-# Launch Claude Code inside it
-terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")
-
-# Wait for startup, then send your task
-# (after ~3-5 seconds for the welcome screen)
-terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")
-
-# Monitor progress by capturing the pane
-terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")
-
-# Send follow-up tasks
-terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")
-
-# Exit when done
-terminal(command="tmux send-keys -t claude-work '/exit' Enter")
-```
-
-**When to use interactive mode:**
-- Multi-turn iterative work (refactor → review → fix → test cycle)
-- Tasks requiring human-in-the-loop decisions
-- Exploratory coding sessions
-- When you need to use Claude's slash commands (`/compact`, `/review`, `/model`)
-
-## PTY Dialog Handling (CRITICAL for Interactive Mode)
-
-Claude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:
-
-### Dialog 1: Workspace Trust (first visit to a directory)
-```
-❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
-  2. No, exit
-```
-**Handling:** `tmux send-keys -t <session> Enter` — default selection is correct.
-
-### Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
-```
-❯ 1. No, exit                    ← DEFAULT (WRONG choice!)
-  2. Yes, I accept
-```
-**Handling:** Must navigate DOWN first, then Enter:
-```
-tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
-```
-
-### Robust Dialog Handling Pattern
-```
-# Launch with permissions bypass
-terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions \"your task\"' Enter")
-
-# Handle trust dialog (Enter for default "Yes")
-terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")
-
-# Handle permissions dialog (Down then Enter for "Yes, I accept")
-terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")
-
-# Now wait for Claude to work
-terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")
-```
-
-**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use `--dangerously-skip-permissions`.
-
-## CLI Subcommands
-
-| Subcommand | Purpose |
-|------------|---------|
-| `claude` | Start interactive REPL |
-| `claude "query"` | Start REPL with initial prompt |
-| `claude -p "query"` | Print mode (non-interactive, exits when done) |
-| `cat file \| claude -p "query"` | Pipe content as stdin context |
-| `claude -c` | Continue the most recent conversation in this directory |
-| `claude -r "id"` | Resume a specific session by ID or name |
-| `claude auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |
-| `claude auth status` | Check login status (returns JSON; `--text` for human-readable) |
-| `claude mcp add <name> -- <cmd>` | Add an MCP server |
-| `claude mcp list` | List configured MCP servers |
-| `claude mcp remove <name>` | Remove an MCP server |
-| `claude agents` | List configured agents |
-| `claude doctor` | Run health checks on installation and auto-updater |
-| `claude update` / `claude upgrade` | Update Claude Code to latest version |
-| `claude remote-control` | Start server to control Claude from claude.ai or mobile app |
-| `claude install [target]` | Install native build (stable, latest, or specific version) |
-| `claude setup-token` | Set up long-lived auth token (requires subscription) |
-| `claude plugin` / `claude plugins` | Manage Claude Code plugins |
-| `claude auto-mode` | Inspect auto mode classifier configuration |
-
-## Print Mode Deep Dive
-
-### Structured JSON Output
-```
-terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)
-```
-
-Returns a JSON object with:
-```json
-{
-  "type": "result",
-  "subtype": "success",
-  "result": "The analysis text...",
-  "session_id": "75e2167f-...",
-  "num_turns": 3,
-  "total_cost_usd": 0.0787,
-  "duration_ms": 10276,
-  "stop_reason": "end_turn",
-  "terminal_reason": "completed",
-  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
-  "modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
-}
-```
-
-**Key fields:** `session_id` for resumption, `num_turns` for agentic loop count, `total_cost_usd` for spend tracking, `subtype` for success/error detection (`success`, `error_max_turns`, `error_budget`).
-
-### Streaming JSON Output
-For real-time token streaming, use `stream-json` with `--verbose`:
-```
-terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)
-```
-
-Returns newline-delimited JSON events. Filter with jq for live text:
-```
-claude -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
-  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
-```
-
-Stream events include `system/api_retry` with `attempt`, `max_retries`, and `error` fields (e.g., `rate_limit`, `billing_error`).
-
-### Bidirectional Streaming
-For real-time input AND output streaming:
-```
-claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages
-```
-`--replay-user-messages` re-emits user messages on stdout for acknowledgment.
-
-### Piped Input
-```
-# Pipe a file for analysis
-terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)
-
-# Pipe multiple files
-terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)
-
-# Pipe command output
-terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)
-```
-
-### JSON Schema for Structured Extraction
-```
-terminal(command="claude -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)
-```
-
-Parse `structured_output` from the JSON result. Claude validates output against the schema before returning.
-
-### Session Continuation
-```
-# Start a task
-terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)
-
-# Resume with session ID
-terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)
-
-# Or resume the most recent session in the same directory
-terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)
-
-# Fork a session (new ID, keeps history)
-terminal(command="claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)
-```
-
-### Bare Mode for CI/Scripting
-```
-terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)
-```
-
-`--bare` skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires `ANTHROPIC_API_KEY` (skips OAuth).
-
-To selectively load context in bare mode:
-| To load | Flag |
-|---------|------|
-| System prompt additions | `--append-system-prompt "text"` or `--append-system-prompt-file path` |
-| Settings | `--settings <file-or-json>` |
-| MCP servers | `--mcp-config <file-or-json>` |
-| Custom agents | `--agents '<json>'` |
-
-### Fallback Model for Overload
-```
-terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)
-```
-Automatically falls back to the specified model when the default is overloaded (print mode only).
-
-## Complete CLI Flags Reference
-
-### Session & Environment
-| Flag | Effect |
-|------|--------|
-| `-p, --print` | Non-interactive one-shot mode (exits when done) |
-| `-c, --continue` | Resume most recent conversation in current directory |
-| `-r, --resume <id>` | Resume specific session by ID or name (interactive picker if no ID) |
-| `--fork-session` | When resuming, create new session ID instead of reusing original |
-| `--session-id <uuid>` | Use a specific UUID for the conversation |
-| `--no-session-persistence` | Don't save session to disk (print mode only) |
-| `--add-dir <paths...>` | Grant Claude access to additional working directories |
-| `-w, --worktree [name]` | Run in an isolated git worktree at `.claude/worktrees/<name>` |
-| `--tmux` | Create a tmux session for the worktree (requires `--worktree`) |
-| `--ide` | Auto-connect to a valid IDE on startup |
-| `--chrome` / `--no-chrome` | Enable/disable Chrome browser integration for web testing |
-| `--from-pr [number]` | Resume session linked to a specific GitHub PR |
-| `--file <specs...>` | File resources to download at startup (format: `file_id:relative_path`) |
-
-### Model & Performance
-| Flag | Effect |
-|------|--------|
-| `--model <alias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |
-| `--effort <level>` | Reasoning depth: `low`, `medium`, `high`, `xhigh`, `max` |
-| `--max-turns <n>` | Limit agentic loops (print mode only; prevents runaway) |
-| `--max-budget-usd <n>` | Cap API spend in dollars (print mode only) |
-| `--fallback-model <model>` | Auto-fallback when default model is overloaded (print mode only) |
-| `--betas <betas...>` | Beta headers to include in API requests (API key users only) |
-
-### Permission & Safety
-| Flag | Effect |
-|------|--------|
-| `--dangerously-skip-permissions` | Auto-approve ALL tool use (file writes, bash, network, etc.) |
-| `--allow-dangerously-skip-permissions` | Enable bypass as an *option* without enabling it by default |
-| `--permission-mode <mode>` | `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` |
-| `--allowedTools <tools...>` | Whitelist specific tools (comma or space-separated) |
-| `--disallowedTools <tools...>` | Blacklist specific tools |
-| `--tools <tools...>` | Override built-in tool set (`""` = none, `"default"` = all, or tool names) |
-
-### Output & Input Format
-| Flag | Effect |
-|------|--------|
-| `--output-format <fmt>` | `text` (default), `json` (single result object), `stream-json` (newline-delimited) |
-| `--input-format <fmt>` | `text` (default) or `stream-json` (real-time streaming input) |
-| `--json-schema <schema>` | Force structured JSON output matching a schema |
-| `--verbose` | Full turn-by-turn output |
-| `--include-partial-messages` | Include partial message chunks as they arrive (stream-json + print) |
-| `--replay-user-messages` | Re-emit user messages on stdout (stream-json bidirectional) |
-
-### System Prompt & Context
-| Flag | Effect |
-|------|--------|
-| `--append-system-prompt <text>` | **Add** to the default system prompt (preserves built-in capabilities) |
-| `--append-system-prompt-file <path>` | **Add** file contents to the default system prompt |
-| `--system-prompt <text>` | **Replace** the entire system prompt (use --append instead usually) |
-| `--system-prompt-file <path>` | **Replace** the system prompt with file contents |
-| `--bare` | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |
-| `--agents '<json>'` | Define custom subagents dynamically as JSON |
-| `--mcp-config <path>` | Load MCP servers from JSON file (repeatable) |
-| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configs |
-| `--settings <file-or-json>` | Load additional settings from a JSON file or inline JSON |
-| `--setting-sources <sources>` | Comma-separated sources to load: `user`, `project`, `local` |
-| `--plugin-dir <paths...>` | Load plugins from directories for this session only |
-| `--disable-slash-commands` | Disable all skills/slash commands |
-
-### Debugging
-| Flag | Effect |
-|------|--------|
-| `-d, --debug [filter]` | Enable debug logging with optional category filter (e.g., `"api,hooks"`, `"!1p,!file"`) |
-| `--debug-file <path>` | Write debug logs to file (implicitly enables debug mode) |
-
-### Agent Teams
-| Flag | Effect |
-|------|--------|
-| `--teammate-mode <mode>` | How agent teams display: `auto`, `in-process`, or `tmux` |
-| `--brief` | Enable `SendUserMessage` tool for agent-to-user communication |
-
-### Tool Name Syntax for --allowedTools / --disallowedTools
-```
-Read                    # All file reading
-Edit                    # File editing (existing files)
-Write                   # File creation (new files)
-Bash                    # All shell commands
-Bash(git *)             # Only git commands
-Bash(git commit *)      # Only git commit commands
-Bash(npm run lint:*)    # Pattern matching with wildcards
-WebSearch               # Web search capability
-WebFetch                # Web page fetching
-mcp__<server>__<tool>   # Specific MCP tool
-```
-
-## Settings & Configuration
-
-### Settings Hierarchy (highest to lowest priority)
-1. **CLI flags** — override everything
-2. **Local project:** `.claude/settings.local.json` (personal, gitignored)
-3. **Project:** `.claude/settings.json` (shared, git-tracked)
-4. **User:** `~/.claude/settings.json` (global)
-
-### Permissions in Settings
-```json
-{
-  "permissions": {
-    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
-    "ask": ["Write(*.ts)", "Bash(git push*)"],
-    "deny": ["Read(.env)", "Bash(rm -rf *)"]
-  }
-}
-```
-
-### Memory Files (CLAUDE.md) Hierarchy
-1. **Global:** `~/.claude/CLAUDE.md` — applies to all projects
-2. **Project:** `./CLAUDE.md` — project-specific context (git-tracked)
-3. **Local:** `.claude/CLAUDE.local.md` — personal project overrides (gitignored)
-
-Use the `#` prefix in interactive mode to quickly add to memory: `# Always use 2-space indentation`.
-
-## Interactive Session: Slash Commands
-
-### Session & Context
-| Command | Purpose |
-|---------|---------|
-| `/help` | Show all commands (including custom and MCP commands) |
-| `/compact [focus]` | Compress context to save tokens; CLAUDE.md survives compaction. E.g., `/compact focus on auth logic` |
-| `/clear` | Wipe conversation history for a fresh start |
-| `/context` | Visualize context usage as a colored grid with optimization tips |
-| `/cost` | View token usage with per-model and cache-hit breakdowns |
-| `/resume` | Switch to or resume a different session |
-| `/rewind` | Revert to a previous checkpoint in conversation or code |
-| `/btw <question>` | Ask a side question without adding to context cost |
-| `/status` | Show version, connectivity, and session info |
-| `/todos` | List tracked action items from the conversation |
-| `/exit` or `Ctrl+D` | End session |
-
-### Development & Review
-| Command | Purpose |
-|---------|---------|
-| `/review` | Request code review of current changes |
-| `/security-review` | Perform security analysis of current changes |
-| `/plan [description]` | Enter Plan mode with auto-start for task planning |
-| `/loop [interval]` | Schedule recurring tasks within the session |
-| `/batch` | Auto-create worktrees for large parallel changes (5-30 worktrees) |
-
-### Configuration & Tools
-| Command | Purpose |
-|---------|---------|
-| `/model [model]` | Switch models mid-session (use arrow keys to adjust effort) |
-| `/effort [level]` | Set reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max` |
-| `/init` | Create a CLAUDE.md file for project memory |
-| `/memory` | Open CLAUDE.md for editing |
-| `/config` | Open interactive settings configuration |
-| `/permissions` | View/update tool permissions |
-| `/agents` | Manage specialized subagents |
-| `/mcp` | Interactive UI to manage MCP servers |
-| `/add-dir` | Add additional working directories (useful for monorepos) |
-| `/usage` | Show plan limits and rate limit status |
-| `/voice` | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |
-| `/release-notes` | Interactive picker for version release notes |
-
-### Custom Slash Commands
-Create `.claude/commands/<name>.md` (project-shared) or `~/.claude/commands/<name>.md` (personal):
-
-```markdown
-# .claude/commands/deploy.md
-Run the deploy pipeline:
-1. Run all tests
-2. Build the Docker image
-3. Push to registry
-4. Update the $ARGUMENTS environment (default: staging)
-```
-
-Usage: `/deploy production` — `$ARGUMENTS` is replaced with the user's input.
-
-### Skills (Natural Language Invocation)
-Unlike slash commands (manually invoked), skills in `.claude/skills/` are markdown guides that Claude invokes automatically via natural language when the task matches:
-
-```markdown
-# .claude/skills/database-migration.md
-When asked to create or modify database migrations:
-1. Use Alembic for migration generation
-2. Always create a rollback function
-3. Test migrations against a local database copy
-```
-
-## Interactive Session: Keyboard Shortcuts
-
-### General Controls
-| Key | Action |
-|-----|--------|
-| `Ctrl+C` | Cancel current input or generation |
-| `Ctrl+D` | Exit session |
-| `Ctrl+R` | Reverse search command history |
-| `Ctrl+B` | Background a running task |
-| `Ctrl+V` | Paste image into conversation |
-| `Ctrl+O` | Transcript mode — see Claude's thinking process |
-| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open prompt in external editor |
-| `Esc Esc` | Rewind conversation or code state / summarize |
-
-### Mode Toggles
-| Key | Action |
-|-----|--------|
-| `Shift+Tab` | Cycle permission modes (Normal → Auto-Accept → Plan) |
-| `Alt+P` | Switch model |
-| `Alt+T` | Toggle thinking mode |
-| `Alt+O` | Toggle Fast Mode |
-
-### Multiline Input
-| Key | Action |
-|-----|--------|
-| `\` + `Enter` | Quick newline |
-| `Shift+Enter` | Newline (alternative) |
-| `Ctrl+J` | Newline (alternative) |
-
-### Input Prefixes
-| Prefix | Action |
-|--------|--------|
-| `!` | Execute bash directly, bypassing AI (e.g., `!npm test`). Use `!` alone to toggle shell mode. |
-| `@` | Reference files/directories with autocomplete (e.g., `@./src/api/`) |
-| `#` | Quick add to CLAUDE.md memory (e.g., `# Use 2-space indentation`) |
-| `/` | Slash commands |
-
-### Pro Tip: "ultrathink"
-Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current `/effort` setting.
-
-## PR Review Pattern
-
-### Quick Review (Print Mode)
-```
-terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)
-```
-
-### Deep Review (Interactive + Worktree)
-```
-terminal(command="tmux new-session -d -s review -x 140 -y 40")
-terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
-terminal(command="sleep 5 && tmux send-keys -t review Enter")  # Trust dialog
-terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
-terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")
-```
-
-### PR Review from Number
-```
-terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)
-```
-
-### Claude Worktree with tmux
-```
-terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")
-```
-Creates an isolated git worktree at `.claude/worktrees/feature-x` AND a tmux session for it. Uses iTerm2 native panes when available; add `--tmux=classic` for traditional tmux.
-
-## Parallel Claude Instances
-
-Run multiple independent Claude tasks simultaneously:
-
-```
-# Task 1: Fix backend
-terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")
-
-# Task 2: Write tests
-terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")
-
-# Task 3: Update docs
-terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")
-
-# Monitor all
-terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")
-```
-
-## CLAUDE.md — Project Context File
-
-Claude Code auto-loads `CLAUDE.md` from the project root. Use it to persist project context:
-
-```markdown
-# Project: My API
-
-## Architecture
-- FastAPI backend with SQLAlchemy ORM
-- PostgreSQL database, Redis cache
-- pytest for testing with 90% coverage target
-
-## Key Commands
-- `make test` — run full test suite
-- `make lint` — ruff + mypy
-- `make dev` — start dev server on :8000
-
-## Code Standards
-- Type hints on all public functions
-- Docstrings in Google style
-- 2-space indentation for YAML, 4-space for Python
-- No wildcard imports
-```
-
-**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.
-
-### Rules Directory (Modular CLAUDE.md)
-For projects with many rules, use the rules directory instead of one massive CLAUDE.md:
-- **Project rules:** `.claude/rules/*.md` — team-shared, git-tracked
-- **User rules:** `~/.claude/rules/*.md` — personal, global
-
-Each `.md` file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.
-
-### Auto-Memory
-Claude automatically stores learned project context in `~/.claude/projects/<project>/memory/`.
-- **Limit:** 25KB or 200 lines per project
-- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions
-
-## Custom Subagents
-
-Define specialized agents in `.claude/agents/` (project), `~/.claude/agents/` (personal), or via `--agents` CLI flag (session):
-
-### Agent Location Priority
-1. `.claude/agents/` — project-level, team-shared
-2. `--agents` CLI flag — session-specific, dynamic
-3. `~/.claude/agents/` — user-level, personal
-
-### Creating an Agent
-```markdown
-# .claude/agents/security-reviewer.md
----
-name: security-reviewer
-description: Security-focused code review
-model: opus
-tools: [Read, Bash]
----
-You are a senior security engineer. Review code for:
-- Injection vulnerabilities (SQL, XSS, command injection)
-- Authentication/authorization flaws
-- Secrets in code
-- Unsafe deserialization
-```
-
-Invoke via: `@security-reviewer review the auth module`
-
-### Dynamic Agents via CLI
-```
-terminal(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)
-```
-
-Claude can orchestrate multiple agents: "Use @db-expert to optimize queries, then @security to audit the changes."
-
-## Hooks — Automation on Events
-
-Configure in `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "Write(*.py)",
-      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
-    }],
-    "PreToolUse": [{
-      "matcher": "Bash",
-      "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
-    }],
-    "Stop": [{
-      "hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> /tmp/claude-activity.log"}]
-    }]
-  }
-}
-```
-
-### All 8 Hook Types
-| Hook | When it fires | Common use |
-|------|--------------|------------|
-| `UserPromptSubmit` | Before Claude processes a user prompt | Input validation, logging |
-| `PreToolUse` | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |
-| `PostToolUse` | After a tool finishes | Auto-format code, run linters |
-| `Notification` | On permission requests or input waits | Desktop notifications, alerts |
-| `Stop` | When Claude finishes a response | Completion logging, status updates |
-| `SubagentStop` | When a subagent completes | Agent orchestration |
-| `PreCompact` | Before context memory is cleared | Backup session transcripts |
-| `SessionStart` | When a session begins | Load dev context (e.g., `git status`) |
-
-### Hook Environment Variables
-| Variable | Content |
-|----------|---------|
-| `CLAUDE_PROJECT_DIR` | Current project path |
-| `CLAUDE_FILE_PATHS` | Files being modified |
-| `CLAUDE_TOOL_INPUT` | Tool parameters as JSON |
-
-### Security Hook Examples
-```json
-{
-  "PreToolUse": [{
-    "matcher": "Bash",
-    "hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
-  }]
-}
-```
-
-## MCP Integration
-
-Add external tool servers for databases, APIs, and services:
-
-```
-# GitHub integration
-terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)
-
-# PostgreSQL queries
-terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)
-
-# Puppeteer for web testing
-terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)
-```
-
-### MCP Scopes
-| Flag | Scope | Storage |
-|------|-------|---------|
-| `-s user` | Global (all projects) | `~/.claude.json` |
-| `-s local` | This project (personal) | `.claude/settings.local.json` (gitignored) |
-| `-s project` | This project (team-shared) | `.claude/settings.json` (git-tracked) |
-
-### MCP in Print/CI Mode
-```
-terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)
-```
-`--strict-mcp-config` ignores all MCP servers except those from `--mcp-config`.
-
-Reference MCP resources in chat: `@github:issue://123`
-
-### MCP Limits & Tuning
-- **Tool descriptions:** 2KB cap per server for tool descriptions and server instructions
-- **Result size:** Default capped; use `maxResultSizeChars` annotation to allow up to **500K** characters for large outputs
-- **Output tokens:** `export MAX_MCP_OUTPUT_TOKENS=50000` — cap output from MCP servers to prevent context flooding
-- **Transports:** `stdio` (local process), `http` (remote), `sse` (server-sent events)
-
-## Monitoring Interactive Sessions
-
-### Reading the TUI Status
-```
-# Periodic capture to check if Claude is still working or waiting for input
-terminal(command="tmux capture-pane -t dev -p -S -10")
-```
-
-Look for these indicators:
-- `❯` at bottom = waiting for your input (Claude is done or asking a question)
-- `●` lines = Claude is actively using tools (reading, writing, running commands)
-- `⏵⏵ bypass permissions on` = status bar showing permissions mode
-- `◐ medium · /effort` = current effort level in status bar
-- `ctrl+o to expand` = tool output was truncated (can be expanded interactively)
-
-### Context Window Health
-Use `/context` in interactive mode to see a colored grid of context usage. Key thresholds:
-- **&lt; 70%** — Normal operation, full precision
-- **70-85%** — Precision starts dropping, consider `/compact`
-- **> 85%** — Hallucination risk spikes significantly, use `/compact` or `/clear`
-
-## Environment Variables
-
-| Variable | Effect |
-|----------|--------|
-| `ANTHROPIC_API_KEY` | API key for authentication (alternative to OAuth) |
-| `CLAUDE_CODE_EFFORT_LEVEL` | Default effort: `low`, `medium`, `high`, `max`, or `auto` |
-| `MAX_THINKING_TOKENS` | Cap thinking tokens (set to `0` to disable thinking entirely) |
-| `MAX_MCP_OUTPUT_TOKENS` | Cap output from MCP servers (default varies; set e.g., `50000`) |
-| `CLAUDE_CODE_NO_FLICKER=1` | Enable alt-screen rendering to eliminate terminal flicker |
-| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from sub-processes for security |
-
-## Cost & Performance Tips
-
-1. **Use `--max-turns`** in print mode to prevent runaway loops. Start with 5-10 for most tasks.
-2. **Use `--max-budget-usd`** for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
-3. **Use `--effort low`** for simple tasks (faster, cheaper). `high` or `max` for complex reasoning.
-4. **Use `--bare`** for CI/scripting to skip plugin/hook discovery overhead.
-5. **Use `--allowedTools`** to restrict to only what's needed (e.g., `Read` only for reviews).
-6. **Use `/compact`** in interactive sessions when context gets large.
-7. **Pipe input** instead of having Claude read files when you just need analysis of known content.
-8. **Use `--model haiku`** for simple tasks (cheaper) and `--model opus` for complex multi-step work.
-9. **Use `--fallback-model haiku`** in print mode to gracefully handle model overload.
-10. **Start new sessions for distinct tasks** — sessions last 5 hours; fresh context is more efficient.
-11. **Use `--no-session-persistence`** in CI to avoid accumulating saved sessions on disk.
-
-## Pitfalls & Gotchas
-
-1. **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.
-2. **`--dangerously-skip-permissions` dialog defaults to "No, exit"** — you must send Down then Enter to accept. Print mode (`-p`) skips this entirely.
-3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately.
-4. **`--max-turns` is print-mode only** — ignored in interactive sessions.
-5. **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.
-6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory.
-7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns.
-8. **Trust dialog only appears once per directory** — first-time only, then cached.
-9. **Background tmux sessions persist** — always clean up with `tmux kill-session -t <name>` when done.
-10. **Slash commands (like `/commit`) only work in interactive mode** — in `-p` mode, describe the task in natural language instead.
-11. **`--bare` skips OAuth** — requires `ANTHROPIC_API_KEY` env var or an `apiKeyHelper` in settings.
-12. **Context degradation is real** — AI output quality measurably degrades above 70% context window usage. Monitor with `/context` and proactively `/compact`.
-
-## Rules for Hermes Agents
-
-1. **Prefer print mode (`-p`) for single tasks** — cleaner, no dialog handling, structured output
-2. **Use tmux for multi-turn interactive work** — the only reliable way to orchestrate the TUI
-3. **Always set `workdir`** — keep Claude focused on the right project directory
-4. **Set `--max-turns` in print mode** — prevents infinite loops and runaway costs
-5. **Monitor tmux sessions** — use `tmux capture-pane -t <session> -p -S -50` to check progress
-6. **Look for the `❯` prompt** — indicates Claude is waiting for input (done or asking a question)
-7. **Clean up tmux sessions** — kill them when done to avoid resource leaks
-8. **Report results to user** — after completion, summarize what Claude did and what changed
-9. **Don't kill slow sessions** — Claude may be doing multi-step work; check progress instead
-10. **Use `--allowedTools`** — restrict capabilities to what the task actually needs