---
name: hermes-claude-bridge
description: Design, build, and evaluate bridges between Hermes (on the VPS) and Claude (Desktop / Claude Code on Connie), with the Syncthing-synced Obsidian vault as the shared memory layer. Trigger when the user asks to "connect Hermes to Claude", "let the agents see each other's work", "share context between agents", evaluate a third-party multi-agent/AI-stack plan (e.g. a pasted architecture doc), or set up MCP between Hermes and Claude. Covers the verified capability matrix (what hermes mcp serve actually is in 0.19.0, what Claude Desktop remote MCP requires), the vault-bridge pattern that works today with zero new software, the MCP-bridge pattern that needs a transport shim, and a checklist for vetting pasted third-party plans against this environment.
---

# Hermes ↔ Claude Bridge

Rob's stated goal (2026-08-06): "connect you to Claude and vice versa so you both can see what the other is doing... and Obsidian can store it all for the future." This is a recurring project class — expect it to resume across sessions. This skill holds the verified facts and the decision framework so each session doesn't re-derive them.

## The two-layer model (get this straight first)

There are TWO independent bridges, with very different cost/benefit:

| Layer | What it gives | Cost | Status |
|---|---|---|---|
| **Vault bridge** (shared memory) | Both agents read/write the same Obsidian vault; each sees the other's distilled notes within seconds | ~Zero — Syncthing + vault already live | **Available today** |
| **MCP bridge** (live delegation) | Claude calls Hermes as a tool mid-conversation ("Hermes, run this web search") | Real project: transport shim + auth + exposure | **Built 2026-08-06** — direct vault MCP server (`hermes-vault-mcp.service`, port 9123) behind nginx + OAuth 2.1/PKCE shim; Claude Desktop connector live. Full recipe: `operating-hermes-gateway` → `references/remote-mcp-claude-desktop.md`. |

**Do the vault bridge first.** It delivers ~80% of the "both agents see the same context" value with no new software. MCP is the remaining 20% (live delegation) at 95% of the effort.

## Verified capability matrix (VPS, hermes 0.19.0 pip, verified 2026-08-06)

- `hermes mcp serve` **exists** in 0.19.0 — `hermes mcp --help` lists it: "Run Hermes as an MCP server (expose conversations to other agents)". It exposes *conversations*, i.e. another agent talks TO a Hermes session.
- Its flags are only `-v` and `--accept-hooks` — **no `--port`, no `--host`, no HTTP/SSE options**. Transport is stdio. There is no built-in way to make it a network service.
- No `vault_path` / `obsidian` keys exist anywhere in the 0.19.0 config schema or source — any plan that says "set `memory.vault_path` in Hermes config" is fabricated. Vault integration is by convention (read/write the synced folder), not config.
- MCP *client* side also exists: `hermes mcp add <name> --url <endpoint>` / `--command` — Hermes can consume MCP servers (none configured as of 2026-08-06; `hermes mcp list` empty).
- Claude Desktop remote MCP (Settings → Connectors) requires a **network-reachable HTTPS endpoint with OAuth 2.1 or Bearer auth**. It cannot attach to a stdio server on a remote host directly. So "paste your VPS URL into Connectors" only works AFTER a stdio→HTTP shim + auth + TLS exist.
- Web search was down this session (Nous Portal out of Firecrawl credits) — verify Claude Desktop's current remote-MCP auth requirements against Anthropic docs when the project resumes; do not rely on this skill's paraphrase for the final build.

## What already exists on this VPS (don't rebuild)

- Syncthing `syncthing@root` active; folders: `hermes-vault` (`/root/.hermes/vault`, 3 devices: VPS/Connie/Surface), `hermes-shared` (`/root/.hermes/shared`, 2 devices), `claude-code-sessions` (`/root/.hermes/mirrors/claude-code-sessions`, **receive-only** mirror of Connie's `C:\Users\Rob\.claude\projects` — Hermes can already read Claude Code's raw transcripts).
- Vault structure on VPS: `01_Job_Seeker/`, `02_Pipeline_Layer/`, `03_Real_Results_Front_Desk/`, `04_OriginatorOS/`, `Agentic OS/`, `Hermes-GHL OS/`, `Jarvis/`, `Memories/`, `Personal/`.
- Obsidian on Connie opens the synced replica; writes flow back in seconds.

