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

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

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

**Monitoring background sessions:**
```python
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)

```python
# 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 /tmp/findings-4.md
4. cat /tmp/findings-4.md
5. Post findings as Gitea issue comment

Gitea: https://git.fbrns.co
Token: 4c85c4c92637b33230a1f550287e63a0d1cef7a0
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)

```python
# 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)

```bash
# Write findings to temp file first
cat > /tmp/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 "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/4/comments" \
  -H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Kugetsu-Subagent/1.0" \
  -d @/tmp/findings-4.md \
  --max-time 30 \
  --retry 3 \
  --retry-delay 5
```

### 4.4 PM Assigns Task to Coding Agent (via Gitea)

```bash
# PM posts task assignment as issue comment
curl -X POST "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/issues/3/comments" \
  -H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
  -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

```bash
# 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 "https://git.fbrns.co/api/v1/repos/shoko/kugetsu/pulls" \
  -H "Authorization: token 4c85c4c92637b33230a1f550287e63a0d1cef7a0" \
  -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)

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

---

## References

- [Hermes Setup Guide](./hermes-setup.md)
- [Kugetsu Architecture](./kugetsu-architecture.md)
- [Subagent Workflow](./SUBAGENT_WORKFLOW.md)
- [Hermes Agent GitHub](https://github.com/nousresearch/hermes-agent)
- [Hermes Agent Docs](https://hermes-agent.nousresearch.com)

---

## Status History

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