Checklists.io

How Checklists.io works

A five-minute guide. No prior experience with AI agents required.

The idea in one paragraph

AI assistants are great at doing steps and bad at accountability. A checklist in a text file is only a suggestion: an AI can skip a step and nobody would know. Checklists.io turns your checklist into an enforced process: your AI must complete steps in order, must attach proof for the steps you mark as needing it, and must stop and wait for your approval on the steps you mark as dangerous. Every run leaves a permanent record of who did what, when, and with what evidence.

Runbook

The recipe: an ordered list of steps, written once, run many times.

Run

One execution of a runbook. It has a live page you can watch and share.

Gate

A step only a human can wave through. The AI parks and waits for you.

What a step can require

  • Order: a step can depend on other steps. The system refuses to complete it until its dependencies are done. Skipping is structurally impossible.
  • Evidence: a step marked evidence: required cannot be completed with an empty hand. The AI must attach proof: command output, a link, a commit hash. You can inspect it on the run page forever.
  • A human gate: a step marked gate: human pauses the run. You get an Awaiting your approval card on the Runbooks page with the AI's explanation and evidence, and Approve / Reject buttons. Rejecting fails the run. The AI cannot approve itself; approval only works from a signed-in browser session.

Set it up (about 3 minutes)

1Create an account

Sign in on the home page with Google or email. Free.

2 Mint an agent token

Go to Settings → Agent tokens, give the token a name (e.g. claude-code-laptop), and copy the ck_… value (it is shown exactly once). This token is how your AI proves it is acting for you. Revoke it any time; the AI is locked out instantly.

3 Connect your AI assistant

Checklists.io speaks MCP (Model Context Protocol), the standard way AI assistants use outside tools. Any MCP-capable assistant works. For Claude Code, run this once in your terminal (paste your token):

claude mcp add --scope user --transport http checklists \
  https://checklists.io/api/mcp \
  --header "Authorization: Bearer ck_YOUR_TOKEN_HERE"

Optional, and worth it: install the agent skill. The MCP server gives your assistant the tools; the skill teaches it how to use them well: wait at a gate rather than working around it, attach the artifact rather than a claim that the check passed, and size steps and gates sensibly when it writes a runbook for you.

npx skills add ChecklistsIO/agent-skills
Using Antigravity?

Add this to ~/.gemini/config/mcp_config.json(or Settings → Customizations → Open MCP Config). Note it's serverUrl, not url:

{
  "mcpServers": {
    "checklists": {
      "serverUrl": "https://checklists.io/api/mcp",
      "headers": { "Authorization": "Bearer ck_YOUR_TOKEN_HERE" }
    }
  }
}

Restart your session, then ask: "list my runbooks". If it answers, you're connected. Other MCP clients (Cursor, VS Code, …) work the same way: the URL plus that one Authorization header. No AI at all? The endpoint accepts plain HTTP (JSON-RPC), usable from scripts and CI.

4Create your first runbook

Easiest way: describe your process to your AI and ask it to create the runbook. For example: "Create a runbook for deploying my website: run the tests (attach proof), then deploy to production (but wait for my approval before the deploy), then verify the site is up." Under the hood it calls the create_checklist tool with a definition like:

name: Deploy my website
steps:
  - id: run-tests
    check: full test suite is green
    evidence: required
  - id: deploy
    check: deployed to production
    gate: human          # waits for YOUR approval
    evidence: required
    depends_on: [run-tests]
  - id: verify
    check: site responds after deploy
    depends_on: [deploy]

5Run it and stay in the loop

Tell your AI to start a run (or press Start run on the Runbooks page). Open the run page and watch steps complete live. When the AI reaches a gated step, the page shows Awaiting your approval with its explanation and evidence. Read it, then Approve or Reject. When the last step finishes, the run closes itself and the record is permanent.

Approving from the terminal

If your AI runs in a terminal, you probably do not want to switch to a browser to approve one step. The CLI signs in as you and decides from the same window.

npm install -g checklists-cli
checklists auth login          # opens your browser, same sign-in as here
checklists pending             # what is waiting on you
checklists show <run-id>       # the AI's case for the gate
checklists approve <run-id> --step "cut release"
checklists reject  <run-id> --step "cut release" --reason "wrong base"

The package is checklists-cli (plural), and it installs both checklists and checklist, so whichever you type by reflex works.

The step has to be named, and the AI's reasoning prints before it asks. Approving whatever happens to be pending is how you approve something you did not read. Rejecting is not “skip”: it fails the whole run, which is why it takes a reason.

Every approval records the surface it came from and the machine it came from, and the run page shows both: “approved via cli · your-laptop”. A step can also require a particular surface with "gate_surfaces": ["web"]; the CLI is refused if it is not on the list.

Writing and running runbooks from the terminal

The CLI also authors. runbooks pull writes a runbook as YAML, you edit it in your editor, and runbooks push shows you exactly what will change and asks before applying.

checklists runbooks pull <id> -o release.yaml
$EDITOR release.yaml
checklists runbooks push <id> -f release.yaml
checklists runs start <id>

Editing never disturbs a run already under way: a run keeps the steps it started with, and the gates, evidence rules and dependencies it enforces come from that snapshot. Your change applies to the next run.

checklists runs, runs complete, runs abort and tokens round it out; anything you can do here, you can do there. Ids can be shortened to their first few characters.

Signing in, and what gets stored

auth login opens your browser and you sign in where your session and password manager already are. No password is typed into or stored by the CLI. The credential comes back over a local callback, so a code intercepted on the way is useless to anyone who did not start the sign-in.

The session is written to ~/.config/checklists/config.json (permissions 0600) and refreshes itself. checklists auth whoami prints who you are signed in as; checklists auth logout removes it.

On a machine with no browser (SSH, a container), checklists auth login --no-browser emails you a one-time code instead.

Common questions

Can the AI approve its own gated steps?

No. Approval requires the checklist owner’s own sign-in: in the browser, or in the CLI, which signs in as you and never as the agent. Agent tokens cannot approve anything: they are not user credentials, and the database derives the approver from the signed-in identity rather than from what the caller claims, so the rule holds regardless of the AI’s instructions. Every approval records which surface it came from, and a step can be restricted to specific surfaces.

What if the AI tries to skip a step or skip evidence?

The server refuses and tells it which dependencies are unmet or that evidence is missing. There is no way around the order. That is the product.

Do I have to use an AI?

No. Runbooks are perfectly good human checklists: start a run in the browser and treat the run page as your working document. The enforcement (order, gates, evidence) applies to everyone equally.

Is my agent token a password?

Treat it like one. It lets an agent act as you (except approvals). Keep it out of shared code and repos, and revoke tokens you no longer use on the tokens page. Only a fingerprint of the token is stored on our side.