claude-code

name	claude-code
description	Delegate coding to CLI coding agents — Claude Code, Codex, OpenCode (features, PRs, review). Print/interactive orchestration, PTY dialog handling, session control, worktree parallelism, per-agent reference guides.
version	2.3.0
author	Hermes Agent + Teknium
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["Coding-Agent","Claude","Anthropic","Codex","OpenCode","Code-Review","Refactoring","PTY","Automation"],"related_skills":["hermes-agent","hermes-admin"]}}

Claude Code — Hermes Orchestration Guide

Delegate coding tasks to Claude Code (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.

Trust dialog only — no second prompt in some configs. If the status bar shows ⏵⏵ bypass permissions on (set via Shift+Tab cycle in interactive mode, or via /permissions then bypassPermissions), Claude Code does NOT show the "I accept" dialog. Only the folder-trust dialog appears on first launch in a new directory. A single Enter handles it.

Sending Multi-line / CJK / Quotes-Safe Content into a tmux TUI

Plain tmux send-keys -t <session> "long 中文 prompt" Enter mangles content in three ways:

• Shell strips/transforms " and $ inside double-quoted strings before tmux sees them
• Newlines get eaten (send-keys treats spaces, not \n)
• Wide CJK characters can be split mid-codepoint by terminal escape timing, producing tofu in the TUI

Use the tmux paste-buffer pattern — write the prompt to a file first, load it into tmux's paste buffer, then paste it as a single atomic insert. The TUI receives a complete Bracketed Paste Mode chunk and renders it as a single edit:

# 1. Write the prompt to a file (preserves everything verbatim)
write_file(path="/tmp/claude-prompt.md", content="你的多行中文指令...")

# 2. Load into tmux's paste buffer
terminal(command="tmux load-buffer -t claude /tmp/claude-prompt.md")

# 3. Paste into the active pane (atomic)
terminal(command="tmux paste-buffer -t claude")

# 4. Send Enter to submit
terminal(command="tmux send-keys -t claude Enter")

Variants:

# Pipe from stdin (e.g. heredoc in the shell command itself)
tmux load-buffer -t claude - <<'EOF'
multi-line
中文内容 with "quotes" and $vars — all preserved
EOF
tmux paste-buffer -t claude

# Or combine: load + paste + enter in one shot
tmux load-buffer -t claude /tmp/prompt.md && tmux paste-buffer -t claude && tmux send-keys -t claude Enter

Observed result (validated 2026-06-02): Sent a 983-byte Chinese prompt to a Claude Code TUI in tmux. CJK, quotes, newlines, and emoji (✓) all rendered correctly. Claude's first capture-pane after paste-buffer showed the full prompt in the input box; subsequent Enter triggered normal processing.

Sandbox / non-PTY limitation. If you're driving tmux from inside a sandboxed terminal() call that doesn't have a real PTY (e.g. some execute_code subshells), tmux attach fails with open terminal failed: not a terminal. Workaround: drive the session through send-keys + load-buffer + paste-buffer + capture-pane only — never try to attach. The tmux server itself runs fine in a detached session even without a controlling TTY.

Reading Output When You Can't Attach

tmux attach requires a real PTY, which a non-interactive sandbox (some terminal() calls, execute_code subshells, CI runners) doesn't have. Use capture-pane instead — it works in any context:

# Last 100 lines of visible output
terminal(command="tmux capture-pane -t claude -p -S -100")

# Last 200 lines + escape sequences preserved (for state inspection)
terminal(command="tmux capture-pane -t claude -p -e -S -200")

# Just the bottom 10 lines (good for status checks)
terminal(command="tmux capture-pane -t claude -p | tail -10")

Pro tip: When polling for "is Claude done?", grep for the ❯ prompt at the bottom of the captured output — it indicates Claude is waiting for the next user input (done with current turn OR asking a question).

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:

{
  "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 | python3 -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, max, auto
--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

{
  "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.

Routines — Scheduled / Automated Workflows

Important: Routines are available on Claude Code Web (code.claude.com) and in the routine-* CLI commands. The docs are at code.claude.com/docs/en/routines, NOT at docs.anthropic.com.

Routines let you define automated workflows that run on schedule (cron), API trigger, or GitHub events — turning Claude Code from an interactive tool into an autonomous agent. A Routine is defined by a ROUTINE.md file in your project.

Quick Reference

# Deploy a routine from ROUTINE.md
claude routine deploy ROUTINE.md

# List routines
claude routine list

# Trigger a routine manually
claude routine trigger <routine-id>

# View run history
claude routine runs <routine-id>

ROUTINE.md Format

name: my-dashboard-generator
description: "Fetch metrics via MCP and generate HTML dashboard"

triggers:
  - type: schedule
    cron: "0 */6 * * *"        # Every 6 hours
  - type: api
    auth:
      type: api_key
  - type: github
    events:
      - pull_request.opened

mcp_servers:
  - name: local-metrics
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    enabled_tools:
      - read_directory
      - read_file

instructions: |
  You are a metrics dashboard generator. Steps:
  1. Read metrics files from ./data via MCP filesystem tools
  2. Parse JSON and aggregate data
  3. Generate a polished HTML dashboard
  4. Save to output/dashboard-{timestamp}.html

Trigger Types

Trigger	Config	Use Case
schedule	cron: "0 9 * * *"	Periodic reports, heartbeat monitors
api	auth.type: api_key	Webhook-driven workflows
github	events: [pull_request.opened, push]	CI/CD, automated review

MCP Integration in Routines

Routines natively support MCP servers. Configure them in ROUTINE.md under mcp_servers, or reference an mcp-config.json file:

{
  "mcpServers": {
    "local-metrics": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

Tools are called with the same naming convention as the CLI: mcp_<server>_<tool>.

Key Differences: CLI vs Web

Aspect	CLI (claude)	Web (Routines)
Mode	Interactive / print (-p)	Scheduled / event-driven
Execution	On-demand	Cloud-hosted, persistent
Triggers	Manual only	Schedule, API, GitHub
MCP	Via --mcp-config	Native in ROUTINE.md
Output	Terminal	Dashboard + logs

See references/routines.md for deep research, demo code, and production patterns.

Where Routines Docs Live

• Routine docs: https://code.claude.com/docs/en/routines
• MCP servers: https://modelcontextprotocol.io (official servers list)
• Claude Code Web: https://code.claude.com

Note: The docs.anthropic.com domain redirects to platform.claude.com/docs/ which does NOT have Routine documentation. Always use code.claude.com for Routine topics.

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, max, or auto
/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):

# .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:

# .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:

# 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

# .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):

{
  "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

{
  "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:

• < 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 send-keys and capture-pane for orchestration, which is essential for multi-turn sessions. If tmux is not installed, fall back to print mode (-p). macOS: brew install tmux.
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 python3 — 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 degrades above 70% context window usage. Monitor with /context and proactively /compact. See Context Window Optimization for recovery strategies and thresholds.
13. OMC superpowers/skills (brainstorming, plan) are NOT relay-compatible — OMC superpowers like and are designed for real-time conversational interaction. When run via Hermes relay, they stall because the skill's internal dialogue loop doesn't properly receive the initial prompt, causing it to re-ask a question it already answered. Claude's prompt says "What would you like to brainstorm/plan?" even though the topic was already provided in the same prompt. (a) Use the community skill (installed via clawhub, not OMC-based) which is relay-safe; (b) Use print mode () for one-shot design output; (c) Use CLI flag in interactive mode for structured design without the skill loop.

Batch Multi-File Implementation (Phased Subagent Pattern)

When delegating large multi-phase implementation tasks (e.g. Phase 1→2→3 of a project), split into sequential phases of parallel subagents. This avoids exceeding max_concurrent_children=3.

Phase 1 (3 subagents max): files 1-3
Phase 2 (3 subagents max): files 4-7
Phase 3 (3 subagents max): files 8-10

Pattern:

delegate_task(
    context="<all context needed>",
    goal="Write files 1-3: X, Y, Z. Read existing files first.",
    tasks=[
        {"goal": "Write file 1: X.py", "toolsets": ["file"]},
        {"goal": "Write file 2: Y.py", "toolsets": ["file"]},
        {"goal": "Write file 3: Z.py", "toolsets": ["file"]},
    ],
)
# Then second phase...
delegate_task(
    context="<same base context>",
    goal="Write files 4-7: A, B, C, D. Read first.",
    tasks=[
        {"goal": "Write file 4: A.py", "toolsets": ["file"]},
        {"goal": "Write file 5: B.py", "toolsets": ["file"]},
        {"goal": "Write file 6: C.py", "toolsets": ["file"]},
        {"goal": "Write file 7: D.py", "toolsets": ["file"]},
    ],
)

Key constraints:

• max_concurrent_children=3 — never exceed 3 parallel subagents per call
• Task count > 3 → split into sequential phases
• Pass same base context to every phase (subagents have no shared memory)
• Subagents must READ existing files first — they have no knowledge of current project state; telling them to "read first" prevents overwriting existing content
• After all phases: run tests → fix failures → commit → push
• All code in English; Chinese only in data-output nodes
• Subagents can share the same workdir — no worktree isolation needed for non-overlapping file writes
• For TypeScript/React projects: run npm run build (tsc + vite build) to verify after each phase

Anti-pattern (will fail):

# WRONG: 10 tasks exceeds max_concurrent_children=3
delegate_task(tasks=[{"goal": f"Write file {i}"} for i in range(10)])
# Error: "Too many tasks: 10 provided, but max_concurrent_children is 3"

Phase verification pattern:

# After each phase:
terminal(command="cd /path/to/project && .venv/bin/python -m pytest tests/ -v")
# Fix failures before proceeding to next phase
# Then commit: git add -A && git commit -m "Phase N: description"

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

Archived Sub-Skills

Claude Code Memory Persistence (absorbed claude-code-memory-persistence)

A two-layer persistent memory system for Claude Code — Obsidian (declarative/atomic memory) + Graphify (structural knowledge graphs). Reduces token consumption by up to 71x by avoiding re-reading project files every session.

Preserved content:

• references/obsidian-integration.md — Obsidian vault setup, session logs, Zettelkasten notes
• references/graphify-reference.md — Graphify CLI reference, knowledge graph generation
• references/workflow-guide.md — Full /resume → work → /save workflow

The original skill's full SKILL.md is archived under ~/.hermes/skills/.archive/claude-code-memory-persistence/.

Codex CLI (absorbed codex)

OpenAI's coding agent CLI. Use when the user asks for Codex specifically, or you want an OpenAI-model coding agent.

• One-shots: codex exec 'task' (needs pty=true + a git repo; mktemp -d && git init for scratch).
• Background long tasks: codex exec --full-auto 'task' with background=true, pty=true, monitor via process(poll|log), answer prompts via process(submit).
• Flags: --full-auto (sandboxed auto-approve) vs --yolo (no sandbox); codex review --base origin/main for PR reviews.
• Parallel issue fixing: git worktrees + one Codex per worktree, then gh pr create.
• Desktop App sessions: codex exec sessions do NOT appear in the Codex Desktop App. To get threads in the App, drive codex app-server JSON-RPC — see references/codex-app-server-ipc.md and the ready bridge at scripts/codex-app-server-bridge.py (usage: python3 scripts/codex-app-server-bridge.py "prompt" --cwd ~/wiki --auto-approve --out /tmp/answer.md).
• Full guide: references/codex-cli.md (flags, PR review batch, phased subagent pattern, rules).

OpenCode CLI (absorbed opencode)

Provider-agnostic open-source coding agent (works with OpenRouter/any provider).

• One-shots: opencode run 'task' — no PTY needed; attach files with -f file; --thinking shows reasoning; --model provider/model forces a model.
• Interactive sessions: opencode with background=true, pty=true, then process(submit) prompts, process(poll|log) monitoring. Exit with Ctrl+C (\x03) — /exit is NOT a valid command (opens an agent selector instead).
• Resume: opencode -c (last session) or opencode -s <id>; sessions listed via opencode session list; costs via opencode stats.
• PR review: opencode pr <number> or review in a temp clone.
• Full guide: references/opencode-cli.md (TUI keybindings, flags, pitfalls, verification smoke test).

Context Management

Long Claude Code sessions accumulate context that degrades output quality. See Context Window Optimization for:

• Threshold guide — 0-50% PEAK, 50-70% GOOD, 70-85% DEGRADING, 85%+ POOR
• Compression system — How Hermes dual compression works (agent + gateway hygiene)
• Recovery strategies — Proactive /compact, session checkpointing, fresh sessions
• Configuration — Tuning compression threshold, summary model, engine selection
• Emergency recovery — What to do when context is severely degraded