opencode-hermes

Progressive-disclosure reflector for OpenCode. Hermes automatically analyzes your conversations to discover reusable patterns, workflows, and domain knowledge, then generates AI skills (SKILL.md) and behavioral rules — turning hard-won experience into permanent team knowledge.

Hermes never installs anything directly. All proposals go to a staging directory for human review before activation.

Features

🔍 Two reflection modes

Mode	Trigger	Scope
Manual	/reflect or "reflect"	Current session — ad-hoc analysis
Batch	Weekly automatic	All idle sessions — cross-session pattern discovery

📦 What it produces

• Skills (SKILL.md) — Step-by-step workflows and domain expertise. Agents load these automatically when conditions match.
• Rules — Concise behavioral principles and environment facts. Staged for human review.
• Staging workflow — All proposals land in ~/.config/opencode/hermes-staging/ for you to approve or reject via the /skill-refresh command.

🧠 Knowledge classification

Hermes categorizes findings into four types:

Type	Classification	Output
Workflow	"How to do X" — step-by-step procedures	SKILL.md
Domain Knowledge	"How X works" — in-depth expertise	SKILL.md
Context Knowledge	"In this env, X is true" — environment facts	Rule
Universal Principle	"Always / Never do X" — behavioral rules	Rule

Installation

1. Add the plugin

{
  "plugin": ["opencode-hermes"]
}

2. Register the slash commands (required)

Add command entries for /reflect and /skill-refresh:

{
  "plugin": ["opencode-hermes"],
  "command": {
    "reflect": {
      "template": "Call hermes_nudge_now to start background reflection.",
      "description": "Analyze conversation for patterns and auto-create skills"
    },
    "skill-refresh": {
      "template": "逐 group 处理 hermes-staging/ 中各待审项。",
      "description": "评估 hermes-staging 待审 proposals"
    }
  }
}

Restart OpenCode after making changes.

Configuration (optional)

Create ~/.config/opencode/hermes.json to override the reflection model:

{
  "reflection_model": {
    "providerID": "anthropic",
    "modelID": "claude-sonnet-4-5",
    "variant": "max"
  }
}

If not configured, Hermes uses the session's current model.

Usage

Manual reflection

/reflect

Hermes performs a two-step analysis:

1. Step 1 — Lightweight scan: Quick pass to identify candidate rounds
2. Step 2 — Deep analysis: Detailed extraction of skills and rules

Results appear as a toast notification and proposals land in hermes-staging/.

Review proposals

/skill-refresh

This walks you through staged proposals grouped by batch, lets you rate each one, and decide whether to keep, delete, or merge.

Weekly batch

Hermes automatically runs a weekly batch scan of all completed sessions that have been idle for 48+ hours. Results appear as a Windows dialog (or terminal notification) when ready.

Data files

File / Directory	Purpose
~/.config/opencode/hermes-state.json	Persistent state (analyzed rounds, session skills, logs)
~/.config/opencode/hermes.json	Optional model config
~/.config/opencode/hermes-staging/	Staging area for human review

How it works

1. Tracking: Hermes listens to chat.message events to track the active session
2. Analysis pipeline: When triggered, it fetches session messages, parses them into structured rounds (user turns → tool calls → assistant responses), and runs a two-pass AI analysis
3. Background sessions: Analysis runs in dedicated background sessions (<title>#reflect) so it doesn't pollute your main conversation
4. Deduplication: Only new rounds since last analysis are processed each time
5. Staging: Results are written to hermes-staging/ organized by date and batch, never installed automatically

Limitations

• Requires OpenCode SDK with client.session.* API access
• Batch mode is Windows-only for the completion popup (can be disabled by removing the spawn block)
• Model dependent: Quality of analysis depends on the reflection model's reasoning capability

License

MIT