## The vault-bridge pattern (build this first)

Asynchronous, file-based, human-auditable — everything lands in Obsidian where Rob can see it:

1. **Hermes → Claude**: agent writes digest notes to `/root/.hermes/vault/Hermes Activity/` (what was done, decisions, artifacts). Syncthing pushes to Connie; Claude (Code or Desktop with file access) reads them as ordinary markdown.
2. **Claude → Hermes**: Claude writes to a `Claude Activity/` folder in the same vault; Syncthing pushes to VPS; Hermes reads.
3. **Raw Claude Code transcripts**: already mirrored receive-only to `/root/.hermes/mirrors/claude-code-sessions/` — readable for deep-dives, but keep raw transcripts OUT of the vault (not curated notes).
4. Convention beats config: there is no auto-capture hook in 0.19.0. Digests are written when asked, or via a cron job if Rob wants automation. Don't promise "automatic" without building the cron.

## Vault-based Ideas + Projects system (collaboration, not just session digests)

The vault bridge works for session digests, but ideas and projects need a richer structure. Rob's pain point: he bounces an idea off Hermes, then Claude, then Perplexity — each in their own chat — and the synthesis dies when he gets busy. The fix is a structured Ideas/Projects folder system in the vault that both agents read and write.

**Full vault collaboration layout:**

```
/root/.hermes/vault/
├── Ideas/
│   ├── _README.md              ← rules: naming, status values, when to archive
│   ├── Templates/
│   │   └── new-idea.md          ← copy-paste template for every new idea
│   ├── Active/                 ← brainstorming → active
│   │   └── project-name/
│   │       ├── context.md      ← Rob's original idea + source notes
│   │       ├── hermes.md       ← Hermes appends analysis here
│   │       ├── claude.md       ← Claude appends analysis here
│   │       ├── research.md     ← Perplexity/web research
│   │       ├── decisions.md    ← what was decided, by whom, when
│   │       └── next-steps.md   ← action items, owners, deadlines
│   └── Archived/               ← done, dead, or superseded
├── Projects/
│   ├── _README.md              ← execution work conventions
│   ├── Templates/
│   ├── Active/                 ← execution-stage work
│   │   └── project-name/
│   │       ├── README.md       ← overview, status, owner, timeline, budget, milestones
│   │       ├── tasks.md        ← task list: what, status, owner, dependencies, blockers
│   │       ├── costs.md        ← budget vs actual, by category
│   │       ├── blockers.md     ← what's stuck, who's unblocking it, ETA
│   │       ├── decisions.md    ← key decisions, rationale, date, who decided
│   │       └── log.md          ← appended progress notes (date-stamped)
│   └── Archived/               ← shipped, killed, or superseded
├── Reference/                  ← config answers, flags, gotchas (survives project deletion)
│   ├── _README.md
│   └── [topic].md               ← one file per topic, append-only, dated entries
├── Hermes Activity/             ← Hermes session digests (existing)
├── Claude Activity/             ← Claude's notes (existing)
└── ...                          ← existing vault content
```

**Status values for Ideas:** `brainstorming → active → paused → done → dead`
**Status values for Projects:** `brainstorming → active → paused → done → dead`

**Conventions:**
- Folder name = slug (lowercase, hyphens)
- Each agent appends to its own file (`hermes.md`, `claude.md`) — don't overwrite, add dated sections
- Rob makes decisions; agents record them in `decisions.md`
- Archive when shipped, abandoned, or superseded — move to `Archived/` with a one-line note
- Reference folder: one file per topic (e.g., `playwright-vps.md`, `claude-code-cli.md`, `ghl-funnel-gotchas.md`). Append dated entries. This is for config answers, flags, workarounds — the stuff you'd search for at 2am.

