Phuriwaj

Hermes Agent Orchestration

Planted 20 days ago

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

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.

2026-05-20

Jira integration tested via Composio: Created PT-1 successfully via Composio MCP connector — first live Jira task created from Claude. Confirmed Rovo (Atlassian native AI) is blocked on personal Jira (phuriwaj.atlassian.net) because account uses outlook.com — Composio is the right path. Alternative: Atlassian MCP server with OAuth (also avoids domain restriction).

Autonomous pipeline research: Reviewed GSD + autonomous-dev full pipeline in detail (CC-Autonomous conversation). Key additions to evaluate for Hermes: adversarial spec-blind testing (separate agent validates output without seeing implementation), wave-based parallel subagents for execution phase, GitHub Actions trigger on requirements.md push. See updated claude-code-autonomous-pipeline for full walk-through.

Capacity planning confirmed: 1 active agentic Claude Code session = 2–5 concurrent API requests. Gateway design for Hermes must account for this multiplier. Re-calculate capacity model.

MiniMax privacy risk flagged: Analysis shows MiniMax policy reserves rights to use de-identified data commercially (including training); no explicit “won’t train” clause; data in China. Z.ai confirmed safer. Implications for Hermes model routing: prefer Z.ai for any task involving customer or sensitive data. See minimax-security-privacy.

2026-05-22

Hermes fleet concept explored: Initiated conversation about running multiple specialized Hermes agents — one per life area rather than a single generalist Hermes. Three candidate architectures: (1) separate Hermes instances per life area (work, personal, health, etc.), (2) Hermes sub-agents under a single orchestrator, (3) hybrid hierarchy. Conversation ended at the clarifying-questions stage — no architecture chosen yet. This maps to the “life OS” vision.

Open question to resolve before next session: what are the life domains and what would each specialized agent actually do differently from a generalist Hermes?

2026-05-22 (evening)

Configuration surface verified: Confirmed native AGENTS.md and MEMORY.md support in Hermes. AGENTS.md uses 4-level progressive discovery (root → workspace → project → subdirectory) and is interchangeable with CLAUDE.md. MEMORY.md is agent-curated with a 2,200-char hard cap — the agent writes to it over time; it is not a hand-authored config file. Full surface: SOUL.md (persona) → USER.md (static profile) → AGENTS.md (project context) → MEMORY.md (learned facts) → FTS5 session db (conversation history) → skills library. Plus 8 optional external memory plugins (Obsidian, Notion, Linear, GitHub, GitLab, Slack, Calendar, Email).

Key implication for fleet design: AGENTS.md is the right place for per-domain rules in a multi-Hermes fleet setup. MEMORY.md accumulates automatically per-instance if Hermes instances are isolated per life area. See hermes-agent-configuration for full reference.

Week of 2026-W20 (Mon 12 – Sun 17 May)

Hermes integration design progressed significantly. Architecture for Hermes as top-level orchestrator of Claude Code sub-agents was designed (May 13): four subagent types (refactor, test, ci, reviewer) routed through LiteLLM proxy by overriding ANTHROPIC_BASE_URL. GitHub and GitLab MCP servers wired into ~/.hermes/config.yaml (May 15–16) — critical finding: tokens must be declared explicitly in the config env: block, not inherited from shell. Full capability surface mapped: SOUL.md, USER.md, AGENTS.md, MEMORY.md, FTS5 db, skills, 8 external memory plugins. Discord integration decision made: Composio MCP (always-on) over Claude Code Channels (session-dependent).

Status: 🟡 MCP configuration designed — SDK not yet installed, Hermes tool wrapper not yet written.

Open tasks (W21):

  • pip install claude-agent-sdk on phuriwajr-dev, set ANTHROPIC_BASE_URL=http://localhost:4000
  • Write Hermes tool wrapper around query() + define 4 subagent types
  • Configure GitHub MCP in ~/.hermes/config.yaml with PAT
  • Configure GitLab MCP in ~/.hermes/config.yaml with PAT
  • Test Composio MCP for Discord integration

2026-05-24

agent-skills stack evaluated: Reviewed addyosmani/agent-skills (43K stars) for inclusion in the autonomous build pipeline. Three skills worth cherry-picking: doubt-driven-development (adversarial decision review), source-driven-development (grounds framework decisions in official docs — critical for Next.js 16/Django 6), and context-engineering (context packing at session start). All other skills overlap with Speckit, Superpowers, and gstack. Final stack with clean job separation: Speckit (WHAT) → agent-skills (HOW to think) → Superpowers (HOW to execute) → gstack (HOW to verify/ship). See claude-code-autonomous-pipeline and addy-osmani.

Also explored today: Linux screen command as an alternative to Zellij for keeping Claude Code sessions alive over SSH (see linux-screen-claude-code). Session ID lookup via jq on ~/.claude/history.jsonl (see claude-code-session-files). Zellij install via cargo/brew confirmed working after fixing PATH.

2026-05-28

Hermes Docker profile migration: Explored how to move a Hermes profile from one Docker instance to another. Key finding: copy the entire profile folder (not individual files) from the Docker volume mount — simpler and safer. Profile data lives inside the container’s mounted volume at <mount_path>/profiles/<profile_name>/. Copy workflow: docker exec to inspect paths → tar + docker cp to extract from source → copy archive to target host → extract into target bind mount. See hermes-docker-profile-management for full commands.

GitHub Actions: Started exploring GitHub Actions automation (conversation still in progress — no action type selected yet).

Week of 2026-W22 (Mon 26 – Fri 30 May)

Focus this week shifted to Hermes infrastructure — specifically Docker profile management. The key operational question (how to migrate profiles between instances) was answered: copy the entire profile folder, not individual files. A new reference note was created: hermes-docker-profile-management. GitHub Actions automation was started but no action type was selected yet; that thread carries into next week.

Earlier in the week: no direct Hermes development work — the May 27 automated tasks and consolidation ran cleanly, and the Claude Code analytics pipeline reported 344,063 lines for the month with phuriwajr at 31,146.

Status: 🟡 Docker profile migration procedure documented — SDK install and tool wrapper still pending.

Open tasks (W23):

  • Run the Hermes profile copy command on target Docker host and verify profile loads correctly
  • Decide on first GitHub Action type for Hermes automation and continue the setup conversation
  • pip install claude-agent-sdk on phuriwajr-dev, set ANTHROPIC_BASE_URL=http://localhost:4000
  • Write Hermes tool wrapper around query() + define 4 subagent types
  • Configure GitHub MCP in ~/.hermes/config.yaml with PAT
  • Configure GitLab MCP in ~/.hermes/config.yaml with PAT