TomLabs Apps
← All applications

RunbookWizard

Step-by-step player for runbooks: guides in Markdown or JSON with exact commands, checks and parameters

github windows runbook avalonia dotnet ops Public Homepage

RunbookWizard

A step-by-step wizard for procedures (setup, install, configuration). It shows each step with its explanation, shows the exact command, runs script steps with one click and tells you what happened and why.

The core idea is one unified format for guides that a person can hand-write and an AI can generate: Markdown with YAML frontmatter (*.runbook.md) or JSON (*.runbook.json), validated against one JSON Schema. RunbookWizard is the reference player for it.

Guide content is untrusted input: nothing runs without a click and the exact command is always shown first.

Use it from an agent (MCP)

While RunbookWizard runs it serves an MCP endpoint on http://127.0.0.1:5233/mcp (local only; switch it off or see its state on the Settings page, Ctrl+,). Register it once in Claude Code:

claude mcp add --transport http runbookwizard http://127.0.0.1:5233/mcp

Tools: list_runbooks, get_runbook, validate_runbook (read only), open_runbook, fill_placeholders and run_step. An agent can open a guide, fill its non-secret parameters and ask to run the current script step; the player shows the request with the exact command and nothing runs until you press Run (no answer within 120 s counts as declined). Set RUNBOOKWIZARD_MCP_PORT to use another port. Design: ADR 0015.

Build and test

dotnet build RunbookWizard.slnx
dotnet test RunbookWizard.slnx
dotnet run --project src/RunbookWizard.App -- docs/examples/hello-world.runbook.md

RunbookWizard --health prints the health JSON (status, version, name); RunbookWizard <guide> opens a guide. UI verification uses the shared automation channel, see CLAUDE.md.

License

Licensed under the Apache License 2.0.

Changelog

Changelog

0.3.0 — 2026-10-17

  • Added: an MCP server inside the app (127.0.0.1:5233, local only) so an agent such as Claude Code can work with the player: list, read and validate guides, open a guide, fill in its parameters and ask you to run the current script step.
  • Added: nothing an agent asks for runs by itself. A banner shows the agent's request with the exact command and its warnings; you press Run or Decline, and no answer within 120 s counts as declined. Secrets, manual, info and choice steps, and restarting as administrator stay with you.
  • Added: what an agent did is marked in the player: "Opened by …", parameters "Filled in by …" (until you change them) and steps "Run at the request of …, confirmed by you".
  • Added: a Settings page (gear in the header, the command palette or Ctrl+,) to switch the MCP server on or off, see whether it listens, and copy the claude mcp add command. RUNBOOKWIZARD_MCP_PORT changes the port.

0.2.0 — 2026-10-13

  • Added: the player updates itself from GitHub Releases (stable and nightly channels, signed manifests, update banner, "Check for updates" in the command palette).

  • Added: steps marked elevated no longer fail confusingly when the player is not run as administrator. A banner explains it, Run is disabled for such a step with the reason (Skip still works), and "Restart as administrator" reopens the player with the same guide through the Windows administrator prompt. Entered values are not carried over.

  • Fixed: a {{Name}} placeholder right after a backslash (IIS:\AppPools\{{SiteName}}, C:\{{Folder}}) was not substituted and lost the backslash in the executed command. A backslash is now only a path separator.

  • Changed: the escape for a literal {{Name}} is now {{!Name}} (was \{{Name}}).

  • Added: Apache-2.0 license (LICENSE), declared in the README and in the build properties.

  • Added: checklists in manual steps. Write - [ ] item lines in the step text and the player shows checkboxes; the confirm button stays disabled until every required item is ticked. Start an item with (optional) to let it stay unticked.

  • Added: the example guide docs/examples/checklist-handover.runbook.md.

  • Added: branching in guides. A choice step lets the reader pick a way; next and onFailure jump to another step; steps on a path not taken show as skipped. Unknown targets and loops are rejected when the guide opens.

  • Added: parameters inside the command. The {{Name}} placeholders in the command preview are fields you edit right there (masked for secrets); they share the value with the Parameters page.

  • Added: the example guide docs/examples/branching-deploy.runbook.md.

  • Added: Markdown in step descriptions, "why" and info text is rendered (bold, italic, code, lists, links, headings, fenced code).

  • Added: syntax highlighting for the command preview (PowerShell, bash, cmd) and for fenced code blocks, in light and dark.

0.1.0 — 2026-10-13

  • Added: one guide format, Markdown with YAML frontmatter or JSON, validated against a JSON Schema, with a specification and examples.
  • Added: the player. Step list with status, description, "why", the exact command, a Run button and live output.
  • Added: script steps in PowerShell, bash or cmd, success checks (exit code, output patterns), captured values and parameters entered once.
  • Added: conditions, retry after a failure, skip, and a second confirmation for destructive steps.
  • Added: secret parameters are masked in the command, the output and the log.
  • Added: Logs page, command palette (Ctrl+K), System/Light/Dark theme, version in the header.