**Write-back requirements (the part that doesn't happen automatically):**
- Hermes: no auto-digest in 0.19.0. Append to `hermes.md` when asked, or via a post-session convention
- Claude: must have a standing instruction in each relevant Cowork Project to write analysis to the project's `claude.md` or `decisions.md`. Without this, the Claude side of the loop stays empty
- Raw Claude Code transcripts: already mirrored to `/root/.hermes/mirrors/claude-code-sessions/` — usable for deep dives, but keep raw transcripts OUT of the vault

**Standing instruction text for Claude Cowork projects (updated 2026-08-15):**

> "When this project relates to an active idea or project in the vault (`/root/.hermes/vault/Ideas/Active/` or `/root/.hermes/vault/Projects/Active/`), append your session analysis to the relevant `claude.md` or `decisions.md` file using the naming convention in that folder's README. If no active project matches, write a brief summary to `Claude Activity/` with the project name in the filename. If you solve a config problem or discover a non-obvious flag/workaround, also write it to `/root/.hermes/vault/Reference/[topic].md`."

**Motion canvases (added 2026-08-15):** for each active product/motion, create a canvas at `vault/Projects/Active/motion-canvases/[motion-name].md` that answers: (1) what we sell vs what we deliver, (2) target vertical, (3) ICP, (4) list compilation method, (5) the hook, (6) outreach sequence, (7) conversion mechanism, (8) fulfillment, (9) kill criteria, (10) current status, (11) next steps. This exposes where a motion stalled and what to build next.

**Why this matters:** the vault is now the shared project system for both agents. Ideas brainstorm here, Projects execute here, Reference lives here. Syncthing syncs to Connie + Obsidian. Both agents read and write the same files. The standing instruction closes the Claude write-back loop.

## ⚠️ Set expectations correctly: the bridge is async, NOT live visibility (2026-08-06)

After the bridge was built, Rob asked Hermes to "list my Cowork projects" and was surprised Hermes couldn't — he thought "the whole reason we setup the Claude to Hermes MCP was so you could know what Claude is working on." **The vault bridge does NOT provide that.** It only surfaces what Claude actively writes into `Claude Activity/` (which was empty except its README a day after setup). When this bridge (or any shared-context setup) is delivered, state the boundary explicitly at handoff:

- "I can see what Claude *chooses to write down*, not what Claude *is doing*."
- "If Claude doesn't write a note, I have zero visibility — the folder will be empty."
- "To get a Cowork project summary into my context, ask Claude in that project: 'Write a summary of this project to the Claude Activity folder in the vault.'"

Claude has no standing instruction to write digests (Rob adds "check Hermes Activity/" to project instructions manually, but the write direction has no equivalent automation). If Rob wants Claude to reliably report, options: add a write-back instruction to each Cowork project's instructions, or accept the manual prompt pattern.

## Verified delegation stack (2026-08-15)

Both Playwright and Claude Code CLI are now installed and verified on the VPS.

| Capability | Hermes | Claude Desktop (Connie) | Bridge |
|---|---|---|---|
| Web search / scrape (raw) | ✅ | ✅ | — |
| Live browser / Chrome Extension | ❌ | ✅ | ❌ **Not bridged** |
| Browser automation (scraping, screenshots, form fills) | ✅ **Playwright 1.62** | — | — |
| Reasoning delegation (Claude API) | ✅ **Claude Code 2.1** | — | — |

**Routing logic:**
```
Need Chrome Extension / live browser with logged-in session?
  ├─ YES → Manual Connie execution (Claude Desktop with Extension)
  └─ NO  → Hermes handles it (web_search, web_extract, Playwright)

Need complex reasoning, copy, strategy, or code generation?
  ├─ YES → Hermes shells out to Claude Code CLI (claude -p)
  └─ NO  → Hermes handles it directly
```

**Playwright (done 2026-08-15)**
- Installed: `pip install playwright` → 1.62.0
- Chromium: `PLAYWRIGHT_BROWSERS_PATH=/root/.hermes/playwright-browsers playwright install chromium` → Chrome Headless Shell 151
- Read-only root fix: `/root/.cache/ms-playwright` fails with `EROFS`; override to writable `/root/.hermes/playwright-browsers`
- System libs needed: `libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2t64`
- Detection mitigation: realistic UA (Windows Chrome), `page.wait_for_timeout(2000)` after nav, rotate delays 1.5–3s
- Full reference: `vault/Reference/playwright-vps.md`

**Claude Code CLI (done 2026-08-15)**
- Installed: `npm install -g @anthropic-ai/claude-code` → v2.1.197 to `/root/.hermes/npm-global/` (read-only root required custom npm prefix + `HOME=/tmp/npm-home`)
- Auth: Anthropic API key via `ANTHROPIC_API_KEY` env var. Claude Code 2.1 does NOT accept OpenRouter keys.
- Non-interactive usage: `claude -p "<task>" --output-format json` returns structured envelope (type, result, duration, usage)
- Task-contract pattern: pipe JSON task packet in, get JSON result back with required fields. Verified cost: ~$0.05/task (Haiku routes + Opus reasons).
- What it's NOT: headless, no Chrome Extension, no Connie desktop session, stateless per call
- Full reference: `vault/Reference/claude-code-cli.md`

**Hermes as orchestrator — the pattern:**
1. Hermes receives event (new GHL lead, scheduled task, cron trigger)
2. Hermes normalizes context (business name, city, services, URL, prior outreach)
3. Hermes delegates: Playwright scrapes websites → Claude Code CLI analyzes → both return structured JSON
4. Hermes validates: check schema, length, missing fields, prohibited claims, confidence threshold
5. Human gate for outbound messaging, account changes, publishing, payment work
6. Hermes executes and logs: update GHL, create task, queue email/SMS, save artifact

**Third-party plan vetting — preferred output format:**

When Rob pastes an architecture doc, present findings as a three-column table:

| Claim | Verdict | Detail |
|---|---|---|
| "... | ✅ Right / ⚠️ Partially / ❌ Wrong / ❓ Unverified | ... |

Then a short summary of the architectural fit and what's actually needed to implement the useful parts. Rob valued this format — it lets him decide per-claim rather than accepting or rejecting the whole doc.

**Red flags to watch for in pasted plans:**
- "Sync the vault via Dropbox/iCloud" — we already have Syncthing
- Mac-only tooling (OMI, etc.) — Rob is on Windows
- Fabricated config keys ("set `memory.vault_path` in Hermes config" — grep the venv before repeating)
- Hand-waved auth ("add the MCP URL to Connectors") — skips the stdio→HTTPS shim
- "Zero cost" claims — vault layer is free; MCP layer has real build cost

## Cowork project inventory + vault folder mapping (established 2026-08-06 — DONE, don't redo)

Rob's 8 active Cowork projects (Anthropic's "How to use Claude" example excluded; "Obsidian Vault -Hermes-GHL OS" was an empty duplicate project Rob deleted 2026-08-07). Each has a dedicated vault folder attached in Cowork:

