Skip to main content
Glama
RodrigoSiliunas

hermes-claude-bridge

by RodrigoSiliunas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Hermes-Claude Bridge

CI Release License: MIT

Delegate development tasks from Hermes Agent to Claude Code CLI — zero additional Anthropic API cost.

Status: early development. API may change until v1.0.0.

Why?

  • You already pay for Claude Code (Pro / Team / Enterprise) — reuse that subscription.

  • Hermes handles orchestration, memory, and multi-tool workflows.

  • Claude Code handles deep, multi-file coding tasks.

  • No Anthropic API tokens are consumed for delegated work.

Related MCP server: openai-agents-mcp

What problem does this solve?

Omni (automagik-dev/omni) showed that Telegram and other channels can talk to Claude Code. This bridge does the same for the Hermes Agent ecosystem, but focused on:

  • No extra API costs — reuse the Claude Code CLI subscription.

  • Persistent contextual sessions — SQLite/PostgreSQL store keeps full conversation history; every new prompt includes prior context.

  • History filtering & compression — cap how many past events are sent, with a compact summary of older messages.

  • MCP server — expose claude_code_delegate as a native MCP tool for Hermes or any MCP client.

  • Real-time events — SSE stream delivers events instantly via asyncio.Condition, no polling.

  • Human-in-the-loop — when Claude asks a question, the bridge pauses and asks the user.

  • Model selection — choose sonnet, opus, haiku, or any full model name.

  • Headless / scriptable — run claude -p --bare from Python/asyncio.

  • Structured results — parse file edits, bash commands, and errors from Claude's output.

  • Hermes-native — register as a tool (claude_code_delegate) inside Hermes skills.

Installation

pip install hermes-claude-bridge

Requires claude CLI installed and authenticated:

claude --version

Quick Start

CLI

# Check if claude is available
hermes-claude health

# Run a single task
hermes-claude run "Refactor auth.py to use dependency injection" -f src/auth.py

# Run from a file
hermes-claude run-file prompt.md

Python API

import asyncio
from hermes_claude_bridge.bridge import HermesClaudeBridge
from hermes_claude_bridge.schemas import ClaudeTask

async def main():
    bridge = HermesClaudeBridge()
    result = await bridge.run_task(ClaudeTask(
        prompt="Add type hints to all functions",
        context_files=["src/main.py"],
    ))
    print(result.model_dump_json(indent=2))

asyncio.run(main())

Setup for Hermes Agent

Option A: MCP server (recommended for tool-gateway style)

Generate the MCP config snippet and merge it into ~/.hermes/config.yaml:

hermes-claude setup --mcp-config >> ~/.hermes/config.yaml

With a default model preset (sonnet, opus or haiku):

hermes-claude setup --mcp-config --model sonnet >> ~/.hermes/config.yaml

On next startup, Hermes discovers the claude_code_delegate tool from the hermes-claude-bridge MCP server.

Option B: Native Hermes plugin

Install the plugin:

hermes-claude setup --hermes-plugin

Then enable it in ~/.hermes/config.yaml:

plugins:
  enabled:
    - hermes-claude-bridge

The plugin can connect to a bridge server automatically when the environment variable HERMES_CLAUDE_BRIDGE_URL is set:

export HERMES_CLAUDE_BRIDGE_URL=http://localhost:8765

Restart Hermes. The tool claude_code_delegate will be available in the hermes-claude-bridge toolset.

Server mode (stateful)

Start the bridge server for persistent sessions and real-time SSE events:

hermes-claude server --port 8765

Then use the Python client from Hermes:

import asyncio
from hermes_claude_bridge.client import BridgeClient

async def main():
    client = BridgeClient("http://localhost:8765")

    # Use mode="interactive" to keep conversation context across prompts.
    # Limit how many past events are included to avoid overflowing context.
    session = await client.create_session(
        working_dir="/path/to/project",
        model="sonnet",
        mode="interactive",
        max_history_events=5,
    )
    result = await client.send_prompt(
        session["session_id"],
        "Refactor auth.py to use dependency injection",
        context_files=["src/auth.py"],
    )
    print(result)

    if result.get("status") == "waiting_user_input":
        question = result["pending_question"]
        # Ask the user, then:
        await client.answer_question(session["session_id"], "Yes, proceed.")

asyncio.run(main())

MCP server

Expose the bridge as a native MCP tool:

hermes-claude mcp-server

Hermes (or any MCP client) can then call claude_code_delegate. For stateless single tasks:

{
  "prompt": "Refactor auth.py",
  "context_files": ["src/auth.py"],
  "model": "sonnet"
}

For persistent sessions, point the tool at a running bridge server:

{
  "prompt": "Refactor auth.py",
  "bridge_url": "http://localhost:8765",
  "mode": "interactive"
}

Hermes Skill

Install the skill into your Hermes profile:

cp -r .skills/hermes-claude-bridge ~/.hermes/skills/

Then register the tool in your agent:

from hermes_claude_bridge.hermes_adapter import ClaudeBridgeTool

tool = ClaudeBridgeTool()
schema = tool.get_schema()  # Register with Hermes
result = await tool.invoke({
    "prompt": "Refactor auth.py",
    "context_files": ["src/auth.py"],
    "model": "sonnet",
    "permission_mode": "acceptEdits",
    "timeout": 300,
})

See .skills/hermes-claude-bridge/SKILL.md for the full skill definition.

Architecture

Hermes Agent
    |
    v
+----------------------------------+
|  BridgeClient or ClaudeBridgeTool|
|  - HTTP client / tool adapter    |
+----------------------------------+
    |
    | SSE / HTTP
    v
+----------------------------------+
|  Hermes-Claude Bridge Server     |
|  - FastAPI + SSE streaming       |
|  - Session Manager (SQLAlchemy)  |
+----------------------------------+
    |
    v
+----------------------------------+
|  HermesClaudeBridge (orchestrator)|
|  - Task execution                |
|  - Health checks                 |
+----------------------------------+
    |
    v
+----------------------------------+
|  ClaudeExecutor (subprocess)     |
|  - claude -p [--bare]            |
|  - Async subprocess + timeout    |
+----------------------------------+
    |
    v
+----------------------------------+
|  OutputParser                    |
|  - Extract file edits            |
|  - Extract bash commands         |
|  - Detect questions              |
+----------------------------------+
    |
    v
  Result (JSON)

Configuration

Environment variables:

Variable

Default

Description

CLAUDE_EXECUTABLE

claude

Path to claude CLI

CLAUDE_WORKING_DIR

.

Default working directory

CLAUDE_TIMEOUT

300

Default timeout in seconds

CLAUDE_BARE

true

Use --bare mode

CLAUDE_PERMISSIONS

acceptEdits

Default permission mode

CLAUDE_MODEL

None

Default Claude model

DATABASE_URL

sqlite+aiosqlite:///./hermes_claude_bridge.db

Async database URL

Permission Modes

Mode

Behavior

acceptEdits

Auto-approve file edits; ask for bash/other tools

dontAsk

Auto-approve everything (dangerous, use with care)

default

Ask for every tool use (not headless)

Development

git clone https://github.com/RodrigoSiliunas/hermes-claude-bridge.git
cd hermes-claude-bridge
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Releasing

To create a new release:

# Update version in pyproject.toml and src/hermes_claude_bridge/__init__.py
git add -A
git commit -m "chore(release): bump version to v0.6.0"
git tag v0.6.0
git push origin main --tags

The Release workflow will automatically build the package and create a GitHub Release with release notes.

Testing

pytest tests/ -v

License

MIT.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers