Daily driver

Recommended local workflow for operating Castellan — agents, panes, and the episode flywheel. For contributing to the Rust codebase, see Engineering guide and Verify before PR.

Why this loop

Mux keeps panes alive, the dashboard shows pressure and agents, run writes episodes, evolve mutates topology, drift-check gates what you trust.

Loop

castellan multiplexer ensure  →  castellan dashboard  →  castellan run  →  castellan evolve  →  castellan drift-check

Multiplexer — castellan multiplexer ensure starts the in-tree PTY server (~/.config/castellan/castellan.sock). Idempotent; safe at the start of every session. Use --session <name> for an isolated socket.
Dashboard — castellan dashboard opens the ratatui UI (agents, pressure, pane tree). Writes ~/.config/castellan/statusline.json for MCP observability. Keys: j/k select, Enter attach, r refresh, q quit — see Dashboard.
Run — pick a mode:

You want	Command
Scheduler-led panes (daily default)	`castellan run --goal "…" --plugin gridworld --mux`
Offline / CI smoke	`castellan run --goal "…" --plugin gridworld`
Headless verify/act	`castellan run --goal "…" --plugin gridworld --rlm`
LLM/editor wired	`castellan run --goal "…" --plugin shell --mcp`

Every mode writes .castellan/episodes/<goal-id>.json. Default castellan run is a deterministic plugin loop — add --mcp / --model only when you want LLM enrichment.

Detach / reattach — panes persist without babysitting. Ctrl+Q detaches; later castellan herd tabs / castellan herd attach <pane-or-session>.
Evolve — castellan evolve --episodes 16 --workspace .castellan/episodes. Prefer --plan / --dry-run before applying; MCP exposes castellan_propose_mutation / castellan_resolve_mutation.
Gate — castellan drift-check against the verification manifest before you trust a topology change.

Honest scope: drift-check catches structurally invalid or manifest-violating topology. It does not grade goal quality — use episode verdicts and castellan vitals for that.

Config layers from castellan.toml when present. Episodes and archive live under .castellan/.

Operator commands

castellan multiplexer ensure

castellan dashboard

castellan herd status

castellan run --goal "reach target" --plugin gridworld --mux

castellan evolve --episodes 16 --workspace .castellan/episodes

castellan drift-check

Remote / SSH

castellan remote --ssh user@host --goal "reach target" --plugin gridworld

castellan herd attach --session my-work

castellan herd status

When something breaks

Symptom	Likely cause	Fix
`castellan herd status` errors	No mux server	`castellan multiplexer ensure`
Dashboard opens blank	Socket up, no panes yet	Run with `--mux`, then `r`
Episode missing after `run`	Plugin exited early	Rerun with `--json`
`evolve` accepts 0	Corpus too small	More episodes, or `--plan` first
`drift-check` rejects	Structural/manifest violation	Inspect violations; do not force-apply

More symptoms: Troubleshooting. Staged diagnostics: castellan doctor --json.

Goal	Page
First-time setup	Quickstart
Dashboard keybindings	Dashboard
MCP / statusline	MCP overview · Statusline
Agent onboarding	Agent guide
Contributor PR gate	Verify
Lexicon	Conventions

Keyboard shortcuts