| Cowork Project | Vault folder |
|---|---|
| New RRR Website Build | `New RRR Website Build/` |
| LinkedIn Posting System | `LinkedIn Posting System/` |
| YouTube Training Videos | `YouTube Training Videos/` |
| Ad Hoc Rob Clone Video Project | `Ad Hoc Rob Clone Video Project/` |
| RRR Blog Posts & Case Studies | `RRR Blog Posts & Case Studies/` |
| Rob AI Avatar Videos | `Rob AI Avatar Videos/` |
| GHL OS - Hermes Managed | `GHL OS - Hermes Managed/` |
| Local Service Business - Market Research | `Local Service Business - Market Research/` |

**Naming-collision pitfall (bit us 2026-08-07):** content for the GHL OS project had been written to a THIRD folder, `Hermes-GHL OS/` (no prefix), while the Cowork project pointed at an empty `Obsidian Vault - Hermes-GHL OS/`. Three near-identical names, content in the one nobody attached. Fix was: move files into `GHL OS - Hermes Managed/`, delete both empty shells. When a project folder is unexpectedly empty, search the vault for name variants before concluding content was lost.

**Per-project Cowork Instructions were authored for all 8 projects (2026-08-06/07).** Each project has a custom Instructions block: universal header (write to attached folder only, `YYYY-MM-DD_description.md` naming, TL;DR-first, no secrets) + project-type directives (RRR vocabulary rules, LinkedIn CTA-above-link, YouTube transcript/credibility workflow, blog AEO structure + rob-writing-voice, GHL OS segment/pricing constraints). Two projects had PRE-EXISTING detailed instruction sets (YouTube transcript workflow, RRR Blog AEO rules) — merge pattern is universal-header-on-top, existing-rules-unchanged-below. Before drafting Instructions for any project, ALWAYS ask Rob what's already there — clobbering an existing set loses workflow detail.

