# hermes-claude-code

MCP server + Hermes plugin that lets [Hermes Agent](https://github.com/NousResearch/hermes-agent) delegate coding tasks to [Claude Code](https://claude.ai/download) 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](https://claude.ai/download) installed and authenticated (`claude auth login`)
- [Node.js 18+](https://nodejs.org/) (for MCP server)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent) (for plugin)

### Quick install

```bash
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)

```bash
cd hermes-claude-code
npm install
```

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

```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`:

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

### Option B: Hermes Plugin (native integration)

```bash
# 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:

```markdown
## 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