Runbook

One config. Two audiences.

Most teams end up with a Makefile for humans and a separate set of AI prompts that describe the same tasks in different words. Runbook eliminates that split. Define your tasks once in YAML and both audiences use the same definitions.

Features

Install

Installs to ~/.bin/runbook. Add ~/.bin to your PATH if needed.

Quick Start

version: "1.0"

defaults:
  shell: "/bin/bash"
  timeout: 300

tasks:
  build:
    description: "Build the project"
    command: "go build -o bin/app ."
    type: oneshot

  dev:
    description: "Start development server"
    command: "npm run dev"
    type: daemon

# See what tasks are available
runbook list

# Run a task
runbook run build

# Run with parameters
runbook run deploy --env=staging

# Start a daemon, check status, view logs, stop it
runbook start dev
runbook status dev
runbook logs dev --lines=50
runbook stop dev

{
  "mcpServers": {
    "runbook": {
      "command": "/path/to/runbook",
      "args": ["-config", ".dev_workflow.yaml"]
    }
  }
}

Shared MCP server

By default Runbook runs in stdio mode, which works great for a single AI session. Run it in HTTP mode and multiple sessions connect to the same instance simultaneously, sharing state, daemons, and logs.

# Start once, connect from anywhere
runbook -serve -config .dev_workflow.yaml

# or on a custom port
runbook -serve -addr :9000 -config .dev_workflow.yaml

Task Types

Every task has a type that controls how Runbook manages its lifecycle.

tasks:
  test:
    description: "Run tests"
    command: "go test ./..."
    type: oneshot
    timeout: 120

tasks:
  server:
    description: "Start API server"
    command: "go run ./cmd/server"
    type: daemon
    working_directory: "/path/to/project"

Parameters

Tasks can accept parameters using Go template syntax. The AI assistant fills in the values automatically based on the parameter schema you define.

tasks:
  deploy:
    description: "Deploy to an environment"
    command: "scripts/deploy.sh --env {{.env}} --version {{.version}}"
    type: oneshot
    parameters:
      env:
        type: string
        required: true
        description: "Target environment (staging, production)"
      version:
        type: string
        required: false
        description: "Version to deploy"
        default: "latest"

Each parameter becomes a field in the MCP tool schema, with its description shown to the AI. Required parameters must be provided; optional ones fall back to default.

You can also expose the task's working directory as a parameter using expose_working_directory: true. Useful when the same task runs against multiple directories.

Workflows

Workflows run multiple tasks in sequence with a single MCP tool call. Steps share optional parameters via template substitution, and individual steps can be marked continue_on_failure to keep the pipeline running even if they fail.

workflows:
  ci:
    description: "Full CI pipeline"
    steps:
      - task: lint
      - task: test
      - task: build
        continue_on_failure: true

Runbook exposes each workflow as a single MCP tool named workflow_{name}. The AI can run your entire CI pipeline with one call.

Config Reference