Plus `Brand Context/` — merged from the old Cowork workspace's CONTEXT/ (about-me, brand-voice, working-style, global-instructions, onboarding-checklist, security-posture). Each project folder has a `_README.md` stating the bridge convention (Claude writes `YYYY-MM-DD_topic.md` + `_project_summary_YYYY-MM-DD.md`; no secrets).

**The old `Cowork/` workspace was merged into the vault and deleted (2026-08-06).** It lived at `C:\Users\Rob\OneDrive\Microsoft Copilot Chat Files\Desktop\Cowork` — a structured agency workspace (CONTEXT/PROJECTS/TEMPLATES/OUTPUTS + README rules, running since 2026-05) that landed in OneDrive because it was the default save path, NOT because Copilot owned it. Rob found it while hunting "why is Notion/Copilot running." If Copilot connect errors from that path resurface: the folder is deleted, errors should stop; content lives in the vault. Deleting needed him to close Notion/Claude Desktop first ("open in another program" lock).

Lessons from the inventory session:
- **Don't trust the Cowork dashboard's folder tags as the attachment record** — "LinkedIn Posting System" showed no folder tag but WAS attached; attach state is only reliable on the project detail screen. When counting "which projects have folders," ask him to check each project, don't infer from card footers.
- **claude.ai/space/<uuid> URLs are auth-walled** — Hermes cannot read them (hCaptcha + login page only). Asking Rob to paste project URLs is a dead end; ask for project NAMES or a dashboard screenshot instead.
- **Folder attach ≠ content migration**: attaching a vault folder gives Cowork a home for NEW files; project name/instructions/memory/chat history stay locked inside Claude Desktop. To get history out, Rob asks Claude in each project: "Write a comprehensive summary of all work to date... save as _project_summary_<date>.md in the attached folder."
- **Rob's workspace instincts are good — inspect before recommending a delete.** The OneDrive path looked like Copilot junk; it was his real system. When a mystery folder shows up, enumerate contents and read any README before proposing cleanup.
- **Cowork folder attachments are fragile and path-cached.** (a) Folder selections can be WIPED by a full Claude Desktop quit (tray-level) — after any "close everything and reopen," expect to re-attach all project folders. (b) If a project had a folder attached in the past, Cowork may silently write new files to the STALE cached path even while the project UI shows "no folder picked" — the tell is a summary that "saved" but didn't land in the vault; search the old path before re-running. (c) Rob may have multiple similarly-named project folders on disk (`Business_Projects\Project - X` vs vault `X`); after any relocation, verify the attachment shows the vault path AND that a test-write lands there.
- **Notion opens .md files as read-only previews with an "Import to Notion" button** — if Rob says "Notion got running," that's why: Windows file association, not a sync. The file is still on local disk; close Notion and use File Explorer for moves.

## Claude Cowork projects — storage reality (researched 2026-08-06)

Cowork = the agentic mode in Claude Desktop (paid plans, Mac+Windows). Projects = local workspaces with own folder, instructions, scheduled tasks, project-scoped memory. **Desktop-only, no cloud sync, no API.** Verified storage locations:

