prose-contracts/deliverables/scot-hermes-playbook/research/04-claude-code-bridge.md

04 — The Claude Code Bridge: Running Hermes WITH Claude Code

Prepared: 2026-09-11. Scot already runs both tools. This file documents the proven integration patterns, citing the installed skills on this host (paths under /home/hermes/.hermes/skills/) and official docs.

Pattern 0 — Import (do this first)

hermes import-agent claude-code [VERIFIED-LIVE] maps CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills, and memories into Hermes equivalents. It always shows a preview, never imports credentials. hermes sessions import [VERIFIED-LIVE] pulls in old Claude Code conversations. After import, Hermes "knows" the projects — the context gap disappears on day one.

Pattern 1 — Hermes as orchestrator, Claude Code as worker

Source: installed skill autonomous-ai-agents/delegate-coding-agent (v1.0.0) + its reference references/claude-code.md (v2.2.1) [V-FILE]. The skill is an official Hermes skill authored for exactly this.

Two orchestration modes (verbatim from the skill):

• Print mode (preferred): claude -p '<task>' --allowedTools 'Read,Edit' --max-turns 10 — one-shot, no dialogs, structured JSON output with session_id, num_turns, total_cost_usd. Ask Hermes: "delegate this coding task to Claude Code in print mode."
• Interactive PTY via tmux: multi-turn sessions — Hermes starts tmux new-session, sends prompts with send-keys, monitors with capture-pane. For iterative refactor → review → fix cycles.

Cross-agent review loop (also from the skill):

git diff main...feature | claude -p 'Review this diff for bugs and security issues.' --max-turns 1

Hermes runs this, reads the output, and fixes findings itself — Claude Code becomes a reviewer Hermes coordinates.

Safety rails the skill prescribes: explicit workdir, clean git status before launch, narrow task prompts, git diff review, targeted tests before committing.

Pattern 2 — Parallel workstreams + neutral merge reconciliation

Source: installed skill autonomous-ai-agents/merge-reconciler [V-FILE]. When Hermes and Claude Code (or two Hermes workers) both edit the same repo and collide:

• Do NOT let either agent resolve the conflict — both are biased toward their own side.
• Spawn a neutral third agent with the merge-reconciler skill; it classifies every conflicted hunk (disjoint-intent / same-question-different-answer / superseded), resolves under an impartiality contract (touch only conflict markers, surface every design call), verifies with build/tests, and hands back a summary naming every hunk decision.
• Kanban-native shape: a reconciliation card assigned to a third profile with both workers' cards as parents — parent links carry both sides' completion summaries into the reconciler's context automatically.

Pattern 3 — Hermes as MCP server (Claude Code gets Hermes tools)

hermes mcp serve [VERIFIED-LIVE] runs Hermes as an MCP server exposing its conversations and capabilities. Claude Code supports MCP clients (claude mcp add), so Claude Code can consume Hermes as a tool provider — persistent memory, skills, cron — the surfaces Claude Code lacks. This is the reverse-bridge only Hermes can offer. Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

Pattern 4 — Import legacy sessions for continuity

hermes sessions import [VERIFIED-LIVE] imports a Claude Code session into the Hermes store; from then on hermes --resume <id> / hermes sessions browse treat it as native history. Use when mid-project: the new agent picks up exactly where Claude Code left off.

Pattern 5 — Desktop GUI automation either side can use

Source: installed skill autonomous-ai-agents/computer-use (v2.0.0) [V-FILE]. hermes computer-use install sets up cua-driver; the computer_use toolset drives native desktop apps background-first (never steals focus/cursor), any-model, cross-platform. Relevant to the bridge because Claude Code has no desktop automation — if a task needs Figma/Excel/native apps, that part routes to Hermes while the code routes to Claude Code. Cmd: hermes computer-use doctor for health checks.

Pattern 6 — The import-agent philosophy in one line

Claude Code holds repo context in CLAUDE.md; Hermes holds it in AGENTS.md + memory + skills. hermes import-agent claude-code translates the first; the learning loop ("save this as a skill") rebuilds the rest automatically the more Scot uses Hermes.

Reference paths (for the writer)

• /home/hermes/.hermes/skills/autonomous-ai-agents/delegate-coding-agent/SKILL.md and references/claude-code.md
• /home/hermes/.hermes/skills/autonomous-ai-agents/merge-reconciler/SKILL.md
• /home/hermes/.hermes/skills/autonomous-ai-agents/computer-use/SKILL.md
• hermes import-agent --help raw output in cli-help-dump.txt (lines 554-577)