Hermes Agent Quick Start

Integrate AIWG with Hermes Agent — file-based deployment plus an optional MCP sidecar.

Hermes integrates like any other provider; the MCP sidecar is optional. As of v2026.5.13 (validated in #1527), aiwg use sdlc --provider hermes deploys artifacts and Hermes reaches AIWG through the discover-first CLI (aiwg discover / aiwg show) and the AGENTS.md / .hermes.md bridge — the same model as Claude Code and Codex, no MCP required. The Hermes → MCP → AIWG sidecar described below is an optional enrichment: any provider or system can connect to AIWG's MCP server, but none require it. Rules are delivered through generated AGENTS.md ### Rule: sections and the CLI aiwg show rule <name> fallback; MCP remains a richer optional path. The broader MCP modernization audit is tracked in #1533. The rest of this guide covers the optional MCP setup.

Architecture

When the optional MCP sidecar is enabled, the AIWG–Hermes seam is a single MCP connection. Hermes can sit upstream of any messaging platform or editor that Hermes itself supports — AIWG doesn't need to know about those upstream surfaces.

[Terminal / Telegram / Discord / Signal / Slack / Mattermost / Matrix / Zed (via ACP)]
                                  │
                                  ▼
                        Hermes Agent (host)
                          ├── Conversation, memory (MEMORY.md/USER.md), sessions
                          ├── Built-in tools (40+) and slash commands (65+)
                          ├── Skills (~/.hermes/skills/)
                          ├── /kanban (built-in agent task board)
                          ├── /handoff (cross-platform session transfer)
                          └── MCP connection
                                └── AIWG MCP Server (sidecar)
                                      └── .aiwg/ artifacts, workflows, templates

Hermes owns: conversation flow, persistent memory (MEMORY.md, USER.md), session history (state.db), user model, skills, in-session task tracking (kanban), platform handoff, scheduled tasks (/cron).

AIWG owns: workflow execution, artifact output in .aiwg/, template rendering, agent definitions, persistent SDLC artifacts.

When enabled, MCP is the seam. Coexistence with clear boundaries — not system unification. AIWG does not need to know which platform a Hermes turn originated from; Hermes does not need to know how AIWG produces an artifact.

Recommended Model Strategy

Two roles, two models. The parent agent handles conversation; coding tasks are delegated with a model override.

Conversation & Soul (parent agent)

Model	Size	Notes
`hermes3` ⭐	8B	Purpose-built for roleplay, persistent memory, character — ideal for soul features
`llama3.2:3b`	3B	Lightweight option; fast on CPU or low VRAM
`mistral:7b`	7B	Solid general-purpose conversation
`gemma2:9b`	9B	Strong nuanced dialogue, good at following persona instructions

Coding & Tool Calls (delegation model)

Qwen models have the best tool call accuracy of any open-weight family. For AIWG workflows involving structured output, function calling, or code generation, Qwen should be the first choice.

Model	Size	Notes
`qwen2.5-coder:14b` ⭐	14B	Best tool call accuracy + coding quality; recommended for AIWG workflows
`qwen2.5-coder:7b`	7B	Smaller Qwen coding variant; excellent tool calls, lower VRAM
`qwen3.5:9b`	9B	Vision + 256K context; strong structured output and tool calls (8GB VRAM)
`qwen3:8b`	8B	Strong structured output; supports thinking/non-thinking modes
`phi4-mini`	3.8B	Microsoft; compact, strong at structured reasoning
`deepseek-coder-v2:16b`	16B	Strong coding quality; needs 16GB+ VRAM

# Pull both recommended models
ollama pull hermes3
ollama pull qwen2.5-coder:14b

Configure delegation model in ~/.hermes/config.yaml under delegation.model: "ollama/qwen2.5-coder:14b" to route coding-heavy AIWG workflows to the coding model while keeping the parent conversation on hermes3.

Version compatibility

This guide is verified against Hermes Agent v0.13.0 (commit 942adf6, 2026-05). File:line references throughout this document are pinned to that version.

The AIWG integration depends on Hermes capabilities that have been stable since v0.4.0:

Feature	First stable
`hermes mcp` CLI (`add	remove
Real-time config reload (`/reload-mcp`)	v0.4.0
`${ENV_VAR}` substitution in config values	v0.4.0
Context-file loader priority `.hermes.md → AGENTS.md → CLAUDE.md`	v0.4.0
Curator (auto-archives stale skills on 7-day cycle)	v0.12.0
`hermes mcp login` (OAuth flows)	v0.13.0

If you're on a newer Hermes minor version and notice file:line drift, run tools/verify-hermes-citations.mjs (#1330) to check what's stale, or file an issue.

Prerequisites

Hermes Agent installed (installation guide)
AIWG installed (npm install -g aiwg)
Local models via Ollama: hermes3 (conversation, soul features) and qwen2.5-coder:14b (coding tasks)
A project directory with source code

Part 1: Verify Both CLIs Independently

Before connecting, confirm both work on their own.

Verify Hermes:

hermes --version
# Start a test conversation to confirm model connection
hermes chat "Hello, what model are you?"

Verify AIWG:

aiwg version
aiwg mcp info    # Confirm MCP server is available

Part 2: Connect AIWG to Hermes via MCP

Add the AIWG MCP server to Hermes configuration.

Option A — CLI add (v0.4.0+, recommended):

hermes mcp add aiwg --command aiwg --args mcp serve

This appends an entry to ~/.hermes/config.yaml automatically. Verified against Hermes v0.13.0 source hermes_cli/main.py:10911-10956: the mcp subcommand surface is serve | add | remove (rm) | list (ls) | test | configure (config) | login — no install subcommand. --args is nargs="*", so pass tokens space-separated (mcp serve), not comma-separated.

In an active chat, run /reload-mcp after adding to pick up the new server without restarting the session.

Option B — Manual config edit:

Edit ~/.hermes/config.yaml:

mcp_servers:
  aiwg:
    command: "aiwg"
    args: ["mcp", "serve"]

After saving, run /reload-mcp in your active Hermes chat to apply.

Why this is lean by default: AIWG's MCP server exposes 16 core tools on default startup — discovery (discover, *-list/*-show pairs for skill/command/rule/agent/template), the allow-listed command-run, plus the artifact read/write surface. Schema footprint stays under 2.5K tokens.

Beyond the core, 45 additional tools are available as opt-in toolsets controlled by the AIWG_MCP_TOOLSETS env var or the --toolsets flag:

# Enable specific toolsets at startup
AIWG_MCP_TOOLSETS=memory,kb,ralph aiwg mcp serve

# Or via CLI flag
aiwg mcp serve --toolsets=memory,kb,ralph

# Or everything (61 tools total, including deprecated compatibility tools)
aiwg mcp serve --toolsets=all

Known toolsets: memory, kb, research (provenance + research-store), activity-log, index, ralph, mc, ops. The core set is always on; listing it explicitly is harmless. Unknown toolsets log a warning and are skipped (non-fatal).

Tool name mangling

Hermes prefixes every MCP tool name with mcp_<server-name>_ and sanitizes non-alphanumeric characters to _. So AIWG's tool command-run becomes mcp_aiwg_command_run in the Hermes tool registry. The mangling regex is [^A-Za-z0-9_] → _; hyphens and dots both collapse to underscores. The 9-char mcp_aiwg_ prefix is included in the 64-char tool-name budget, so AIWG tool names stay ≤30 chars locally to leave headroom for the prefix.

Verify the server registered correctly:

hermes chat "What AIWG tools are available?"

The default core toolset registers 16 tools; with all toolsets enabled Hermes sees 61, including deprecated compatibility tools. If your output shows only the legacy 5 (workflow-run, artifact-read, artifact-write, template-render, agent-list), the AIWG installation is stale — run aiwg refresh and /reload-mcp in your active chat.

Part 3: Add Routing Guidance (AGENTS.md)

Create an AGENTS.md at your project root that tells Hermes when to call AIWG.

First-match-wins context loading (verified against Hermes v0.13.0 agent/prompt_builder.py:1417-1456). Hermes loads exactly one project-context file per turn, by priority:

.hermes.md / HERMES.md (walks up to git root)

AGENTS.md / agents.md (cwd only, no walk)

CLAUDE.md / claude.md (cwd only, no walk)

.cursorrules / .cursor/rules/*.mdc (cwd only)

The code comment is explicit: "Priority (first found wins — only ONE project context type is loaded)." Earlier docs that suggested Hermes loads AGENTS.md and CLAUDE.md together were aspirational. AIWG always emits a .hermes.md twin file (#1239 / #1242), so when this integration is installed, AGENTS.md and CLAUDE.md never load on Hermes turns — they remain valid context files for Claude Code, Codex, etc., but are silent on Hermes.

flowchart TB
  TURN([Hermes turn starts])
  TURN --> CWD[Get cwd]
  CWD --> WALK[Walk up to git root<br/>looking for .hermes.md or HERMES.md]

  WALK --> H{".hermes.md or<br/>HERMES.md found?"}
  H -->|Yes| HLOAD[Load .hermes.md<br/>STOP — winner]
  H -->|No| A{"AGENTS.md or<br/>agents.md in cwd?"}
  A -->|Yes| ALOAD[Load AGENTS.md<br/>STOP — winner]
  A -->|No| C{"CLAUDE.md or<br/>claude.md in cwd?"}
  C -->|Yes| CLOAD[Load CLAUDE.md<br/>STOP — winner]
  C -->|No| R{".cursorrules or<br/>.cursor/rules/*.mdc?"}
  R -->|Yes| RLOAD[Load .cursorrules<br/>STOP — winner]
  R -->|No| NONE[No project context loaded]

  HLOAD --> CAP[Cap at 20,000 chars<br/>head/tail truncate above]
  ALOAD --> CAP
  CLOAD --> CAP
  RLOAD --> CAP
  CAP --> PROMPT[Inject into system prompt<br/>this turn]
  NONE --> PROMPT

  classDef winner fill:#d4edda
  class HLOAD,ALOAD,CLOAD,RLOAD winner

Each context source is capped at 20,000 chars (CONTEXT_FILE_MAX_CHARS in v0.13.0 agent/prompt_builder.py:824). Above that, head/tail truncation kicks in with a [...truncated] marker. The thin .hermes.md AIWG emits (~450 chars) is well under the cap, and the deployed AGENTS.md (which inlines top-7 CRITICAL rule priming as ### Rule: sections) is currently well below the hard cap.

Token budget reminder: even within the 20K cap, Hermes loads context in full on every turn. Keep routing guidance compact — AIWG's default .hermes.md is ~230 tokens.

Create AGENTS.md in your project root:

# AIWG Integration

AIWG connected through file-based deployment. Use `aiwg discover` and
`aiwg show <type> <name>` for the on-demand catalog. Optional MCP tools are
available via `aiwg mcp serve`: discover, skill-list/show, command-list/show/run,
rule-list/show, agent-list/show, template-list/render/show, artifact-read/write.
Opt-in via AIWG_MCP_TOOLSETS=memory,kb,ralph,mc,ops,...

## Route to AIWG When

- Structured artifacts needed (requirements, architecture, test plans, risk registers)
- Multi-step workflows with phase gates or checkpoints
- Template-driven output that persists across sessions

Handle in Hermes directly: one-off questions, short tasks, conversation.

## Memory Boundary

When AIWG returns an artifact: store path + one-sentence summary in MEMORY.md.
Do NOT copy artifact body text into memory. Reference, don't replicate.

Use `delegate_task(goal="...", context="...")` for AIWG workflows.
Child agents automatically exclude context files and memory.

## Artifact Store (.aiwg/)

Fetch on demand via `artifact-read`:
- `requirements/` — use cases, user stories
- `architecture/` — SAD, ADRs
- `planning/` — phase plans
- `testing/` — test strategy
- `security/` — threat models

A template is available at agentic/code/frameworks/sdlc-complete/templates/hermes/AGENTS.md.aiwg-template.

Part 4: Run Your First Workflow

Ask Hermes to create a structured artifact that routes through AIWG.

Example prompt:

Create an architecture decision record for choosing PostgreSQL over MongoDB
for our user service. Save it as a persistent AIWG artifact.

What should happen:

Hermes reads the routing rules in .hermes.md (or AGENTS.md as fallback per Part 3)
Hermes calls mcp_aiwg_command_run (with the appropriate flow command) or mcp_aiwg_artifact_write via MCP
AIWG creates the artifact in .aiwg/architecture/
Hermes receives the result and stores a reference

Verify:

ls .aiwg/architecture/
# Should show the new ADR file

Composing with Hermes session features

Once Part 4 works, you can chain AIWG calls with Hermes's session-management commands. None of these require AIWG configuration — they work on top of the MCP seam.

Hand the session off to mobile (/handoff <platform> — landed in Hermes #23400, source: gateway/run.py:_process_handoff):

You: Create the inception use cases for our auth feature, then I'll review on the train.
Hermes: <runs aiwg-orchestrate to file UC-001..UC-004 in .aiwg/requirements/>
You: /handoff telegram
Hermes: ✓ Session transferred. Continue from your phone.

The chat continues on Telegram (or Discord, Signal/SMS via Twilio, Mattermost, Matrix, etc. — any gateway platform Hermes supports). Mobile messages route back to the same Hermes session, which still holds the AIWG MCP connection.

Run an AIWG workflow in the background (/background <prompt> aliases /bg, /btw):

/bg use aiwg-orchestrate to draft the SAD for the payment service

The prompt runs without blocking your foreground chat. Use /agents (alias /tasks) to check progress.

Set a standing AIWG goal (/goal "<text>"):

/goal Complete SDLC inception phase by EOW — file all use cases, ADRs, risk register

Hermes carries this across turns and proactively triggers AIWG workflows toward the goal. Pause/resume/clear with /goal pause | resume | clear | status.

Part 5: State Boundaries

Hermes and AIWG each own distinct state. Do not synchronize them.

Owned by Hermes	Owned by AIWG
`~/.hermes/memories/MEMORY.md`	`.aiwg/requirements/`
`~/.hermes/memories/USER.md`	`.aiwg/architecture/`
`~/.hermes/state.db` (sessions)	`.aiwg/planning/`
`~/.hermes/skills/`	`.aiwg/testing/`
Conversation context	`.aiwg/security/`

The contract: Exchange references, not synchronized databases. Hermes stores a path and summary; AIWG stores the full artifact.

Part 6: aiwg-orchestrate Skill (auto-installed)

After Part 4, AIWG ships a convenience skill that uses delegate_task to keep AIWG workflows out of the parent context.

Why: Direct MCP calls add 3,000-8,000 tokens to the parent context per workflow. delegate_task reduces this to ~200 tokens — a 95% reduction.

#1242 update: Since 2026.5.0+ aiwg use --provider hermes automatically installs this skill at ~/.hermes/skills/aiwg-orchestrate/SKILL.md on first deploy. The install is idempotent — your edits are preserved across subsequent aiwg use runs. The Hermes provider's prune-stale-skills sweep treats aiwg-orchestrate as part of the kernel set so it survives reruns.

API note (verified v0.13.0): delegate_task automatically excludes context files (AGENTS.md, SOUL.md, .hermes.md) and memory (MEMORY.md, USER.md) from child agents — this is hardcoded behavior, not a per-call parameter. Earlier AIWG docs that suggested skip_context_files=True, skip_memory=True kwargs were incorrect (those parameters do not exist on the signature; the behavior is automatic). The delegation model is configured globally in ~/.hermes/config.yaml under delegation.model.

To verify the install: ls ~/.hermes/skills/aiwg-orchestrate/SKILL.md

To re-install (after deletion or to reset to the shipped version): rm -rf ~/.hermes/skills/aiwg-orchestrate && aiwg use sdlc --provider hermes

Manual creation (if for some reason auto-install was skipped — e.g. read-only home dir): create ~/.hermes/skills/aiwg-orchestrate/SKILL.md with the body below.

---
name: aiwg-orchestrate
description: Route structured artifact work to AIWG workflows via MCP
version: 1.0.0
author: aiwg
license: MIT
metadata:
  hermes:
    tags: [aiwg, sdlc, artifacts, delegation, mcp]
---

## When to Use

Use when the user asks for a requirements document, architecture decision,
test plan, or any structured artifact that persists in .aiwg/.

## Procedure

1. Confirm the task needs a persistent AIWG artifact
2. Use delegate_task to isolate the AIWG interaction:
   delegate_task(
       goal="Run AIWG workflow for [description]",
       context="Project: [name]. Save artifact to .aiwg/[category]/[filename].md"
   )
   Note: Child agents automatically exclude context files and memory.
   The delegation model is configured in config.yaml under delegation.model.
3. Store artifact path + one-sentence summary in MEMORY.md
4. Report result to user

## Memory Rule

Store: [date] Created [type] at [path]: [summary]
Never store artifact body content in memory.

## Verification

Confirm artifact exists under .aiwg/ and summary is accurate.

A template is available at agentic/code/frameworks/sdlc-complete/templates/hermes/skills/aiwg-orchestrate/SKILL.md.

Part 7: Context Budget Reference

Understanding the token budget helps configure Hermes for local hardware.

With lean AGENTS.md (recommended)

AIWG's MCP server exposes exactly 5 tools — no more, no less. Two variables affect overhead: AGENTS.md size and the AIWG kernel-skill set installed at ~/.hermes/skills/.

Component	Tokens
Hermes system prompt	~1,500
AGENTS.md (≤1,000 chars; AIWG-default thin pointer is ~580 chars / ~145 tokens)	~250
MEMORY.md	~800
USER.md	~500
AIWG MCP schema (5 tools)	~3,000
AIWG kernel skills at `~/.hermes/skills/` (6 skills post-rc.14 pivot)	~1,200
`aiwg-orchestrate` skill (auto-installed, #1242)	~150
Total overhead	~7,400
Available for conversation (32K context)	~25,368 (77%)

#1241 update: After aiwg use --provider hermes, six AIWG kernel skills (aiwg-doctor, aiwg-help, aiwg-language-map, aiwg-refresh, aiwg-status, aiwg-utils-quickref) deploy to ~/.hermes/skills/. Hermes loads these natively per skill; budget rough estimate ~200 tokens each. Subtract this row if you remove the AIWG addon or use only the MCP surface.

#1242 update: The aiwg-orchestrate skill (~150 tokens) is auto-installed at ~/.hermes/skills/aiwg-orchestrate/. Despite the modest schema cost, using it for AIWG workflows nets a large savings — direct MCP calls would add 3,000-8,000 tokens per workflow to the parent context; delegate_task via this skill keeps that cost in the child agent and returns a ~200-token summary to the parent. Net positive after the first workflow.

Worst-case: large `.hermes.md` near the 20K-char cap

Hermes loads exactly one project-context file per turn (priority order documented in Part 3). Because AIWG always emits a .hermes.md at project root, AGENTS.md and CLAUDE.md never load on Hermes turns when this integration is installed — they remain valid for Claude Code, Codex, and other providers. So the worst case isn't "AGENTS.md + CLAUDE.md stacked" but "operator hand-edited .hermes.md to pack as much as possible up to the 20K-char head/tail-truncation cap."

Component	Tokens
Hermes system prompt	~1,500
`.hermes.md` at the 20K-char cap (head/tail truncation point)	~5,000
MEMORY.md	~800
USER.md	~500
AIWG MCP schema (5 tools)	~3,000
AIWG kernel skills	~1,200
`aiwg-orchestrate` skill	~150
Total overhead	~12,150
Available for conversation (32K context)	~20,618 (63%)

The compression threshold fires at 50% of context by default (30% recommended for local models). Note that CONTEXT_FILE_MAX_CHARS = 20,000 in v0.13.0 agent/prompt_builder.py:824 bounds the worst case — even a runaway .hermes.md cannot exceed 20K chars in the prompt because Hermes head/tail-truncates above that with a [...truncated] marker. Keep .hermes.md lean by default; if you need a longer routing guide, write the bulk to a file Hermes can fetch on demand via artifact-read.

Recommended compression config for 12GB VRAM

compression:
  enabled: true
  threshold: 0.30
  summary_model: "ollama/qwen2.5-coder:7b"
  summary_provider: "custom"
  summary_base_url: "http://localhost:11434/v1"

Part 8: Advanced — Delegation Model Configuration

After the basic integration is stable, configure the delegation model for optimal AIWG workflow performance.

Add delegation config to ~/.hermes/config.yaml:

delegation:
  model: "ollama/qwen2.5-coder:14b"    # Coding model for structured output
  max_iterations: 50                     # Max tool rounds per child agent

This routes AIWG workflows delegated via delegate_task to a coding-optimized model while the parent stays on hermes3 for conversation. Only configure after Part 4 is working reliably.

Hermes CLI surface (v0.13.0): hermes tools interactively manages MCP tool configuration; hermes mcp installs new MCP servers (now with OAuth via hermes mcp login, added in v0.13.0). See hermes_cli/main.py:10911-10956 for the verified mcp subcommand list.

Part 9: Validation Checklist

Run these checks to confirm the integration is working:

Check	Command / Action	Expected
Connectivity	Ask Hermes "list AIWG tools"	5 tools listed
Routing	Ask a one-off question	Hermes answers directly (no AIWG call)
Routing	Ask for a requirements document	Routes to AIWG via MCP
Artifact write	Check `.aiwg/` after workflow	New artifact file exists
Artifact read	Ask Hermes to read the artifact	Uses `artifact-read`, not memory
Memory boundary	Check `~/.hermes/memories/MEMORY.md`	Contains path + summary, not body
Failure mode	Stop `aiwg mcp serve`, ask for artifact	Hermes handles gracefully

Hermes Capabilities Reference

A compact catalog of Hermes v0.4.0+ surface area that interacts with the AIWG seam. Citations point at the Hermes Agent source so future drift is detectable. None of these require AIWG-side code changes — they compose with the existing MCP integration.

`/kanban` — built-in agent task board

Hermes ships a multi-profile collaboration board with task lifecycle: todo → ready → running → blocked → done → archived. 15-verb subcommand surface (list, show, create, assign, link, unlink, claim, comment, complete, block, unblock, archive, …).

Source: hermes_cli/kanban.py, hermes_cli/kanban_db.py, design spec docs/hermes-kanban-v1-spec.pdf.

AIWG composition note: /kanban is in-session task tracking; AIWG is for persistent SDLC artifacts. Use /kanban to coordinate the agent's day-to-day work flow inside one session. Use AIWG (workflow-run, artifact-write) to file durable use cases, architecture decisions, test plans, etc. into .aiwg/. They compose well: a kanban task ("Draft auth use cases") can call aiwg-orchestrate to actually produce the artifact, then mark itself complete with the artifact path in the comment.

`/handoff <platform>` — cross-platform session transfer

Transfer an active Hermes session to Telegram, Discord, Signal/SMS, Mattermost, Matrix, Slack, or any other supported platform. Recently landed in Hermes #23400.

Source: gateway/run.py:_process_handoff, hermes_cli/commands.py:178 area.

AIWG composition note: AIWG sessions running in a Hermes terminal can be handed to mobile. The MCP connection stays attached to the same Hermes session, so AIWG state survives the handoff. Useful for long-running SDLC workflows where the operator needs to step away.

ACP adapter — Agent Communication Protocol

Hermes can be exposed as an ACP agent. ACP is Zed's editor-agent protocol, enabling chains like Zed → ACP → Hermes → MCP → AIWG.

Source: acp_adapter/server.py, acp_adapter/__init__.py.

AIWG composition note: AIWG is transitively reachable from Zed via Hermes-as-ACP-agent. No AIWG configuration needed — the same aiwg use --provider hermes setup works.

`/agents` (alias `/tasks`) — running-task inspector

Show active agents and running tasks spawned via delegate_task.

Source: hermes_cli/commands.py CommandDef("agents", …, aliases=("tasks",)).

AIWG composition note: When aiwg-orchestrate dispatches a child agent via delegate_task, monitor it with /agents to see progress, model usage, and elapsed time. Useful during long AIWG workflows.

`/goal <text>` — standing goal across turns

Hermes maintains a goal that persists across turns until achieved, paused, or cleared. Subcommands: pause | resume | clear | status.

Source: hermes_cli/commands.py CommandDef("goal", …).

AIWG composition note: A standing goal like "Complete SDLC inception" can pair with AIWG workflows — Hermes proactively triggers aiwg-orchestrate calls toward the goal across turns without re-prompting.

`/cron` — scheduled tasks

Hermes has its own scheduled-task surface, separate from aiwg schedule.

Source: cron/ directory in the Hermes repo.

AIWG composition note: Boundary recommendation —

Hermes /cron: schedule recurring conversational tasks (daily standup digest, periodic check-ins, polling external systems through Hermes tools).
aiwg schedule: schedule recurring AIWG workflows that produce SDLC artifacts (weekly retrospective reports, monthly architecture reviews).

The Steward's capability matrix routes operators to the right tool — when in doubt, ask the Steward.

`/snapshot` and `/rollback` — Hermes filesystem checkpoints

Hermes can create and restore filesystem snapshots of its config and state. /rollback [number] restores by checkpoint number.

Source: hermes_cli/commands.py CommandDef("snapshot"/"rollback").

AIWG composition note: Different scope from AIWG's .aiwg/working/ artifacts. Hermes snapshots cover Hermes's own state (configs, session db); AIWG checkpoints cover SDLC artifacts. They don't overlap — operators don't need to coordinate them.

`/background` (alias `/bg`, `/btw`) — fire-and-forget prompts

Run a prompt without blocking the foreground chat.

Source: hermes_cli/commands.py CommandDef("background", …, aliases=("bg", "btw")).

AIWG composition note: Pairs naturally with aiwg-orchestrate for fire-and-forget workflows: "/bg use aiwg-orchestrate to draft the SAD" runs the workflow concurrently, monitor with /agents.

Gateway platforms — multi-platform reach

Discord, Slack, Telegram (incl. DM topics), DingTalk, Signal/SMS via Twilio, Mattermost, Matrix, Webhook, OpenAI-compatible API server.

Source: gateway/platforms/ directory.

AIWG composition note: AIWG workflows are platform-agnostic from Hermes's perspective — the same .aiwg/ artifacts produced via MCP work whether the conversation is happening in terminal, Discord, or via SMS. The thin .hermes.md we ship is loaded the same way regardless of platform.

Plugin system

Hermes hosts plugins at plugins/ (kanban, memory, observability, disk-cleanup, google_meet, image_gen, model-providers, hermes-achievements, context_engine).

Source: plugins/ directory.

AIWG composition note: AIWG ships as an MCP server, not a Hermes plugin. The MCP-server choice is intentional — same AIWG code works against any MCP host (Claude Desktop, Codex, Hermes, future MCP clients) with no per-host plugin work. A plugins/aiwg/ would be a separate architectural choice, not pursued today.

What This Integration Is NOT

Not aiwg use sdlc --provider hermes — there is no hermes.mjs provider
Not mirroring .aiwg/ into Hermes memory — exchange references only
Not a TypeScript-to-Python bridge — MCP is the seam
Not a replacement for Hermes's built-in tools — AIWG adds structured workflows on top

Troubleshooting

AIWG tools not visible in Hermes:

Verify aiwg mcp serve runs successfully on its own
Check ~/.hermes/config.yaml syntax (YAML is whitespace-sensitive)
Ensure aiwg is in your PATH

Context filling up too fast:

Check AGENTS.md character count (wc -c AGENTS.md) — keep under 1,000
AIWG MCP server exposes only 5 tools (~3,000 tokens) — check other MCP servers for bloat
Use delegate_task for AIWG workflows to isolate context cost
Lower compression threshold to 0.30

Artifacts not appearing in .aiwg/:

Ensure AIWG is initialized in the project (aiwg use sdlc)
Check that artifact-write is in the tool whitelist
Verify the working directory matches the project root

Related Resources

Hermes Agent documentation
AIWG MCP server reference
Local models guide
agentskills.io skill standard
Integration plan: .aiwg/planning/hermes-aiwg-integration-plan.md
Context research: .aiwg/planning/hermes-context-research.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hermes Agent Quick Start

Architecture

Recommended Model Strategy

Conversation & Soul (parent agent)

Coding & Tool Calls (delegation model)

Version compatibility

Prerequisites

Part 1: Verify Both CLIs Independently

Part 2: Connect AIWG to Hermes via MCP

Tool name mangling

Part 3: Add Routing Guidance (AGENTS.md)

Part 4: Run Your First Workflow

Composing with Hermes session features

Part 5: State Boundaries

Part 6: aiwg-orchestrate Skill (auto-installed)

Part 7: Context Budget Reference

With lean AGENTS.md (recommended)

Worst-case: large `.hermes.md` near the 20K-char cap

Recommended compression config for 12GB VRAM

Part 8: Advanced — Delegation Model Configuration

Part 9: Validation Checklist

Hermes Capabilities Reference

`/kanban` — built-in agent task board

`/handoff <platform>` — cross-platform session transfer

ACP adapter — Agent Communication Protocol

`/agents` (alias `/tasks`) — running-task inspector

`/goal <text>` — standing goal across turns

`/cron` — scheduled tasks

`/snapshot` and `/rollback` — Hermes filesystem checkpoints

`/background` (alias `/bg`, `/btw`) — fire-and-forget prompts

Gateway platforms — multi-platform reach

Plugin system

What This Integration Is NOT

Troubleshooting

Related Resources

FilesExpand file tree

hermes-quickstart.md

Latest commit

History

hermes-quickstart.md

File metadata and controls

Hermes Agent Quick Start

Architecture

Recommended Model Strategy

Conversation & Soul (parent agent)

Coding & Tool Calls (delegation model)

Version compatibility

Prerequisites

Part 1: Verify Both CLIs Independently

Part 2: Connect AIWG to Hermes via MCP

Tool name mangling

Part 3: Add Routing Guidance (AGENTS.md)

Part 4: Run Your First Workflow

Composing with Hermes session features

Part 5: State Boundaries

Part 6: aiwg-orchestrate Skill (auto-installed)

Part 7: Context Budget Reference

With lean AGENTS.md (recommended)

Worst-case: large .hermes.md near the 20K-char cap

Recommended compression config for 12GB VRAM

Part 8: Advanced — Delegation Model Configuration

Part 9: Validation Checklist

Hermes Capabilities Reference

/kanban — built-in agent task board

/handoff <platform> — cross-platform session transfer

ACP adapter — Agent Communication Protocol

/agents (alias /tasks) — running-task inspector

/goal <text> — standing goal across turns

/cron — scheduled tasks

/snapshot and /rollback — Hermes filesystem checkpoints

/background (alias /bg, /btw) — fire-and-forget prompts

Gateway platforms — multi-platform reach

Plugin system

What This Integration Is NOT

Troubleshooting

Related Resources

Worst-case: large `.hermes.md` near the 20K-char cap

`/kanban` — built-in agent task board

`/handoff <platform>` — cross-platform session transfer

`/agents` (alias `/tasks`) — running-task inspector

`/goal <text>` — standing goal across turns

`/cron` — scheduled tasks

`/snapshot` and `/rollback` — Hermes filesystem checkpoints

`/background` (alias `/bg`, `/btw`) — fire-and-forget prompts