Open source · MIT · Public source preview

Run AI work from a plan you can check

Agent Playbook OS turns a written playbook into a run that follows the steps in order, stops for a person where you ask, carries on from where it stopped, and leaves a record that shows if anyone changed it.

Try the demo Read the README

git clone https://github.com/CometWeb-io/agent-playbook-os

A replay of a real run of kernel-demo (version 0.6.0) on 11 Nov 2026. Steps, outputs and event counts come from that run; the 10-second wait for approval is shortened. How it was run.

Finished steps run twice

After the approval, the demo run carried on from step 3. Steps 1 and 2 did not run again.

5/5

Record checks passed

playbook verify on that run checked its history, plan, state, links and files.

Kinds of step

From a single action to a person's approval, a branch, a loop or a nested playbook.

Runtime dependencies

Pydantic, PyYAML and jsonschema. No model provider's SDK is required.

How it works

Write it, review it, run it, check it

A playbook is a YAML file that lists the steps, their order and who has to approve what. The same file gives the same plan every time, so you can repeat a run, compare two runs and audit one later.

01 · WRITE

Write the playbook

Steps, inputs, approvals and limits in one versioned file.

playbook validate

02 · REVIEW

Review the plan

It compiles into a fixed plan with each skill pinned, so what you review is what runs.

playbook compile

03 · RUN

Run and approve

Steps run in order. The run pauses where a person has to sign off and carries on when they do.

playbook run · resume

04 · CHECK

Check the record

Every run keeps its history, and one command tells you whether any of it was changed.

playbook verify

Real output · 11 Nov 2026

What a run leaves behind

Four results from the CLI on this repository's examples, laid out as documents. Every value is copied from what the commands printed.

Run recordcompleted

kernel-demo, for Ada

Result: approved for Ada

GreetingSaid “Hello Ada”.

step 1

Pick a pathThe rule chose proceed.

step 2

Approved by reviewer@example.comThe run waited until the approval came, 10 seconds later.

14:17 UTC

Result written and checkedExpected and actual result match.

steps 4–5

28 events recorded · playbook verify: all 5 checks pass

Plan for reviewnot run yet

evidence-to-decision

Question: “Should we ship?” Compiled before anything runs, so you can read it first.

ResearchSkill evidence-researcher, pinned.

v1.0.11

Stop unless the evidence is readyContinues only if research reports READY.

gate

DecideSkill ai-council, pinned, run as a separate subagent.

v5.3.2

Both skills checked against CometWeb Agent Skills (commit ea92513): unchanged.

Interrupted runneeded a person

The process died mid-send

An outside call was in progress when the process was killed. Nobody could know whether it went through.

DraftFinished before the crash.

done

Send: outcome unknownResume refused to send it again:

reconcile before resume uncertain external invocation … for send

blocked

Checked, then finishedAn operator recorded “not executed”, and the resumed run completed.

completed

A test playbook; the built-in sleep action stood in for the outside call.

Edited recordverify failed

Someone changed the approver

In a copy of the demo run, one name in the saved history was replaced.

HistoryChanged at event 13, the approval.

fails

Plan, state, links, filesThe other four checks still pass.

4 pass

playbook verify exits with an error, so a script or CI job stops here.

Run locally on 11 Nov 2026 with version 0.6.0 (commit 65a6185) and the built-in reference runtime, which calls no model. The commands and full output are in site/media/cli-runs.md.

Get started

Try it from a clone

There is no release yet, so you install from the repository. You need Python 3.11 or newer and uv. These commands were run on a fresh clone on 11 Nov 2026.

STEP 1

Clone and install

uv creates a local environment with the playbook command in it.

$ git clone https://github.com/CometWeb-io/agent-playbook-os $ cd agent-playbook-os $ uv sync

STEP 2

Run the demo

It runs two steps, then stops and waits for your approval.

$ uv run playbook run \ playbooks/examples/kernel-demo.yaml \ --input name=Ada --run-root .playbook-runs "status": "WAITING_APPROVAL"

STEP 3

Approve and check

Use the run folder the first command printed.

$ uv run playbook resume .playbook-runs/<RUN> \ --approve approval --approval-actor you@example.com "result": "approved for Ada" $ uv run playbook verify .playbook-runs/<RUN> "ok": true

Write a playbook Full quick start

Preview status

What it does not do yet

This is a public source preview. The limits below come from the repository's own release-readiness notes.

A preview, not a release

No version tag and no PyPI package. Install from a clone, and expect files and commands to change.

Not yet tested with a live agent

The examples run on a built-in reference runtime. Adapters for real hosts are sketched but not tested end to end.

Claude Code Codex Cursor

An intact record is not a right answer

Verify shows the record was not changed. It cannot tell you whether a model's answer or a real-world action was correct.

One machine, no sign-in

Runs are stored in files or SQLite. Shared production storage and real sign-in for approvers are not covered yet.

Tests run on every push Security policy ↗ Threat model ↗ Changelog ↗

Try a run you can check

Clone the repository, run the demo, approve it and verify the record. Then write a playbook for your own work.

Get started View on GitHub