Hermes Agent Orchestration

Building Hermes as a top-level orchestrator that delegates long-running software development tasks to Claude Code sub-agents via the Claude Agent SDK, all routing through the existing LiteLLM proxy on localhost:4000.

Current Focus

MCP integrations explored: GitHub and GitLab MCP servers configured via ~/.hermes/config.yaml. Next: install SDK, write the Hermes tool wrapper, wire MCP servers into subagent contexts.

Open Tasks

• pip install claude-agent-sdk on phuriwajr-dev
• Set ANTHROPIC_BASE_URL=http://localhost:4000 and ANTHROPIC_API_KEY=<litellm_master_key>
• Write Hermes tool wrapper that calls query() with scoped options
• Define 4 subagent configs: refactor-agent, test-agent, ci-agent, reviewer
• Test end-to-end: Hermes → refactor-agent on a real codebase directory
• Add max_budget_usd per call to prevent runaway spend
• Wire session_id for multi-turn subagent tasks
• Configure GitHub MCP in ~/.hermes/config.yaml with personal access token
• Configure GitLab MCP in ~/.hermes/config.yaml with personal access token
• Run hermes mcp list to verify both servers show tools

Key Decisions / Insights

• Claude Agent SDK is the right bridge — CLI subprocess is too brittle for production orchestration
• ANTHROPIC_BASE_URL override routes SDK through LiteLLM transparently — same pattern as Claude Code
• Each subagent gets only the tools it needs — read-only reviewer, Bash-enabled test-agent
• 1 agentic session ≈ 2–5 concurrent API requests — Hermes gateway capacity must be planned accordingly
• GSD + autonomous-dev pattern worth evaluating for Hermes overnight build pipeline

People

None yet.

Progress Log

2026-05-13

Architecture designed in conversation “Hermes orchestrating Claude agents for development workflows”. Chose Claude Agent SDK (Python) over CLI subprocess or MCP bridge. Full architecture: Hermes → query() → Claude Agent SDK → Claude Code subprocess → LiteLLM proxy → GLM/OpenRouter. Four subagent types defined (refactor, test, ci, reviewer). Next step: hands-on setup on phuriwajr-dev.

2026-05-15

Explored Hermes capabilities across four domains: productivity (notes, tasks, summaries), personal (second brain via MEMORY.md + evergreen notes), work/dev (orchestrate sub-agents via Claude Agent SDK, model routing via LiteLLM), and life (decision support, planning with persistent context). Designed MCP integration for GitHub and GitLab via ~/.hermes/config.yaml — env vars must be explicit in config, not inherited from shell. Key insight: Hermes becomes more useful over time as MEMORY.md accumulates context. See reference/hermes-mcp-github-gitlab for full setup.

2026-05-16

Revisited GitHub/GitLab MCP setup — confirmed the config pattern from yesterday is correct. Explored Discord integration options: Claude Code Channels (official, requires v2.1.80+ and Pro/Max subscription), Composio MCP connector (for Cowork), and n8n/Albato for no-code automation. Key distinction: Claude Code Channels only works while a local Claude Code session is actively running. Discord via Composio is the better path for Hermes (always-on knowledge work). No new tasks added — MCP config tasks from 2026-05-15 still open.

2026-05-19

Capacity planning correction: Clarified that Claude Code agentic sessions are not 1:1 with concurrent API requests. A single agentic task spawns 2–5 parallel tool calls. If Z.ai gateway limit = 10 concurrent, Hermes realistically supports only 2–3 simultaneous active users running agentic tasks. Need to re-calculate capacity model and possibly request higher concurrency tier. See claude-code-execution-methods for full details.

New pipeline pattern evaluated: GSD + autonomous-dev harness reviewed as a potential architecture for Hermes overnight builds. The adversarial spec-blind reviewer concept is worth adopting: have a separate sub-agent test the output without having seen the implementation. Adds: tasks written before coding, 0-failure gate, no-stubs gate, spec-blind validation. See claude-code-autonomous-pipeline.