kugetsu/docs/hermes-communication-patterns.md

Hermes Communication Patterns

Date: 2026-03-30 Status: Complete Related Issue: #4

Summary

Document how Hermes passes messages between agents — the mechanisms, patterns, and practical examples for PM ↔ Coding Agent coordination.

---

1. Message Passing Mechanisms

Hermes has two distinct delegation mechanisms, each with different concurrency characteristics:

1.1 delegate_task() — Native LLM Subagent

Spawns an LLM-powered subagent with its own isolated context. Communication is direct (function calls).

Attribute	Value
Concurrency	Max 3 (hard schema limit)
Context	Fresh, isolated per subagent
Tools	Full Hermes toolset
Best for	Reasoning-heavy research tasks

delegate_task(
    goal="Analyze issue #4 and document findings",
    context="Repo: ~/repositories/kugetsu, Token: ...",
    toolsets=["terminal", "file"]
)

Limitation: The 3-agent cap is a schema constraint. Reaching it causes "Too many active tasks" errors. For parallel workloads, use terminal(opencode run) instead.

1.2 terminal() + OpenCode — CLI Subprocess Wrapper

Spawns an OpenCode CLI process as a child. Hermes streams output via process().

Attribute	Value
Concurrency	No hard cap (limited by RAM/CPU)
Context	OpenCode maintains its own session state
Tools	OpenCode's built-in toolset
Best for	Coding agents, parallel workloads

terminal(
    command="opencode run 'Fix issue #1: add retry logic'",
    workdir="/tmp/issue-1",
    timeout=300
)

Monitoring background sessions:

process(action="poll", session_id="<id>")    # Check status
process(action="log", session_id="<id>")     # View output
process(action="submit", session_id="<id>", data="continue...")  # Send input
process(action="kill", session_id="<id>")    # Terminate

---

2. Kugetsu's Gitea-Based Communication Hub

Since Hermes has no native agent-to-agent protocol, Kugetsu uses Gitea as an asynchronous communication hub. This creates a permanent, auditable record.

┌──────────────────────────────────────────────────────────────┐
│  Hermes (Orchestrator / PM)                                  │
│  - terminal(opencode run ...) for Coding Agents              │
│  - delegate_task() for LLM subagents (max 3)                │
└──────────────────────────────────────────────────────────────┘
        │ (CLI subprocess)
        ▼
┌──────────────────────────┐
│  OpenCode Subagent      │
│  - Isolated git worktree│
│  - Posts to Gitea via   │
│    curl                 │
└──────────────────────────┘
        │ (Gitea API)
        ▼
┌──────────────────────────────────────────────────────────────┐
│  Gitea (Communication Hub)                                   │
│  - Issues as task tickets                                    │
│  - Comments as progress updates                              │
│  - PRs as code deliverables                                   │
└──────────────────────────────────────────────────────────────┘

Why Gitea?

• Permanent record — All agent work is logged in issue threads
• Human review — Users supervise via Gitea, not terminal
• No agent-to-agent protocol needed — Async by design
• PR-based code delivery — Clean merge workflow

---

3. Communication Protocols

3.1 PM → Human

Message	Channel
Task-split plans	Gitea issue comment
Final PR approval requests	Gitea PR
Blockers/escalations	Gitea issue comment

3.2 PM → Coding Agent

Message	Channel
Task assignment	Gitea issue comment (directs agent)
PR feedback	Gitea PR comment
Retry/abandon instructions	Gitea issue comment

3.3 Coding Agent → PM

Message	Channel
Task completion	Gitea issue comment + PR
PR status	Gitea PR
Blockers	Gitea issue comment
Findings/research	Gitea issue comment

3.4 Human → Coding Agent

Message	Channel
Inline PR feedback	Gitea PR comment
Priority override	Gitea issue (reassign/comment)
Task adjustment	Gitea issue comment

---

4. Practical Examples

4.1 Delegating a Research Task (delegate_task)

# In Hermes session
result = delegate_task(
    goal="""Work on Issue #4: Document Hermes Communication Patterns

Steps:
1. Read existing docs in ~/repositories/kugetsu/docs/
2. Identify message passing mechanisms used
3. Write findings to ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md
4. cat findings file
5. Post findings as Gitea issue comment

Gitea: git.example.com
Token: <YOUR_GITEA_TOKEN>
Repo: shoko/kugetsu
Issue: #4""",
    context="Focus on: delegate_task() vs terminal(opencode), Gitea hub pattern",
    toolsets=["terminal", "file"]
)

