Hermes-to-Claude (h2c)

English | 中文

Hermes-Agent controls multiple Claude Code instances via HTTP — one agent, many Claude workers. No Pro/Max subscription required.

📱 User ----HTTP----> 🤖 Hermes-Agent ----h2c----> 🏭 Claude Code (deploy role)
                            ├----h2c----> 🔧 Claude Code (coding role)
                            ├----h2c----> 🧪 Claude Code (testing role)
                            └----h2c----> 🔬 Claude Code (building role)

1. h2c Advantages

• No Pro/Max required — works with any Claude Code via stdio; no Anthropic subscription needed.
• One agent, many Claudes — one Hermes-Agent routes tasks to multiple Claude Code instances, each in its own project directory with its own CLAUDE.md and skills.
• Default-off, secure — zero ports open until you explicitly enable. Auth key protects all endpoints.
• Cross-platform — Windows / Linux / macOS. Single codebase.
• Local-only — no cloud, no external API. Fully offline.

2. For Human Users

Prepare

h2c requires Node.js ≥ 20. Install it for your platform:

| Platform | Command | |----------|---------| | Linux (Ubuntu/Debian) | sudo apt install nodejs npm | | macOS | brew install node | | Windows | winget install OpenJS.NodeJS or download from https://nodejs.org |

Installation

For End User, One command to install globally:

npm install -g hermes-to-claude

This makes the h2c command available everywhere on your system.

For Developer, For contributors who want to hack on h2c itself:

git clone https://github.com/xuhancn/hermes-to-claude.git
cd hermes-to-claude
npm install && npm run build

Start in Claude Code

After installation, enable h2c from inside Claude Code:

/h2c enable

This starts the HTTP server. The port is derived from the working directory (see Authentication and Port below). Check status at any time:

/h2c status

Stop the bridge at any time:

/h2c disable

disable reads the daemon's PID (recorded under ~/.h2c/pid.<port> when it was enabled) and kills the background process, releasing the port. No orphan left behind.

Orphan Auto-Exit

h2c runs as a background process launched from inside Claude Code. When Claude Code exits, h2c would otherwise be left as an orphan holding the port. To prevent this, h2c watches its own stdin — when the launching Claude Code exits, the pipe closes and h2c shuts itself down, releasing the port.

• Grace period: 360 seconds (6 minutes) — within this window h2c stays alive so Hermes-Agent can connect; once it elapses, orphan cleanup fires.
• Disable: set H2C_NO_AUTO_EXIT=1 to keep h2c running indefinitely (e.g. from a terminal).

Home Mode — For Headless Machines

When Hermes-Agent runs on a server with no display, no manual command is needed. Export the environment variable before starting h2c:

# Linux / macOS
H2C_HOME=1

# Windows (Command Prompt)
set H2C_HOME=1

# Windows (PowerShell)
$env:H2C_HOME = "1"

With Home mode active, the server listens on 127.0.0.1 only. Authentication is disabled — safe because only local processes can reach it. Hermes-Agent connects without managing keys.

Claude Code Binary Resilience

h2c spawns Claude Code per task via npx @anthropic-ai/claude-code. If Anthropic ships an incomplete release (the native binary in the npm tarball is a tiny placeholder stub — e.g. the 2.1.237 win32 package 404), the process would crash instantly with exit code 1. h2c now detects this before spawning and self-heals:

