hermes-claude-code

hermes-claude-code

MCP server + Hermes plugin that lets Hermes Agent delegate coding tasks to Claude Code CLI sub-agents.

Hermes plans and coordinates while Claude Code handles the actual implementation — reading files, writing code, running commands, making commits, and more.

How it works

Hermes (coordinator)
  │
  ├─→ claude_code_delegate("implement auth middleware in /app")
  │     └─→ claude -p "implement auth middleware..." --permission-mode bypassPermissions
  │         └─→ [reads files, writes code, runs tests, returns result]
  │
  ├─→ claude_code_research("how does the payment flow work in /api")
  │     └─→ claude -p "READ-ONLY: how does..." --tools Read Glob Grep Bash Agent
  │
  └─→ claude_code_batch([task1, task2, task3])  ← parallel execution
        ├─→ claude -p "task 1..." &
        ├─→ claude -p "task 2..." &
        └─→ claude -p "task 3..." &

Features

• claude_code_delegate — Send autonomous coding tasks (read + write access)
• claude_code_research — Read-only codebase exploration and analysis
• claude_code_batch — Run up to 5 tasks in parallel
• claude_code_continue — Resume a previous session for multi-turn workflows (MCP only)
• Model selection — Route to opus (complex), sonnet (standard), or haiku (simple)
• Session continuity — Pass session_id to continue previous work
• Budget control — Set max_budget_usd per task
• Tool restrictions — Limit which tools Claude Code can use
• Multi-directory — Grant access to additional directories with add_dirs

Installation

Prerequisites

• Claude Code CLI installed and authenticated (claude auth login)
• Node.js 18+ (for MCP server)
• Hermes Agent (for plugin)

Quick install

git clone https://github.com/DevvGwardo/hermes-claude-code.git
cd hermes-claude-code
./install.sh          # Install both MCP server + Hermes plugin
# or
./install.sh mcp      # MCP server only
./install.sh plugin   # Hermes plugin only

Option A: MCP Server (works with Hermes, Claude Code, and any MCP client)

cd hermes-claude-code
npm install

Register with Hermes — add to ~/.hermes/config.yaml:

mcp_servers:
  claude-code:
    command: node
    args: [/path/to/hermes-claude-code/server.mjs]
    timeout: 660

Register with Claude Code — add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "claude-code": {
      "command": "node",
      "args": ["/path/to/hermes-claude-code/server.mjs"]
    }
  }
}

Option B: Hermes Plugin (native integration)

# Symlink or copy the plugin into Hermes plugins directory
ln -s /path/to/hermes-claude-code/hermes-plugin ~/.hermes/plugins/claude-code

Restart Hermes — the tools appear automatically.

Usage

From Hermes

Once installed, Hermes can use these tools in conversation:

You: Build a REST API for user management in /projects/my-app

Hermes: I'll delegate this to Claude Code.
  → claude_code_delegate(task="Create a REST API with CRUD endpoints for user management using Express.js. Include: POST /users, GET /users/:id, PUT /users/:id, DELETE /users/:id. Use a SQLite database. Add input validation and error handling.", work_dir="/projects/my-app")

Parallel tasks

You: Set up the backend and frontend for my new project simultaneously

Hermes: I'll run both tasks in parallel.
  → claude_code_batch(tasks=[
      {task: "Create Express.js backend with auth...", work_dir: "/projects/backend"},
      {task: "Create React frontend with login page...", work_dir: "/projects/frontend"}
    ])

Research mode

You: How does the authentication flow work in this codebase?

Hermes: Let me have Claude Code analyze that.
  → claude_code_research(question="Trace the full authentication flow from login to session creation. Identify all middleware, token generation, and session storage mechanisms.", work_dir: "/projects/my-app")

Multi-turn workflows

# Step 1: Initial implementation
→ claude_code_delegate(task="Create user model...", work_dir="/app")
# Returns session_id: "abc-123"

# Step 2: Continue with tests (MCP server only)
→ claude_code_continue(message="Now add unit tests for the user model", session_id="abc-123")

Configuration

Environment variables

Variable	Default	Description
CLAUDE_CODE_BIN	claude	Path to Claude Code CLI binary

CLAUDE.md integration

Add to your project's CLAUDE.md to guide Hermes on when to delegate:

## Claude Code Delegation

When implementing features or fixing bugs, delegate self-contained sub-tasks
to Claude Code using the `claude_code_delegate` tool.

### When to delegate
- Writing new functions, modules, or files with clear requirements
- Bug fixes with clear scope
- Refactoring specific files
- Running tests and fixing failures

### When NOT to delegate
- Tasks requiring back-and-forth with the user
- Architecture decisions
- Tasks that depend on conversation context Hermes hasn't passed

Architecture

MCP Server (server.mjs)

Node.js MCP server that wraps the claude CLI. Uses @modelcontextprotocol/sdk for the MCP protocol and spawns claude -p subprocesses for each task.

Hermes Plugin (hermes-plugin/)

Python plugin that registers tools directly into Hermes's tool registry via PluginContext.register_tool(). Uses subprocess.run() to invoke Claude Code and ThreadPoolExecutor for parallel batch execution.

Both approaches produce identical results — choose based on your setup:

• MCP server: Works with any MCP-compatible client (Hermes, Claude Code, Cursor, etc.)
• Hermes plugin: Tighter integration, no extra process, appears in hermes tools TUI

License

MIT