How to work

Procedural version of the Daily driver loop — every step, the decision at each fork, and what to do when it breaks. Copy-paste the commands; branch at the decision trees.

mux → dashboard → run → detach/reattach → evolve → drift-check

1. Start the multiplexer

castellan multiplexer ensure

Spawns the in-tree PTY server if it isn’t already running, bound to ~/.config/castellan/castellan.sock (or --socket / a named --session).

Note: ensure is idempotent — safe to run at the start of every session, scripted or interactive.

Decision — is the mux already up?

• Not sure → castellan herd status. Exit non-zero or connection error means no server yet.
• Working on a second, isolated workspace → add --session <name> to ensure (and to every subsequent herd/dashboard call) so it gets its own socket and persist directory.

2. Open the dashboard

castellan dashboard

The ratatui control tower: agent list, pressure/pane tree, evolution archive. Writes ~/.config/castellan/statusline.json on every refresh for headless observers.

Keys: j/k select, Enter attach, r refresh, q quit. Full reference: Dashboard.

Warning: the dashboard needs a live mux socket. If it opens but shows nothing, go back to step 1 before debugging further.

3. Run an episode

Decision — do you need panes?

Every mode writes .castellan/episodes/<goal-id>.json on completion — that file is the input to evolve.

Note: default castellan run is a deterministic plugin loop — the scheduler wakes agents from substrate signals, not from a manager LLM. Add --mcp / --model only on the verify path when you want LLM enrichment.

4. Detach and reattach

You don’t have to babysit a run in the dashboard. Panes and the mux server persist independently of your terminal.

# From inside an attached pane
# Ctrl+Q → detach, leaves the pane running

# From any terminal, later
castellan herd tabs                 # see what's live
castellan herd attach <pane-or-session>

Decision — dashboard says disconnected after reattach?

1. Confirm the server is actually up: castellan herd status
2. If not: castellan multiplexer ensure (or castellan herd server for the foreground form)
3. Re-open: castellan dashboard

5. Evolve topology

Once you have a handful of episodes:

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

Decision — how much do you trust the mutation before it lands?

Same two-phase gate is exposed over MCP as castellan_propose_mutation / castellan_resolve_mutation for agent-driven evolve. See castellan evolve.

6. Drift-check before you trust it

castellan drift-check

Validates the repo (and any pending topology mutation) against the verification manifest. This is the operator gate — contributors use the heavier ./scripts/verify.sh instead (see Verify before PR).

Honest scope: drift-check catches structurally invalid or manifest-violating topology and repo guardrail regressions. It does not grade goal quality or plugin correctness — that’s what episode verdicts and castellan vitals are for.

Decision — drift-check failed. Now what?

1. Read the reported drift_violations / guardrail diff.
2. Guardrail (repo) failure → fix per governance policies, rerun.
3. Topology mutation rejected → the archive was not written; rerun castellan evolve --dry-run and inspect .castellan/proposals/ before retrying --apply-proposal.
4. Still stuck → castellan doctor --json for a staged diagnostic (socket, governance manifest, plugin registry, archive, vitals).

Full failure-path table

Related

• Daily driver — the condensed loop
• Conventions — vocabulary and default paths
• Dashboard — keybindings and headless observability
• castellan evolve · castellan herd
• Troubleshooting