claude-code

name claude-code description Delegate coding to Claude Code CLI (features, PRs). version 2.2.1 author Hermes Agent + Teknium license MIT platforms ["linux","macos","windows"] metadata {"hermes":{"tags":["Coding-Agent","Claude","Anthropic","Code-Review","Refactoring","PTY","Automation"],"related_skills":["codex","hermes-agent","opencode"]}} 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 . 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 | 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