🤖 hermes-claude-cli

Use your Claude Max subscription as a first-class provider in Hermes Agent.

---

A tiny Hermes Agent plugin that adds claude-cli to the hermes model picker. Inference flows through claude-bridge, which subprocesses Anthropic's official claude CLI — meaning every request runs against your Claude Code subscription's base plan allowance instead of pay-per-token API credits.

hermes model      →   pick "Claude CLI (Max subscription)"
                  ↓
hermes session    →   provider=claude-cli, base_url=http://localhost:9180/v1
                  ↓
claude-bridge     →   subprocess `claude -p --output-format json`
                  ↓
your Max subscription

Why this exists

Hermes' bundled anthropic provider calls api.anthropic.com directly. With a Claude Max plan, that path returns:

Third-party apps now draw from your extra usage, not your plan limits.

…because Max's base allowance only applies to first-party Claude Code. This plugin sidesteps that by routing through the local claude CLI itself, which is first-party.

What you get

After install, hermes model shows:

  ...
  ✓ anthropic              Anthropic — Claude API (API key, billed per token)
  ✓ claude-cli             Claude CLI (Max subscription) — uses your Max base allowance
  ✓ deepseek               DeepSeek
  ✓ openrouter             OpenRouter (100+ models, pay-per-use)
  ...

Pick claude-cli, and every Hermes call (cli, dashboard chat, Matrix, Telegram, cron) routes through your subscription.

Model aliases supported: sonnet, opus, haiku, plus the full IDs (claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5).

Install

One-liner

curl -fsSL https://raw.githubusercontent.com/niski84/hermes-claude-cli/main/scripts/install.sh | bash

The installer:

1. Checks for Claude Code (must be installed and logged in)
2. Checks for Hermes Agent at ~/.hermes/
3. Clones, builds, and installs claude-bridge at ~/.local/bin/claude-bridge
4. Sets up a systemd user service so the bridge auto-starts on login
5. Symlinks the provider plugin into ~/.hermes/plugins/model-providers/claude-cli
6. Verifies the bridge responds + Hermes sees the plugin

Or manually

# 1. Install + run claude-bridge (see https://github.com/niski84/claude-bridge)
go install github.com/niski84/claude-bridge/cmd/claude-bridge@latest
claude-bridge &   # listens on :9180

# 2. Drop this plugin into Hermes' user plugins dir
mkdir -p ~/.hermes/plugins/model-providers
git clone https://github.com/niski84/hermes-claude-cli.git ~/hermes-claude-cli
ln -s ~/hermes-claude-cli/plugin/claude-cli ~/.hermes/plugins/model-providers/claude-cli

# 3. Restart any running Hermes processes
systemctl --user restart hermes-gateway 2>/dev/null

Use

# Interactively pick claude-cli as your provider
hermes model

# Or hardcode it in ~/.hermes/config.yaml
cat >> ~/.hermes/config.yaml <<'EOF'
model:
  provider: claude-cli
  default: sonnet
EOF
systemctl --user restart hermes-gateway

After that, run Hermes however you normally do — CLI, dashboard chat, Matrix bot, Telegram bot, cron jobs. Everything routes through the bridge → CLI → Max subscription.

Configuration

The plugin has one optional env var:

Var	Default	Purpose
CLAUDE_BRIDGE_URL	http://localhost:9180/v1	Where claude-bridge is reachable. Override if running on a different host/port or behind a reverse proxy.

claude-bridge itself has its own env vars — see its README.

What this doesn't do (yet)

• No tool-call passthrough. Hermes sends tools: [...] arrays; the claude CLI doesn't accept tool schemas from callers — it uses its own built-in tools (Read, Grep, Bash, Edit). For most Hermes use (chat, summaries, vault search via the obsidian skill) this is fine — Claude does the equivalent work with its own tools. Hermes-specific skills that depend on injected tool definitions won't fire through this path.
• Subprocess overhead. Each request spawns claude fresh (~1–3s startup). Worth it for the cost savings; slower than direct API calls.

Troubleshooting

hermes model doesn't show "Claude CLI"

# Confirm the symlink:
ls -la ~/.hermes/plugins/model-providers/claude-cli/

# Force Hermes to re-scan plugins:
systemctl --user restart hermes-gateway
hermes plugins list | grep claude

Empty responses / Empty response (no content or reasoning)

You're on an old claude-bridge build that didn't emit SSE for streaming requests. Rebuild:

cd ~/.local/share/claude-bridge && git pull && go build -o ~/.local/bin/claude-bridge ./cmd/claude-bridge
systemctl --user restart claude-bridge

Permission prompts ("I need access to…") in responses

Claude CLI defaults to permission gates on filesystem reads outside CWD. Tell claude-bridge to either pre-authorize specific dirs or skip permissions entirely (localhost-only deployment makes this safe):

systemctl --user edit claude-bridge
# Add:  Environment="CLAUDE_BYPASS_PERMISSIONS=true"
systemctl --user restart claude-bridge

See claude-bridge's README for the full env var list.

Architecture

hermes-claude-cli/
├── plugin/claude-cli/
│   ├── plugin.yaml        # Hermes plugin manifest
│   └── __init__.py        # ~30-line ProviderProfile registration
├── scripts/
│   └── install.sh         # one-shot bootstrap
├── LICENSE                # MIT
└── README.md

The plugin is 30 lines of Python. It instantiates a ProviderProfile with the bridge's URL and the curated model list, then calls register_provider(). All the heavy lifting (HTTP server, CLI subprocessing, SSE streaming, message flattening) is in claude-bridge.

Roadmap

• Upstream the provider into Hermes core (PR pending)
• Bundle a prebuilt bridge binary in the install.sh so Go isn't required
• /claude-cli slash command for runtime status + bridge restart
• Optional support for direct subprocess (skip the HTTP hop) when running entirely inside Hermes

License

MIT. See LICENSE.

Related

• claude-bridge — the HTTP shim this plugin talks to
• Hermes Agent — the agent framework this plugin extends
• Claude Code — Anthropic's CLI, what gets subprocessed