| Data | Windows | Mac |
|---|---|---|
| Project workspaces (default) | `C:\Users\<user>\Documents\Claude\Projects\` | `~/Documents/Claude/` |
| Artifacts | `...\Documents\Claude\Artifacts\` | `~/Documents/Claude/Artifacts/` |
| Scheduled tasks | `...\Documents\Claude\Scheduled\` | `~/Documents/Claude/Scheduled/` |
| Session outputs (ephemeral, may be cleaned between sessions) | `%APPDATA%\Claude\local-agent-mode-sessions\...\outputs` | `~/Library/Application Support/Claude/local-agent-mode-sessions/...` |

**Project metadata (names, instructions, memory, linked folders) is NOT readable on disk** — internal to Claude Desktop (SQLite/Electron storage), no documented path. Multiple GitHub issues confirm no config key exists for even a default workspace folder. So: Hermes can NEVER enumerate Rob's Cowork projects from the VPS. The only visibility paths are (a) the async vault bridge above, (b) syncing a Cowork project *folder* via Syncthing — which gets the files but not the project name/instructions/memory.

## The MCP-bridge pattern (the real project, when Rob green-lights)

`hermes mcp serve` is stdio-only, so remote use needs, in order:

1. A **stdio→HTTP/SSE shim** in front of `hermes mcp serve` (custom code or a gateway tool — evaluate options at build time).
2. **TLS + auth**: reuse the existing nginx 443 / robblake.cloud Let's Encrypt setup as reverse proxy, with a Bearer token; OR Cloudflare Tunnel (free tier, no inbound ports). nginx matches Rob's SSOT/no-new-service bias.
3. Claude Desktop → Settings → Connectors → add the HTTPS endpoint with the token.
4. Scope exposure carefully: `hermes mcp serve` exposes conversations, which means Claude can drive a Hermes session — treat the token as root-equivalent and keep it out of synced folders (see syncthing-folder-sync credential preflight).

## Vetting pasted third-party plans (Rob brings these — expect more)

When Rob pastes an architecture doc from a newsletter/creator, evaluate against THIS environment before adopting anything. Red flags found in the 2026-08-06 doc (a Julian-Goldie-style "agentic OS" recipe):

- **"Sync the vault via Dropbox/iCloud"** — inferior to the already-live Syncthing setup (third-party cloud, slower, unnecessary). Wrong default for this user.
- **"OMI for auto-capture on your Mac"** — Rob is on Windows (Connie, Surface). Mac-only tooling is a dead end; flag platform mismatches immediately.
- **"Set `memory.vault_path` in Hermes config"** — fabricated config key (verified absent from 0.19.0 source). Grep the venv before repeating ANY claimed config key: `grep -rn -iE '<key>' /root/.hermes/venv/lib/python3.12/site-packages/hermes_cli/`.
- **"Add the MCP URL to Claude Desktop Connectors"** — hand-waves the stdio→HTTPS+auth gap. The real work is the shim.
- **"Cowork orchestration"** — the 2026-08-06 doc's usage was aspirational hand-waving, but NOTE: "Claude Cowork" has since shipped as a real product surface (agentic mode in Claude Desktop, with Projects). Distinguish real-Cowork (desktop app feature, verified above) from a pasted doc's vague "orchestration" claims.
- **"Zero cost"** — vault layer yes; MCP layer no (shim code, auth design, testing).

The general vetting protocol: (1) check each claimed command/config key against the installed version's `--help` and source, (2) check each claimed tool against Rob's actual platforms, (3) check each claimed infra need against what's already running, (4) present a "right / wrong-for-you / unverified" table — NOT a flat accept or reject. Rob valued the honest comparison format this session.

## Related

- `syncthing-folder-sync` — the sync layer this bridge rides on; credential preflight applies to any new shared folder.
- `operating-hermes-gateway` — VPS architecture context; `references/local-vs-remote-session.md` for telling the user where a session executes.
- `composio-mcp-ops` — existing MCP-based integration (Hermes as MCP *client*); useful contrast when wiring Hermes as an MCP *server*.

## Supporting files

- `references/vault-ideas-projects-system.md` — folder layout, conventions, and write-back rules for the vault-based Ideas/Projects collaboration system
- `references/delegation-capability-matrix-2026-08-15.md` — verified capability matrix for Hermes/Claude/Playwright as of the Aug 15 audit
- `references/third-party-plan-vetting-2026-08-15.md` — preferred output format and red-flag checklist for evaluating pasted architecture docs