claude-code

# 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` |