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

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

claude

claude "query"

claude -p "query"

cat file | claude -p "query"

claude -c

claude -r "id"

claude auth login

--console

--sso

claude auth status

--text

claude mcp add <name> -- <cmd>

claude mcp list

claude mcp remove <name>

claude agents

claude doctor

claude update

claude upgrade

claude remote-control

claude install [target]

claude setup-token

claude plugin

claude plugins

claude auto-mode

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

num_turns

total_cost_usd

subtype

success

error_max_turns

error_budget

Streaming JSON Output

For real-time token streaming, use

stream-json

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

attempt

max_retries

error

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

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

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

ANTHROPIC_API_KEY

To selectively load context in bare mode:

--append-system-prompt "text"

--append-system-prompt-file path

--settings <file-or-json>

--mcp-config <file-or-json>

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

-p, --print

-c, --continue

-r, --resume <id>

--fork-session

--session-id <uuid>

--no-session-persistence

--add-dir <paths...>

-w, --worktree [name]

.claude/worktrees/<name>

--tmux

--worktree

--ide

--chrome

--no-chrome

--from-pr [number]

--file <specs...>

file_id:relative_path

Model & Performance

--model <alias>

sonnet

opus

haiku

claude-sonnet-4-6

--effort <level>

low

medium

high

max

auto

--max-turns <n>

--max-budget-usd <n>

--fallback-model <model>

--betas <betas...>

Permission & Safety

--dangerously-skip-permissions

--allow-dangerously-skip-permissions

--permission-mode <mode>

default

acceptEdits

plan

auto

dontAsk

bypassPermissions

--allowedTools <tools...>

--disallowedTools <tools...>

--tools <tools...>

""

"default"

Output & Input Format

--output-format <fmt>

text

json

stream-json

--input-format <fmt>

text

stream-json

--json-schema <schema>

--verbose

--include-partial-messages

--replay-user-messages

System Prompt & Context

--append-system-prompt <text>

--append-system-prompt-file <path>

--system-prompt <text>

--system-prompt-file <path>

--bare

--agents '<json>'

--mcp-config <path>

--strict-mcp-config

--mcp-config

--settings <file-or-json>

--setting-sources <sources>

user

project

local

--plugin-dir <paths...>

--disable-slash-commands

Debugging

-d, --debug [filter]

"api,hooks"

"!1p,!file"

--debug-file <path>

Agent Teams

--teammate-mode <mode>

auto

in-process

tmux

--brief

SendUserMessage

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

#

# Always use 2-space indentation

Interactive Session: Slash Commands

Session & Context

/help

/compact [focus]

/compact focus on auth logic

/clear

/context

/cost

/resume

/rewind

/btw <question>

/status

/todos

/exit

Ctrl+D

Development & Review

/review

/security-review

/plan [description]

/loop [interval]

/batch

Configuration & Tools

/model [model]

/effort [level]

low

medium

high

max

auto

/init

/memory

/config

/permissions

/agents

/mcp

/add-dir

/usage

/voice

/release-notes

Custom Slash Commands

Create

.claude/commands/<name>.md

~/.claude/commands/<name>.md

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

Skills (Natural Language Invocation)

Unlike slash commands (manually invoked), skills in

.claude/skills/

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

Ctrl+C

Ctrl+D

Ctrl+R

Ctrl+B

Ctrl+V

Ctrl+O

Ctrl+G

Ctrl+X Ctrl+E

Esc Esc

Mode Toggles

Shift+Tab

Alt+P

Alt+T

Alt+O

Multiline Input

\

Enter

Shift+Enter

Ctrl+J

Input Prefixes

!

!npm test

!

@

@./src/api/

#

# Use 2-space indentation

/

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

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

--tmux=classic

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

# 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

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

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/

~/.claude/agents/

--agents

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

~/.claude/settings.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

UserPromptSubmit

PreToolUse

PostToolUse

Notification

Stop

SubagentStop

PreCompact

SessionStart

git status

Hook Environment Variables

CLAUDE_PROJECT_DIR

CLAUDE_FILE_PATHS

CLAUDE_TOOL_INPUT

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

-s user

~/.claude.json

-s local

.claude/settings.local.json

-s project

.claude/settings.json

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

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

• < 70% — Normal operation, full precision
• 70-85% — Precision starts dropping, consider

  /compact

• > 85% — Hallucination risk spikes significantly, use

  /compact

  or

  /clear

Environment Variables

ANTHROPIC_API_KEY

CLAUDE_CODE_EFFORT_LEVEL

low

medium

high

max

auto

MAX_THINKING_TOKENS

0

MAX_MCP_OUTPUT_TOKENS

50000

CLAUDE_CODE_NO_FLICKER=1

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

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

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