hermes-to-claude 0.1.0

package/DESIGN.md

@@ -0,0 +1,233 @@
+# H-Bridge (hbridge) Design
+
+Hermes Bridge — local HTTP bridge from Hermes Agent to Claude Code.
+
+## Architecture
+
+```
+npm install
+  ├─ preinstall: build → dist/hbridge.mjs + dist/statusline.mjs
+  ├─ install: npm deps
+  └─ postinstall: register statusLine + skill in ~/.claude configs
+
+/hbridge enable
+  └─ HTTP server on homePort(cwd)
+       ├─ GET  /health                   → {"status":"ok"}
+       ├─ POST /v1/task/create            → Bridge.createTask(prompt)
+       │                                    → new Session → spawn Claude
+       ├─ POST /v1/task/cancel             → Session.cancel()
+       ├─ POST /v1/task/permission         → Session.respondPermission()
+       ├─ GET  /v1/task/output?task_id=x   → Bridge.getTaskOutput(id)
+       ├─ GET  /v1/task?task_id=x          → Bridge.getTask(id)
+       └─ GET  /v1/task/output/stream?id=x → SSE streaming
+```
+
+## Session Pool
+
+Each task gets its own `Session` (one Claude Code child process). Sessions run in parallel up to `maxConcurrent` (default 3). If at capacity, tasks are queued in `_pendingQueue` and start when a slot opens.
+
+```
+Bridge.createTask(prompt)
+  ├─ _sessions.size < maxConcurrent
+  │   └─ new Session → spawn Claude → send prompt → onComplete → persist
+  └─ _sessions.size >= maxConcurrent
+      └─ _pendingQueue.push → _dequeueNext() when slot opens
+```
+
+## Session Lifecycle
+
+```
+Session.start()
+  ├─ spawn npx @anthropic-ai/claude-code --print ...
+  ├─ StdioTransport (stdin/stdout NDJSON)
+  ├─ send prompt (type: "user")
+  ├─ _onMessage() handles all NDJSON message types
+  │   ├─ stream_event → progressive text accumulation
+  │   ├─ assistant → content block parsing (text/tool_use/tool_result)
+  │   ├─ control_request/can_use_tool → permission pipeline
+  │   ├─ tool_progress → SSE forwarding
+  │   ├─ user → multi-turn auto-respond
+  │   └─ stop_reason / result → _finishTask() → persist + cleanup
+  └─ _cleanup() → kill child, close transport
+```
+
+## Permission Pipeline
+
+By default, when Claude wants to use a tool (Bash, Read, Write...), it sends a `can_use_tool` control_request. The Session blocks and emits an SSE `permission_request` event. Hermes must respond via `POST /v1/task/permission`.
+
+```
+Claude → {"type":"control_request","request":{"subtype":"can_use_tool","tool_name":"Bash",...}}
+  → Session._onMessage
+    → if permissionMode == "bypass": auto-allow (no SSE event)
+    → if permissionMode == "approve": block + emit permission_request SSE
+      → Hermes sees SSE → POST /v1/task/permission
+        → Session.respondPermission("allow"|"deny")
+          → control_response → Claude proceeds or stops
+```
+
+Modes (set per-task at creation):
+| `permission_mode` | Behavior |
+|---|---|
+| `"approve"` (default) | Hermes must approve each tool call |
+| `"bypass"` | Session auto-approves all tool calls |
+| `skip_permissions: true` | `--dangerously-skip-permissions` flag, Claude never asks |
+
+## API Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/health` | GET | No | Health check |
+| `/v1/task/create` | POST | Yes | Create a task + optional `permission_mode` + `skip_permissions` |
+| `/v1/task/cancel` | POST | Yes | Cancel a running or queued task |
+| `/v1/task/permission` | POST | Yes | `{"task_id","behavior","updatedInput?","message?"}` |
+| `/v1/task/output?task_id=x` | GET | Yes | Get task result (memory → disk fallback) |
+| `/v1/task/output/stream?task_id=x` | GET | Yes | SSE streaming (chunk, permission_request, done, error) |
+| `/v1/task?task_id=x` | GET | Yes | Get task status only |
+
+### SSE Streaming Events
+
+Connect to `/v1/task/output/stream?task_id=xxx`:
+
+```
+data: {"type":"connected","taskId":"task_xxx"}
+data: {"type":"chunk","text":"Fixing bug..."}
+data: {"type":"permission_request","task_id":"t1","tool_name":"Bash","input":{"command":"git status"}}
+data: {"type":"done","exitCode":0}
+```
+
+### Task Lifecycle Diagram
+
+```
+Hermes                          hbridge:<port>                    Session (Claude Code)
+  │                                │                                │
+  │  POST /v1/task/create          │                                │
+  │  {"prompt":"fix bug"}          │                                │
+  │──────────────────────────────▶│                                │
+  │  {"task_id":"task_xxx",       │  spawn Claude Code              │
+  │   "status":"created"}         │  stdin (NDJSON):                │
+  │◀──────────────────────────────│  {"type":"user",               │
+  │  (immediate, no wait)         │   "message":{"role":"user",    │
+  │                                │    "content":"fix bug"},       │
+  │                                │──────────────────────────────▶│
+  │                                │                                │  execute
+  │                                │  stdout (NDJSON):              │
+  │                                │  stream_event (progressive)    │
+  │                                │  SSE: chunk events             │
+  │                                │  result / stop_reason          │
+  │                                │◀──────────────────────────────│
+  │                                │  task persisted to disk        │
+  │                                │                                │
+  │  GET /v1/task/output?          │                                │
+  │    task_id=task_xxx            │                                │
+  │──────────────────────────────▶│                                │
+  │  {"retrieval_status":"success",│                                │
+  │   "task":{"status":"done",    │                                │
+  │    "result":"Fixed...",       │                                │
+  │    "exitCode":0,              │                                │
+  │    "usage":{...}}}            │                                │
+  │◀──────────────────────────────│                                │
+```
+
+## Task Result Format
+
+```json
+{
+  "retrieval_status": "success" | "pending",
+  "task": {
+    "id": "task_xxx",
+    "status": "done" | "failed" | "running",
+    "result": "Hello.",
+    "exitCode": 0,
+    "usage": {
+      "total_cost_usd": 0.01234,
+      "input_tokens": 150,
+      "output_tokens": 300,
+      "cache_creation_input_tokens": 10,
+      "cache_read_input_tokens": 20
+    }
+  }
+}
+```
+
+## Design Rationale: Key vs Port
+
+**Key is machine-global**, **port is per-directory**. This follows Claude Code's working-directory-centric model.
+
+Claude Code reads its context — `CLAUDE.md`, project skills, `.claude/settings.json` — from the **current working directory**. Each project has its own conventions, its own skills, its own CLAUDE.md. To serve the right context, hbridge must spawn Claude Code in the right directory.
+
+```
+/project-a/CLAUDE.md  →  hbridge :9200  →  Claude Code (cwd=/project-a)
+/project-b/CLAUDE.md  →  hbridge :9201  →  Claude Code (cwd=/project-b)
+```
+
+**Port per directory** (`9200 + MD5(cwd) % 600`) means:
+- Each project gets a stable, predictable port
+- You can run hbridge for multiple projects on the same machine without conflict
+- The port is deterministic — Hermes computes it from the directory path without asking the server
+
+**Key per machine** means:
+- Hermes only needs one credential per machine, not one per project
+- The key is random, generated once, persisted in `~/.hbridge_key`
+- Same auth works across all directories on the same host
+
+Key format: `hb_` + 8 base52 chars (≈ 45 bits entropy, `crypto.randomBytes(8)`, stored once).
+
+## Key & Port Derivation
+
+- **Port**: `9200 + (MD5(cwd)[0:2] % 600)` — range [9200, 9799], stable per directory
+- **Key**: `hb_` + 8 random base52 characters — generated once, stored in `~/.hbridge_key`. Same for all directories on one machine.
+
+## Task Persistence
+
+Completed tasks are saved to `~/.hbridge_tasks.jsonl` (JSONL, append-only, max 2000 entries). On server restart, tasks are loaded into memory. `getTaskOutput` checks session → memory cache → disk.
+
+## Files
+
+### Runtime (gitignored)
+| File | Purpose |
+|------|---------|
+| `~/.hbridge_state.json` | running/stopped flag + port + lastClientIP/lastActiveAt |
+| `~/.hbridge_tasks.jsonl` | Completed task records (JSONL, survive restart) |
+
+### Config (written by postinstall)
+| File | Purpose |
+|------|---------|
+| `~/.claude/settings.json` | StatusLine command (highest priority) |
+
+## StatusLine
+
+Claude Code polls ~3-5s:
+
+```
+▶️ hbridge: on | :<port>
+⏹️ hbridge: off
+```
+
+Liveness is determined by polling `127.0.0.1:<port>/health` — no state-file dependency.
+
+## Changelog
+
+### #51 — Multi-session + persistence
+- **Sequential queue busy-polls** ✅ Fixed
+  - Old: `createTask` polled `setInterval` until previous task finished
+  - New: Session pool with promise queue — no busy-polling
+- **Task timeout kills queue** ✅ Fixed (see #52)
+- **Persistence**: Completed tasks saved to `~/.hbridge_tasks.jsonl`, survive restart
+- **Session class**: One Claude Code child process per task
+- **Parallelism**: Up to 3 concurrent tasks (configurable via `maxConcurrent`)
+
+### #52 — Remove hard 5-min timeout
+- `TASK_TIMEOUT_MS` default changed from 300_000 to 0 (no timeout)
+- Timeout is now opt-in: pass `taskTimeoutMs` to Bridge/Session constructor
+
+### #53 — Home mode direct enable
+- Home mode (`HBRIDGE_HOME=1`) now calls `cmd_enable()` directly
+- No longer goes through `--stdio` MCP layer
+- `--stdio` removed — hbridge is HTTP-only
+
+### #54+ — Permission pipeline
+- `--dangerously-skip-permissions` replaced by Hermes-controlled permission pipeline
+- Default mode `"approve"`: every tool call waits for Hermes decision
+- `POST /v1/task/permission` for allow/deny/modify
+- SSE `permission_request` events for real-time Hermes notification
+- Task-level `permission_mode` and `skip_permissions` overrides

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xu Han
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# Hermes-Claude-Bridge (hbridge)
+
+**Hermes-Agent** controls multiple **Claude Code** instances via HTTP — one agent, many Claude workers. No Pro/Max subscription required.
+
+```
+📱 User ----HTTP----> 🤖 Hermes-Agent ----hbridge----> 🏭 Claude Code (deploy role)
+                            ├───hbridge───> 🔧 Claude Code (coding role)
+                            ├───hbridge───> 🧪 Claude Code (testing role)
+                            └───hbridge───> 🔬 Claude Code (building role)
+```
+
+---
+
+## 1. hbridge 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
+
+hbridge 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 |
+
+### Install
+
+```bash
+git clone https://github.com/xuhancn/hermes-to-claude.git
+cd hermes-claude-bridge
+npm install && npm run build
+```
+
+### Start in Claude Code
+
+After installation, enable hbridge from inside Claude Code:
+
+```
+/hbridge enable
+```
+
+This starts the HTTP server. The port is derived from the working directory (see Authentication and Port below). Check status at any time:
+
+```
+/hbridge status
+```
+
+### 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 hbridge:
+
+```bash
+export HBRIDGE_HOME=1       # environment variable — auto-starts hbridge
+```
+
+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.
+
+### 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 (`hb_` + 8 random base52 characters) is written to `~/.hbridge_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 hbridge via HTTP. Here is the complete API.
+
+### Security
+
+Like Claude Code CLI, hbridge 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:
+
+```bash
+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:
+
+```bash
+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 |
+
+### Health Check
+
+Verify the server is reachable — no authentication required:
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+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
+
+hbridge 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──▶ hbridge :<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:
+
+```bash
+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 `~/.hbridge_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:
+
+```jsonl
+{"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](DESIGN.md) | Architecture, protocol, session lifecycle, permission pipeline, API reference, changelog |
+| [docs/local-mode.md](docs/local-mode.md) | HBRIDGE_HOME auto-start mode |
+| [docs/spawn-mechanism.md](docs/spawn-mechanism.md) | Claude Code spawn protocol, NDJSON format |
+| [docs/mcp-spec.md](docs/mcp-spec.md) | MCP tool definitions (Claude Code integration) |
+
+---
+
+## License
+
+MIT
+
+Created by **Xu Han** — [github.com/xuhancn](https://github.com/xuhancn)

package/build.mjs

@@ -0,0 +1,35 @@
+import { execSync } from "child_process";
+import * as esbuild from 'esbuild'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SRC_DIR = path.resolve(__dirname, 'src')
+
+// Generate version from git
+const count = execSync("git rev-list --count HEAD", { encoding: "utf8" }).trim();
+const hash = execSync("git rev-parse --short HEAD", { encoding: "utf8" }).trim();
+const HBRIDGE_VERSION = `v${count}.0.${hash}`;
+console.log(`✓ version ${HBRIDGE_VERSION}`);
+
+// Build hbridge CLI
+await esbuild.build({
+  entryPoints: [path.join(SRC_DIR, 'hbridge', 'cli.mjs')],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  outfile: 'dist/hbridge.mjs',
+  external: ['zod', 'chalk', 'axios', '@anthropic-ai/sdk', 'qrcode', 'lodash-es', 'get-east-asian-width'],
+  define: {
+    'globalThis.HBRIDGE_VERSION': JSON.stringify(HBRIDGE_VERSION),
+  },
+});
+
+// Build statusline — pure Node.js, no external deps
+await esbuild.build({
+  entryPoints: [path.join(SRC_DIR, 'hbridge', 'statusline.mjs')],
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  outfile: 'dist/statusline.mjs',
+});