Content
# Hermes + Claude Code
**Hermes Agent → Claude Code via any OpenAI-compatible API.**
Pipe coding tasks straight to Claude Code from your AI agent, routed through any proxy (OpenRouter, VansRouter, LiteLLM, 9Router) or direct provider (OpenAI, Anthropic, Gemini, etc.).
```
┌─────────────┐ MCP/stdio ┌──────────────┐ HTTP/JSON ┌─────────────┐
│ Hermes │ ◄─────────────────► │ cc-mcp- │ ◄───────────► │ Any │
│ Agent │ │ server.py │ │ OpenAI- │
│ (AI agent) │ 8 tools exposed │ │ /v1/chat/ │ compatible │
└─────────────┘ │ + wrapper │ completions │ API │
└──────────────┘ └─────────────┘
```
---
## ⚡ One-shot setup: give this to your AI agent
Copy-paste the block below to any AI agent. It will auto-setup everything.
```
You have access to my server. I want to connect my AI agent to Claude Code.
1. Clone this repo:
git clone https://github.com/<your-username>/hermes-claude-code.git ~/.hermes-claude-code
2. Run installer:
cd ~/.hermes-claude-code && bash setup/install.sh
3. Create .env with my API details:
cat > ~/.hermes-claude-code/.env << 'EOF'
CC_BASE_URL=http://localhost:20126/v1
CC_API_KEY=sk-xxxxx
CC_MODEL_OPUS=opus-level
CC_MODEL_SONNET=sonnet-level
CC_MODEL_HAIKU=haiku-level
EOF
4. Source it and restart Hermes:
source ~/.hermes-claude-code/.env
hermes gateway restart
5. Verify:
hermes mcp list # Should show 'claude-code' with tools
claude-code-run.sh -m haiku -w /tmp "print('hello from CC')"
6. Use from your agent — the 8 MCP tools are ready:
cc_haiku(task, workdir) # Quick fixes, typos, one-liners
cc_sonnet(task, workdir) # Features, refactoring, PR review
cc_opus(task, workdir) # Architecture, deep debug, heavy reasoning
cc_image(task, image_path) # OCR, receipt extraction
cc_continue(task, workdir) # Resume last session
cc_save_session(...) # Persist results
cc_daemon_dispatch(...) # Fire-and-forget long tasks
cc_daemon_check(task_id) # Check daemon status
Done. You're now talking to an agent that can delegate coding to Claude Code.
```
That's it. Your agent does the rest.
---
## Features
- **Provider-agnostic** — set two env vars (`CC_BASE_URL` + `CC_API_KEY`) and it works with any OpenAI-compatible backend.
- **3 cost tiers** — `haiku` for cheap quick-fixes, `sonnet` for daily work, `opus` for hard problems.
- **Sync + async** — MCP tools block with 24h timeout; daemon dispatch is fire-and-forget.
- **Auto-project init** — `git init` + CLAUDE.md with Karpathy-style guidelines if missing.
- **Piped input** — `git diff | claude-code-run.sh "review this"`.
- **tmux REPL** — interactive multi-turn Claude Code sessions.
- **Zero personal data** — all paths use `Path.home()` or env vars.
## Prerequisites
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) (`npm install -g @anthropic-ai/claude-code`)
- An OpenAI-compatible API endpoint (VansRouter, 9Router, OpenRouter, LiteLLM, Anthropic, OpenAI...)
- Python 3.10+
- Hermes Agent (for MCP integration)
## Manual setup
```bash
git clone https://github.com/<your-username>/hermes-claude-code.git ~/.hermes-claude-code
cd ~/.hermes-claude-code
bash setup/install.sh
# Edit .env with your API config
nano .env
# Restart Hermes
hermes gateway restart
```
Or follow [`docs/MANUAL_SETUP.md`](docs/MANUAL_SETUP.md) step by step.
## Environment variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CC_BASE_URL` | Yes | `http://localhost:20126/v1` | OpenAI-compatible API endpoint |
| `CC_API_KEY` | Yes* | — | API key |
| `CC_DB_PATH` | Alt* | — | SQLite DB with API keys (VansRouter/9Router) |
| `CC_DB_KEY_NAME` | No | `Claude Code` | API key name in SQLite |
| `CC_MODEL_OPUS` | No | `opus-level` | Model name for opus tier |
| `CC_MODEL_SONNET` | No | `sonnet-level` | Model name for sonnet tier |
| `CC_MODEL_HAIKU` | No | `haiku-level` | Model name for haiku tier |
| `CC_MODEL_DELEGATE` | No | `delegate` | Model name for daemon delegate |
| `CC_MODEL_HIGH_THINK` | No | `high-think` | Model name for high-reasoning |
| `CC_MODEL_IMAGE` | No | `image` | Model name for vision/OCR |
| `CC_SKIP_GIT_INIT` | No | — | Set `1` to skip auto git init |
*\*Set `CC_API_KEY` OR `CC_DB_PATH`. If neither, the wrapper errors.*
## Usage
### From any AI agent (MCP tools)
Tool | Purpose | Best for
-----|---------|---------
`cc_haiku` | Quick fix | Typo, one-liner, format, simple script
`cc_sonnet` | Core dev | Feature, refactor, test, PR review
`cc_opus` | Heavy work | Architecture, security audit, deep debug
`cc_image` | Vision/OCR | Receipt text, screenshot analysis
`cc_continue` | Resume | Follow up on last CC session
### From terminal
```bash
# Basic
./scripts/claude-code-run.sh -m sonnet -w /project "Add tests"
# Piped input
git diff | ./scripts/claude-code-run.sh -m haiku -b 0.02 "Review changes"
# Streaming output
./scripts/claude-code-run.sh -m sonnet -s -w /project "Debug this"
# Interactive tmux REPL
./scripts/claude-code-run.sh -T -w /project "Implement feature"
# Resume last session
./scripts/claude-code-run.sh -c -w /project "Follow up on the PR"
```
### Daemon (background tasks)
```bash
# Dispatch heavy task (returns immediately)
python3 scripts/cc-daemon-manager.py dispatch "Refactor auth" /project opus
# Check status later
python3 scripts/cc-daemon-manager.py check <task_id>
# List all tasks
python3 scripts/cc-daemon-manager.py list
```
## Backend examples
| Backend | `CC_BASE_URL` |
|---------|---------------|
| VansRouter (local) | `http://localhost:20126/v1` |
| 9Router (local) | `http://localhost:20127/v1` |
| OpenRouter | `https://openrouter.ai/api/v1` |
| LiteLLM | `http://localhost:4000/v1` |
| Anthropic Direct | `https://api.anthropic.com/v1` |
| OpenAI Direct | `https://api.openai.com/v1` |
## How it works
1. Your AI agent calls an MCP tool (e.g. `cc_sonnet`)
2. **cc-mcp-server.py** receives it and delegates to `claude-code-run.sh`
3. **claude-code-run.sh** resolves API key, sets `OPENAI_BASE_URL`, launches `claude` CLI
4. **Claude Code** runs the task via your configured API
5. Result flows back through the chain
## File structure
```
hermes-claude-code/
├── README.md # This file + AI prompt template
├── LICENSE # MIT
├── .gitignore
├── scripts/
│ ├── claude-code-run.sh # Main CLI wrapper (provider-agnostic)
│ ├── cc-mcp-server.py # MCP stdio server for Hermes
│ ├── cc-daemon-manager.py # Background task dispatcher
│ └── cc-daemon-start.sh # Daemon starter template
├── setup/
│ └── install.sh # One-command installer
└── docs/
├── MODEL_TIERS.md # Model tier reference
├── TROUBLESHOOTING.md # Common issues & fixes
└── MANUAL_SETUP.md # Step-by-step manual setup
```
## License
MIT