1. Detect — bin/claude[.exe] smaller than 4KB (the package's own stub size) = placeholder. Result cached ~30s.
2. Self-heal — re-runs the package's install.cjs with backoff retries (2s/4s).
3. Fallback — if the latest release is genuinely broken, installs the newest previous release that ships a complete binary and locks it (auto re-checks latest every 6h). No version pinning — h2c always follows the latest healthy release.

Optional environment variables:

| Variable | Meaning | |----------|---------| | H2C_CLAUDE_VERSION | Pin a specific Claude Code version (npx @anthropic-ai/claude-code@<version>). When set, h2c never falls back to another version — a broken pin surfaces a clear error. | | H2C_CLAUDE_NO_SELF_HEAL | Set to 1 to disable the detection/self-heal/fallback pipeline entirely. Use in regions where Claude Code cannot be (re)installed (e.g. a blocked npm registry) — otherwise the pipeline loops "reinstall → fail → reinstall" on every spawn. With this set, spawn goes straight to npx and a broken binary fails fast instead of looping. | | H2C_CACHE_DIR | Override the fallback install dir (default ~/.cache/hermes-to-claude/claude-code). |

Authentication and Port

The port is deterministic: MD5(cwd) → first 2 bytes → 9200 + (value % 600). Each project directory gets its own port. This is intentional:

• Each Claude Code instance runs in its own working directory
• Claude reads its own CLAUDE.md, skills, and project files from that directory
• Port = project — you always know which Claude you're talking to

The auth key (h2c_ + 8 random base52 characters) is written to ~/.h2c_key once and reused across all directories on the same machine. All HTTP endpoints (except /health) require HTTP Basic Auth with username bridge and the key as password.

3. For Hermes-Agent

Hermes-Agent discovers and controls h2c via HTTP. Here is the complete API.

Security

Like Claude Code CLI, h2c requires authentication for all mutating endpoints. But Hermes-Agent can simplify — either handle the auth flow itself, or bypass it entirely with skip_permissions for trusted workloads. Hermes-Agent must handle the same authentication and permission flow that human users would, or explicitly choose to bypass it.

Create a Task

Spawn a Claude Code session:

curl -X POST http://<host>:<port>/v1/task/create \
  -H "Authorization: Basic <base64(bridge:key)>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "fix the off-by-one bug in main.c"}'
# → {"task_id":"task_xxx","status":"created"}

To skip permission prompts for development workloads:

curl -X POST http://<host>:<port>/v1/task/create \
  -H "Authorization: Basic <base64(bridge:key)>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "...", "skip_permissions": true}'

| Optional field | Type | Description | |---------------|------|-------------| | permission_mode | "approve" (default) or "bypass" | Tool approval behavior | | skip_permissions | boolean | Skip all permission prompts | | cwd | string | Working directory for the Claude session | | sessionId | string | Reuse an existing Claude session |

Connect Hermes-Agent

Give Hermes-Agent the port and key. Add to ~/.hermes/config.yaml:

# Single h2c instance
h2c:
  project: my-app
  cwd: /path/to/project
  host: <ip>
  port: <port>
  key: h2c_XXXXXXXX

# Multiple machines (10 h2c instances):
h2c_farm:
  coding:
    host: 192.168.27.88
    port: 9761
    key: h2c_XXXXXXXX
    cwd: /home/xu/coding
  testing:
    host: 192.168.27.243
    port: 9709
    key: h2c_YYYYYYYY
    cwd: /home/xu/testing
  building:
    host: 192.168.27.225
    port: 9352
    key: h2c_ZZZZZZZZ
    cwd: /home/xu/building

Hermes-Agent reads the config and dispatches tasks to the right machine based on project. See the API reference below.

Health Check

Verify the server is reachable — no authentication required:

curl http://<host>:<port>/health
# → {"status":"ok"}

Check health after creating a task to confirm the bridge is running and ready.

Get Task Output

Poll until status is "done" or "failed". Long-running tasks (code generation, test suites) may take minutes.

curl "http://<host>:<port>/v1/task/output?task_id=task_xxx" \
  -H "Authorization: Basic <base64(bridge:key)>"
# → {"retrieval_status":"success","task":{"status":"done","result":"Fixed.","exitCode":0}}

Cancel a Task

curl -X POST http://<host>:<port>/v1/task/cancel \
  -H "Authorization: Basic <base64(bridge:key)>" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_xxx"}'

Permission Pipeline

h2c includes a full permission pipeline — just like CI tools. Hermes-Agent can decide per-task how to handle tool approvals:

| Mode | Behavior | |------|----------| | approve (default) | Claude sends control_request → Hermes decides allow/deny | | bypass | Claude sends request but doesn't block; Hermes can log for audit | | skip_permissions | --dangerously-skip-permissions — no requests, maximum speed |

For quick development tasks, use skip_permissions. For production workloads that need an audit trail, keep the default approve mode. Hermes-Agent can also respond with updatedInput to modify tool parameters before Claude executes them.

Architecture

Hermes ──HTTP──▶ h2c :<port> ──spawn──▶ Session (Claude Code)
  │                   │                              │
  │  Control Layer    │  server.mjs (HTTP routing)    │  reads CLAUDE.md
  │  (create/cancel/  │  bridge.mjs (session pool)    │  loads skills
  │   output/poll)    │  session.mjs (per-task proc)  │  edits files
  │                   │                              │
  │  Transport Layer  │  StdioTransport               │
  │  (SSE streaming)  │  (NDJSON stdin/stdout pipe)   │  Claude stdout
  │                   │                              │
  └─ poll or SSE ◀────┴─ task output (status/result) ─┘

Hermes-Agent dispatches tasks through two layers:

• Control Layer: HTTP endpoints for task lifecycle — create, cancel, poll for results, health. This is what Sections 3.1–3.5 describe.
• Transport Layer: Streaming, real-time progress, and persistent transcript via SSE and NDJSON. This is described below.

Claude Code loads project-specific CLAUDE.md and skills from the working directory as a per-task child process. Each session is isolated.

Transport Layer

Beyond polling getTaskOutput, Hermes-Agent can receive real-time streaming via Server-Sent Events (SSE) and read the raw Claude Code NDJSON transcript:

SSE Streaming

Subscribe to a task's output stream to receive events as they happen — no polling needed:

curl -N "http://<host>:<port>/v1/task/output/stream?task_id=task_xxx" \
  -H "Authorization: Basic <base64(bridge:key)>"
# event: chunk
# data: {"task_id":"task_xxx","chunk":"Fixing the off-by-one...\n"}
#
# event: done
# data: {"task_id":"task_xxx","status":"done","exitCode":0}

Event types pushed over SSE:

| Event | Description | |-------|-------------| | chunk | Incremental text output from Claude Code | | status | Task status change (running → done / failed) | | tool_progress | Tool execution progress (tool name + elapsed time) | | permission_request | Claude requests tool approval (in approve mode) |

NDJSON Transcript

The raw Claude Code stdout is saved to ~/.h2c_transcript.jsonl. Each line is a complete NDJSON message from Claude Code — assistant messages, stream_event deltas, tool_use blocks, and result messages with usage data:

{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"Fixing"}}}
{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":" the"}}}
{"type":"assistant","message":{"content":[{"type":"text","text":"Fixed the off-by-one error."}]}}
{"type":"result","subtype":"success","result":"...","usage":{"input_tokens":120,"output_tokens":45}}

Hermes-Agent can tail this file for full Claude Code session history, or consume the SSE stream for live updates. The transport layer ensures no output is lost — even if the HTTP connection drops, the transcript file preserves every message.

Document References

| Document | Contents | |----------|----------| | DESIGN.md | Architecture, protocol, session lifecycle, permission pipeline, API reference, changelog | | docs/local-mode.md | H2C_HOME auto-start mode | | docs/spawn-mechanism.md | Claude Code spawn protocol, NDJSON format | | docs/mcp-spec.md | MCP tool definitions (Claude Code integration) |

License

MIT

Created by Xu Han — github.com/xuhancn