README
¶
Herrscher
Herrscher is a self-hosted harness for running fleets of AI coding agents — durable sessions with persistent memory, each in its own git worktree, reachable from Discord or your terminal.
Agents survive restarts, learn across sessions, and delegate work to each other across model vendors.
Docs live in Herrscherd/herrscher-docs; page slugs below are given as inline code.
What it gives you
- Durable sessions — each session is a channel + an agent + an isolated git worktree, supervised and restarted automatically; the conversation resumes from the backend's own resume token. →
architecture/durable-agents,architecture/session-lifecycle - Persistent memory — an auto-provisioned Obsidian vault, scoped shared-per-project and private-per-agent, recalled before every turn. →
architecture/memory - Learning — opt-in consolidation of a session's work into scoped nodes, with aging, semantic merge, cross-agent promotion, and fully reversible archiving. →
architecture/learning - Multi-agent delegation across vendors — an agent ends a turn with a
⟢trailer to delegate, fan out, route, merge, or hand off; workers inherit their agent's vendor, so one run can mix Claude, Codex, and Cursor. →architecture/coordination - Any front end — Discord, the in-tree terminal TUI, or your own gateway plugin behind the same neutral port. →
plugins/gateway,plugins/terminal
Also: cross-backend skills (SKILL.md works on every backend) → guide/skills, and per-node memory budgets → guide/budgets.
Install & run
Requires Go 1.25+.
git clone https://github.com/Herrscherd/herrscher.git
cd herrscher
go build -o herrscher . # the only binary; plugins are compiled in
./herrscher init # compose the plugin stack, seed config
./herrscher # opens the terminal TUI
No Discord token is needed for the terminal path — the in-tree terminal gateway is a first-class gateway, so you can create, drive, and resume sessions entirely from your shell. A Discord token is only required if you enable the Discord gateway. For a boot-started service, an Arch PKGBUILD, and the rest, see guide/installation and guide/service.
Plugins
Plugins compile into the binary (the xcaddy pattern): add a blank import, rebuild.
| Category | Port | Official plugin |
|---|---|---|
| Gateway | Gateway |
herrscher-discord-gateway, in-tree terminal |
| Backend | Backend |
herrscher-claude-backend, herrscher-codex-backend, herrscher-cursor-backend |
| Memory | Memory |
herrscher-obsidian-memory |
| Orchestrator | Orchestrator |
herrscher-orchestrator |
Architecture
Hexagonal. herrscher-contracts is the authority: it declares the ports and neutral types, with zero platform mechanics. Every dependency arrow points inward at it — the agnostic domain (core) depends on no edge, the edges depend on no core, and only the host's wiring file ever sees two concrete types at once. Purity tests (TestHostPurity, TestCorePurity, TestCoreNamesNoConcretePlatform) fail the build if a concrete platform leaks in. → architecture/hexagonal
Documentation
Full docs: Herrscherd/herrscher-docs — overview/introduction, architecture/hexagonal, plugins/model, guide/quickstart, reference/env.
A note on history
The platform grew out of a Go monolith that bridged Discord to a local Claude. Herrscher is that monolith decomposed along its natural seams — channel, model, domain — so each can evolve independently. The contract shapes were chosen deliberately to make the eventual transport change (in-process → NATS/gRPC) a detail, not a rewrite.
Documentation
¶
Overview ¶
Command herrscher is the composition root and CLI for a Herrscher host: it wires the registered gateway/backend/orchestrator plugins and the core into one binary. It exposes the always-on daemon (serve/bridge/service), the session verbs, and the host self-management verbs (init/plugin/update/install). It stays gateway-agnostic: it never imports a concrete chat adapter (dctl lives in the discord-gateway plugin), driving platforms only through the contracts gateway port. Output is deliberately minimal so an LLM driving it spends few tokens.
Config (env): the active gateway plugin declares its own required vars (the discord gateway needs DISCORD_BOT_TOKEN); the host resolves them generically.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
core
|
|
|
bridge
Package bridge implements the bridge as a pure backend runner: the daemon hub owns all gateway I/O and feeds inputs over a control socket, the bridge runs the injected backend per turn and emits events back.
|
Package bridge implements the bridge as a pure backend runner: the daemon hub owns all gateway I/O and feeds inputs over a control socket, the bridge runs the injected backend per turn and emits events back. |
|
cli
Package cli is the native, channel-agnostic command dispatcher.
|
Package cli is the native, channel-agnostic command dispatcher. |
|
config
Package config loads the daemon's declarative defaults from a user-authored ~/.config/herrscher/config.json.
|
Package config loads the daemon's declarative defaults from a user-authored ~/.config/herrscher/config.json. |
|
envx
Package envx resolves the daemon's environment variables under the HERRSCHER_ prefix.
|
Package envx resolves the daemon's environment variables under the HERRSCHER_ prefix. |
|
internal/agent
Package agent models a durable companion agent: a persistent home directory holding the agent's persona (SOUL.md), its MCP server declaration (mcp.json), and its Claude settings (settings.json).
|
Package agent models a durable companion agent: a persistent home directory holding the agent's persona (SOUL.md), its MCP server declaration (mcp.json), and its Claude settings (settings.json). |
|
internal/control
Package control is the bridge's control channel: a per-session local socket (or named pipe on Windows) the daemon hub accepts on and the bridge dials.
|
Package control is the bridge's control channel: a per-session local socket (or named pipe on Windows) the daemon hub accepts on and the bridge dials. |
|
internal/forge
Package forge wraps the gh / glab CLIs to list and clone remote repos.
|
Package forge wraps the gh / glab CLIs to list and clone remote repos. |
|
internal/instanceid
Package instanceid resolves and validates the per-daemon instance identifier used to namespace global resources (git branches, worktree paths, channel titles) so multiple daemons can share one gateway home.
|
Package instanceid resolves and validates the per-daemon instance identifier used to namespace global resources (git branches, worktree paths, channel titles) so multiple daemons can share one gateway home. |
|
internal/metrics
Package metrics is a lightweight in-process metrics registry (atomic counters plus a bounded latency reservoir, stdlib only).
|
Package metrics is a lightweight in-process metrics registry (atomic counters plus a bounded latency reservoir, stdlib only). |
|
internal/obs
Package obs is the operator-observability seam.
|
Package obs is the operator-observability seam. |
|
internal/redact
Package redact scrubs credential-shaped substrings from external command output before it is surfaced in an error, and caps the size so a misbehaving tool can't flood logs.
|
Package redact scrubs credential-shaped substrings from external command output before it is surfaced in an error, and caps the size so a misbehaving tool can't flood logs. |
|
service
Package service installs the `herrscher serve` daemon as a native, boot-started background service on Linux (systemd user unit), macOS (launchd LaunchAgent), and Windows (Task Scheduler onlogon task).
|
Package service installs the `herrscher serve` daemon as a native, boot-started background service on Linux (systemd user unit), macOS (launchd LaunchAgent), and Windows (Task Scheduler onlogon task). |
|
skills
Package skills discovers SKILL.md skills and runs a progressive-disclosure engine that injects a skill menu into a turn and expands a skill's body on demand — so backends that do not load skills natively can still use them.
|
Package skills discovers SKILL.md skills and runs a progressive-disclosure engine that injects a skill menu into a turn and expands a skill's body on demand — so backends that do not load skills natively can still use them. |
|
Package manage is the host's self-management surface: it edits the managed plugins.go composition and rebuilds the binary.
|
Package manage is the host's self-management surface: it edits the managed plugins.go composition and rebuilds the binary. |
|
plugins
|
|
|
terminal
Package terminal is the terminal gateway plugin: a chat gateway whose "channels" are tabs in the local TUI.
|
Package terminal is the terminal gateway plugin: a chat gateway whose "channels" are tabs in the local TUI. |
|
terminal/tui
Package tui renders a gateway's live event stream and captures the operator's input, driving it through the narrow Backend interface.
|
Package tui renders a gateway's live event stream and captures the operator's input, driving it through the narrow Backend interface. |