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.
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)
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:
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)
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, 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
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)
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:
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.
--dangerously-skip-permissions dialog defaults to "No, exit" — you must send Down then Enter to accept. Print mode (-p) skips this entirely.
--max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much. Setting lower will error immediately.
--max-turns is print-mode only — ignored in interactive sessions.
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.
Session resumption requires same directory — --continue finds the most recent session for the current working directory.
--json-schema needs enough --max-turns — Claude must read files before producing structured output, which takes multiple turns.
Trust dialog only appears once per directory — first-time only, then cached.
Background tmux sessions persist — always clean up with tmux kill-session -t <name> when done.
Slash commands (like /commit) only work in interactive mode — in -p mode, describe the task in natural language instead.
--bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.
Context degradation is real — AI output quality measurably degrades above 70% context window usage. Monitor with /context and proactively /compact.
Rules for Hermes Agents
Prefer print mode (-p) for single tasks — cleaner, no dialog handling, structured output
Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI
Always set workdir — keep Claude focused on the right project directory
Set --max-turns in print mode — prevents infinite loops and runaway costs
Monitor tmux sessions — use tmux capture-pane -t <session> -p -S -50 to check progress
Look for the ❯ prompt — indicates Claude is waiting for input (done or asking a question)
Clean up tmux sessions — kill them when done to avoid resource leaks
Report results to user — after completion, summarize what Claude did and what changed
Don't kill slow sessions — Claude may be doing multi-step work; check progress instead
Use --allowedTools — restrict capabilities to what the task actually needs
📋 检查点设计
检查点 1：环境准备验证
【前置检查】执行任务前必须验证：
# 检查Claude Code是否安装
which claude && claude --version
# 检查认证状态
claude auth status --text
# 检查工作目录
test -d "/path/to/project" && echo "✓ 目录存在" || echo "✗ 目录不存在"
验证清单：
Claude Code已安装（v2.x+）
认证状态有效（Pro/Max或API Key）
工作目录存在且可访问
tmux已安装（如需交互模式）
检查点 2：Print Mode执行验证
【执行中监控】Print Mode关键指标：
# 执行并捕获退出码
claude -p "任务描述" --max-turns 10 --allowedTools "Read,Edit"
exit_code=$?
# 检查退出码
if [ $exit_code -eq 0 ]; then
echo "✓ 任务成功完成"
else
echo "✗ 任务失败，退出码: $exit_code"
fi
Error: Not authenticated. Run 'claude auth login' first.
恢复流程：
# 1. 检查认证状态
claude auth status
# 2. 重新认证
claude auth login # 浏览器OAuth
# 或
claude auth login --console # API Key
# 3. 验证认证成功
claude auth status --text | grep "Logged in"
异常类型2：工作目录不存在
症状：
Error: Directory '/path/to/project' does not exist
恢复流程：
# 1. 验证目录路径
pwd
ls -la /path/to/project
# 2. 创建目录（如需要）
mkdir -p /path/to/project
# 3. 重新执行任务
cd /path/to/project && claude -p "任务描述"
