Hermes Claude Bridge

README

# hermes-claude-bridge

Hermes plugin that lets [Hermes](https://github.com/NousResearch/hermes-agent) talk to Claude via [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) — using a Claude Code subscription, not API-key billing.

Bundles a Hermes-flavored fork of [shinglokto/openclaw-claude-bridge](https://github.com/shinglokto/openclaw-claude-bridge) (MIT) as a local HTTP service, plus a Hermes provider profile that points at it. Runs side-by-side with OpenClaw's own bridge on the same machine — different ports, isolated CLI session namespace.

## Models exposed

```
claude-bridge/claude-opus-4-7        # 1M context
claude-bridge/claude-sonnet-4-5      # 1M context
claude-bridge/claude-haiku-4-5       # 200k context
claude-bridge/claude-opus-latest     # alias
claude-bridge/claude-sonnet-latest   # alias
claude-bridge/claude-haiku-latest    # alias
```

Switch via `/model claude-bridge/claude-opus-4-7` in Hermes, or set it in your profile config.

## Install

The repo doubles as a Hermes plugin and a Node service. Clone anywhere, run `install.sh` to set up the service, then symlink the nested provider dir into Hermes' plugin path:

```bash
# Clone wherever you want
git clone https://github.com/Kyzcreig/hermes-claude-bridge ~/Projects/hermes-claude-bridge
cd ~/Projects/hermes-claude-bridge
./install.sh                           # builds bridge, installs launchd/systemd, starts service

# Wire the Hermes-side provider profile into your Hermes home
ln -s ~/Projects/hermes-claude-bridge/plugins/model-providers/claude-bridge \
      ~/.hermes/plugins/model-providers/claude-bridge
```

Prerequisites: `claude` CLI installed and authenticated (`claude auth status`), Node ≥18.

`install.sh` runs `npm install`, creates state dirs, installs a launchd plist (macOS) or systemd user unit (Linux), starts the bridge, and verifies `/health`. The symlink lets Hermes discover the provider profile on next start.

## Ports

| Service | Port | Bind |
|---|---|---|
| API | `3556` | `127.0.0.1` |
| Status / dashboard | `3558` | `127.0.0.1` |

These are explicitly +100 from upstream (`3456/3458`) so both bridges can run on the same machine.

## Coexistence with OpenClaw bridge

By design:
- Ports don't overlap
- CLI working directory is isolated (`~/.hermes/plugins/model-providers/claude-bridge/state/cli-cwd/` vs upstream's `/tmp`), so Claude session JSONLs land in entirely separate `~/.claude/projects/` namespaces
- State files separate
- Env var prefixes differ (`HERMES_BRIDGE_*` vs `OPENCLAW_BRIDGE_*`)

See [`docs/coexistence-with-openclaw.md`](docs/coexistence-with-openclaw.md).

## What we changed vs. upstream

See [`CHANGELOG.md`](CHANGELOG.md). Summary:

- **Scrubber:** Hermes-neutral alias word lists (`Nova/Echo/Kite/...` × `Hub/Pod/Bay/...`), brand strings swap `Hermes`/`hermes` instead of `OpenClaw`/`openclaw`
- **Ports:** `3556/3558` (was `3456/3458`)
- **CLI cwd:** isolated to plugin state dir (was `/tmp`)
- **Timeouts:** idle `360s` (was `120s`), hard `30 min` (was `20 min`) — Opus + heavy software tasks legitimately stall longer
- **Status bind:** `127.0.0.1` (was `0.0.0.0`) — safer default
- **Env vars:** `HERMES_BRIDGE_*` prefix
- **Attachment pass-through:** images, PDFs, code/text via in-prompt `@path` refs (default on) — opt-out via `HERMES_BRIDGE_ATTACHMENT_MODE=describe`

We aim to keep the diff small and rebase-friendly. `scripts/upstream-sync.sh` pulls upstream and reapplies our patches.

## Status

🚧 v0.1 in progress. See [`docs/PRD.html`](docs/PRD.html) for the full spec and phase tracker.

## License

MIT (matching upstream). See [`LICENSE`](LICENSE).