Documentation / Runbooks

Runbooks

A runbook is a markdown file in your project that holds durable context for a recurring task — a known bug, a deploy procedure, an onboarding checklist. Attach a runbook to a Claude session and Claude reads it as part of its system prompt; the same notes are in scope every time you come back to the same kind of work.

Runbooks are project-internal markdown — Mulpex just provides the UI for attaching them. Your project stays Mulpex-agnostic.

Where they live

By default, <project>/docs/runbooks/*.md. The directory is configurable per-project via the top-level runbooks: { dir: "..." } key in mulpex.json, or through the Configuration modal's Runbooks pane (⌘,).

Each runbook is plain markdown. Optional YAML frontmatter (title, summary, tags, related, status, last_updated) makes the runbook nicer to search and display, but isn't required.

Attaching via the picker (⌘P)

The runbook picker opens automatically the first time you spawn a fresh worktree or loose tab. You can also reopen it any time with ⌘P on the Claude tab.

Search filters across filename, title, summary, body, and tags — so you can author synonym-rich tags and they'll match without cluttering the row. Each row has a Read button that opens the runbook in a preview modal. Confirm your selection with Confirm (or Enter), or dismiss with Skip (or Esc). On a fresh spawn, typing your first message into Claude also auto-dismisses the picker.

Re-attaching mid-session

Right-click the instance in the sidebar → Attach runbook…. Mulpex respawns Claude silently (terminal stays mounted) with the new runbook set; you'll see a [runbooks reloaded] marker in the transcript when it's done.

Saving a session as a runbook

Two entry points, both available only when the session has no runbooks attached (otherwise, Claude is already nudged to update the existing runbook before commit):

• Close-dialog checkbox. When you close a worktree or loose tab, the dialog has an "Also save session as runbook" checkbox. Check it and Mulpex distills the session into a new .md file before running the close.
• Right-click → "Save session as runbook…". Same flow but keeps the session running afterward — Mulpex respawns Claude with --continue / --resume so you can keep working.

Claude picks a component-first filename (e.g. firewall-rules-missing.md, auth-mfa-disable.md) and authors 3–6 searchable tags.