---
name: callboard
description: A shared to-do list for a human and their AI coding agents. Tasks, requests only the human can do, and questions that are the human's call, kept as three Markdown checklists in each project, with a live page, item-by-item git merging, and claims so agents don't collide.
homepage: https://github.com/AsWali/CallBoard
post: https://asror.dev/blog/callboard
---

> **If you are an AI agent reading this file:** this is your guide to setting
> up Callboard for your human. Follow the steps below in order. Tell them what
> you ran and what changed; don't skip the last step.

# Callboard

Callboard is one program (`callboard`) that keeps a project's plan where the
human can see it:

- `backlog.md`: tasks you and other agents do. You claim one before you start
  it and tick it when it's done.
- `requests.md`: things only the human can do (an account, an API key, a
  payment, a deploy), with exact steps.
- `questions.md`: decisions that are the human's, with the options and the one
  you recommend.

Once it's connected, Claude Code and Codex hear the lists at the start of every
session and get MCP tools to change them. You don't need to learn the file
format: use the tools.

## What should you do?

**Step 1: Install the program** (skip if `callboard version` already works).

On macOS or Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/AsWali/CallBoard/main/install.sh | sh
```

The script downloads the latest release, checks it against the release's
checksums, and puts `callboard` in `~/.local/bin`. If `~/.local/bin` isn't on
the PATH, tell your human the line to add to their shell profile:
`export PATH="$HOME/.local/bin:$PATH"`.

On Windows, download `callboard-…-windows-amd64.exe` from
https://github.com/AsWali/CallBoard/releases, rename it to `callboard.exe` and
put it in a folder on the PATH.

If your sandbox blocks the download or the write to `~/.local/bin`, ask your
human to approve it; don't work around it.

**Step 2: Connect the agents.** Ask your human which they want, unless they
already said:

| They want | Run | What it changes |
|---|---|---|
| Every project (recommended) | `callboard setup --global` | Only their own settings: Claude Code's MCP server, hooks and `/callboard` command; Codex's MCP server, hooks and a section in `~/.codex/AGENTS.md`; git's merge driver. Never the files in their projects. |
| Just this project, shared with a team | `callboard setup` in the repo | Files meant to be committed: `.mcp.json`, `.claude/settings.json`, `.gitattributes`, and for Codex `AGENTS.md`, `.codex/config.toml`, `.codex/hooks.json`. |

Show them what the command printed. The undo is `callboard disconnect --global`
(or `callboard disconnect` in the repo); the lists stay.

If a line starts with ✗, tell your human what it says and follow the fix it
gives, then run the same command again. Don't switch to the other kind of
setup instead: `callboard setup` writes files into their repo.

**Step 3: Check it.** Run `callboard status --global` (or `callboard status` in
the repo) and tell your human if anything is missing.

**Step 4: Tell your human what's left for them.**

- The MCP server and hooks load in *new* sessions. Ask them to start a new
  Claude Code or Codex session in their project.
- Codex asks once to approve the hooks: in Codex, type `/hooks` and trust
  Callboard's.
- To see the lists: `callboard serve --open` opens the live page. Or, in
  that new session, type `/callboard` in Claude Code (`!callboard` in
  Codex). It doesn't work in the session that ran the setup.

## Try it on a demo project

If your human wants to see it before using it on their own work:

```bash
git clone https://github.com/AsWali/CallBoard && cd CallBoard
scripts/demo.sh
cd "${TMPDIR:-/tmp}/callboard-demo/pebble"
callboard serve --open
```

`scripts/demo.sh` builds a made-up app, Pebble, with tasks, requests and
questions already in its lists. Then they can start `claude` or `codex` in that
folder and ask it to pick up the next task.

## Example prompts

| What the human says | What to do |
|---|---|
| "Read asror.dev/callboard-setup.md and set up Callboard for me" | Steps 1 to 4, for every project unless they say otherwise. |
| "Read asror.dev/callboard-setup.md and set it up for this repo" | Steps 1 to 4 with `callboard setup` in the current repo. |
| "Read asror.dev/callboard-setup.md and show me the demo" | Step 1, then the demo above. |

## More

- README: https://github.com/AsWali/CallBoard
- Questions people ask: https://github.com/AsWali/CallBoard/blob/main/docs/faq.md
- How agents use it: https://github.com/AsWali/CallBoard/blob/main/docs/agents.md