Cerveau boots data-first and loads models on demand. Every degraded tier is usable, nothing crashes for a missing component, and browsing a past session needs no model at all.
The boot sequence
Load config from ~/.config/cerveau/config.json, with CRV_* overrides applied.
Open the session store — the events.jsonl files on disk.
Connect Typesense if it is reachable. If it is not, carry on.
Panel live.
The core never spawns a model server
It pings endpoints. A model is a URL, not a process the harness owns — which is why an engine crash cannot take the panel with it, and why the model can live on a NAS or another machine entirely.
Four tiers, all usable
Missing components degrade the tier. Nothing crashes, and the readiness gate blocks only what the tier you asked for actually needs.
The readiness gate
Triggered by a new chat, a mode start, or continuing a session from the picker — nothing enters the loop un-gated. It runs parallel checks: model endpoint reachable and loaded, embedder up, Typesense up, code graph indexed.
Each component gets a status card with one-tap fix hints, and the gate blocks only what the requested tier actually needs. Wanting to read a past conversation does not require a model to be running.
Sessions
Create
An ordinary session in the current workspace.
CreateInWorkspace
Stamped with an explicit workspace, so a session belongs to a specific project rather than to whichever folder was last picked. This is what keeps a CLI session and a panel session from fighting over the same path.
CreateInstant
Ephemeral, with its own isolated scratch workspace under the session directory, so it never touches a real project. Flagged instant, skipped by memory promotion, swept after 24 hours idle.
The sweeper runs at boot and every 30 minutes thereafter.
Replay
Opening a session replays its events.jsonl into a read-only window: full history, reports, decisions. The log is append-only and crash-safe, so replay is exact rather than reconstructed.
Turn-boundary hooks
Zero extra inference, zero user wait. Everything here runs after the answer has already been delivered.
A failure in any of these is logged and never blocks the next turn. The panel shows a saved-count badge, not a spinner.
turn_close
Turn metadata distilled by a small async background call after delivery, off the critical path.
Checkpoint
An episodic event at every boundary: plan state, step status, diffs, tool log. Per step in Autopilot. This is what makes crash-resume and the final report trivial.
Async promotion
The curator dedups candidates and upserts facts and decisions. The panel shows a "n memories saved" badge rather than a spinner.
Window reclaim
This turn's raw tool results demote to event-id pointers and the episodic tail shrinks, so the next turn starts lean.
Report render
The final Autopilot report is a render of checkpoint events. Zero extra work at plan end — the hooks did the bookkeeping as they went.
Interrupts
Every Think and Act runs under a cancellable context.
Action
Effect
Steer
Cancels in-flight work now, appends your message, re-thinks immediately.
Pause
Finishes the current Act, then parks.
Kill
Aborts everything and hands back.
A real steer flags itself before cancelling
A genuine steer sets an explicit flag before it cancels, so the loop can distinguish it from an incidental cancellation — a flaky endpoint, a dropped connection. Without that, an incidental abort reads as a steer and silently spins the loop to its iteration cap.
The engine's prefix cache survives all three. Aborted partials are logged but never kept in the window, and every path resumes through episodic replay.
Error handling
An error taxonomy rather than a blanket retry:
Class
Example
Policy
Transient
Timeout, sidecar down
Auto-retry, budget 2, with backoff.
Args
Bad path, guard denial
No retry. A structured denial plus a hint goes back to the model.
Malformed
Unparseable tool call
One regenerate, with the parse error fed back.
Threshold: three same-tool or five total failures hands back. See The agent loop.
What you see
Error cards
What / Why / Tried / Options, with the reason expanded by default so it is visible without a click. Dismissal tracks stable per-error signatures, so a new fatal error can never be swallowed by a prior dismissal.
Live iteration ticks
A running-to-done glyph, the tool name and its actual argument, and collapsible real output. Transient retry chatter is filtered out of the chat and kept in the activity rail.
The principle behind both: never a dead spinner, never a log wall. The user always sees what the loop is doing and why anything failed.