4.2 Delegating a Coding Task (terminal + opencode)

# Spawn OpenCode agent for issue #1
terminal(
    command="opencode run 'Fix issue #1: implement retry logic in api.py'",
    workdir="~/repositories/kugetsu",
    timeout=300
)
# Returns session_id for monitoring

4.3 Posting Findings to Gitea (from subagent)

# Write findings to temp file first (use KUGETSU_TEMP_DIR instead of /tmp)
cat > ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md << 'EOF'
# Research Findings for Issue #4

## Message Passing Mechanisms Identified

1. **delegate_task()** — Max 3 concurrent LLM subagents
2. **terminal(opencode run)** — No hard cap, CLI subprocess

## Gitea Hub Pattern

All agent communication flows through Gitea issues/PRs as the async record.
EOF

# Post as issue comment
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/4/comments" \
  -H "Authorization: token <YOUR_GITEA_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Kugetsu-Subagent/1.0" \
  -d @${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md \
  --max-time 30 \
  --retry 3 \
  --retry-delay 5

4.4 PM Assigns Task to Coding Agent (via Gitea)

# PM posts task assignment as issue comment
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/3/comments" \
  -H "Authorization: token <YOUR_GITEA_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "## Task Assignment\n\nAgent: coding-agent-1\n\n1. Explore ~/repositories/kugetsu/tools/parallel-capacity-test/\n2. Run the capacity test tool\n3. Document findings in /tmp/findings-3.md\n4. Post findings here\n\nDeadline: Before next PM review cycle"
  }'

4.5 Coding Agent Creates PR

# Create feature branch
git checkout -b fix/issue-3-capacity-test main

# ... do work ...

# Push and create PR
git push -u origin fix/issue-3-capacity-test

# Create PR via API
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/pulls" \
  -H "Authorization: token <YOUR_GITEA_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "fix #3: Add parallel capacity test tool",
    "body": "## Summary\n\nImplements parallel capacity testing for Hermes/OpenCode.\n\n## Testing\n\n- [ ] Tool runs without errors\n- [ ] Output logged to /tmp/capacity-test.log",
    "head": "fix/issue-3-capacity-test",
    "base": "main"
  }'

---

5. Known Limitations

Limitation	Impact	Workaround
delegate_task() max 3 cap	Can't spawn 4+ LLM subagents	Use terminal(opencode run) for coding agents
No native agent-to-agent protocol	Must use Gitea as hub	Async communication via issues/comments
OpenCode session management	Sessions can hang	Use timeout wrapper, kill stale sessions
Gitea rate limiting	Too-frequent API calls blocked	Add delays, use --retry

---

6. Issue State Machine

┌─────────────────────────────────────────────────────────────┐
│  Issue Lifecycle (Gitea-based async coordination)            │
└─────────────────────────────────────────────────────────────┘

OPEN ──► IN_PROGRESS (PM assigns to Coding Agent)
              │
              ▼
       AWAITING_FEEDBACK (Coding Agent posted findings)
              │
              ▼
         IN_PROGRESS (Human/PM replied, coding continues)
              │
              ▼
        COMPLETED (Coding Agent merged, PM closes)

---

7. Checklist (from Issue #4)

• Message passing mechanism identified
  • delegate_task() for LLM subagents (max 3)
  • terminal(opencode run) for parallel coding agents
  • Gitea as async communication hub
• Agent-to-agent communication tested
  • Hermes → OpenCode via terminal subprocess
  • OpenCode → Gitea via curl
• PM ↔ Coding Agent communication tested
  • PM assigns via Gitea issue comment
  • Coding Agent reports via Gitea PR/comment
• Examples documented
  • Research delegation (delegate_task)
  • Coding delegation (terminal + opencode)
  • Gitea posting patterns
  • PR creation workflow

---

References

• Hermes Setup Guide
• Kugetsu Architecture
• Subagent Workflow
• Hermes Agent GitHub
• Hermes Agent Docs

---

Status History

• 2026-03-30: Initial documentation — addresses all checklist items from issue #4