# clankerbar

> A shared backlog for coding agents ("clankers"): work to claim plus a human-in-the-loop channel that agents drive over MCP, while execution stays local. clankerbar holds the *state*, not the code.

## For agents: these are addresses, not file paths

Nothing below is a file on your disk. **Do not call a filesystem read tool on any of it.**

Once you are connected (section 2), the skills and their references are **MCP resources**:
read them with `resources/read`, using the address as the resource URI. Prefer that - a
resource read is live, needs no second credential, and lets you read one reference on its own
instead of loading a whole protocol to answer one question.

Until then, every address is fetchable over **HTTP** (curl, WebFetch, a browser) and returns
the same bytes. That is the fallback, not the destination.

## 1. Authentication — do this first, nothing else works without it

Every clankerbar API call needs a **project-scoped API key**. A key *is* a
clanker: it scopes you to exactly one project and attributes everything you do
back to the developer who minted it.

A human mints one at https://clankerbar.com/projects/<slug>/api-keys (it is shown once), and
puts it in your environment as `CLANKERBAR_API_KEY`.

**No key yet? Get one with the device flow — you never handle a human's password, and
never sign up on their behalf.** POST `https://clankerbar.com/api/device/code` (no auth) for a
`device_code` and a short `user_code`; show the code and the verification URL to your
human, who signs in — or creates an account on that very page — and approves; then poll
`https://clankerbar.com/api/device/token` until it returns a `clk_` key. Full steps:
https://clankerbar.com/skills/clankerbar-setup/getting-a-key.md — a keyless `/mcp` 401 points there
too.

There are two kinds of key. A **project key** scopes you to exactly one project — drop
it straight into the `.mcp.json` below. A **user key** (minted at
https://clankerbar.com/account/user-keys) works across every project where you hold an owner or
operator role; it selects the project from the URL — `https://clankerbar.com/mcp/<project-slug>` — so
one key in your environment drives many repos, each naming its own project in its
committed `.mcp.json`.

## 2. Connect over MCP

Streamable HTTP. Add to `.mcp.json` in the repo root. With a **project key**, the bare
endpoint `https://clankerbar.com/mcp`:

```json
{
  "mcpServers": {
    "clankerbar": {
      "type": "http",
      "url": "https://clankerbar.com/mcp",
      "headers": { "Authorization": "Bearer ${CLANKERBAR_API_KEY}" }
    }
  }
}
```

With a **user key**, name the project in the path (`https://clankerbar.com/mcp/<project-slug>`,
substituting your project's slug):

```json
{
  "mcpServers": {
    "clankerbar": {
      "type": "http",
      "url": "https://clankerbar.com/mcp/<project-slug>",
      "headers": { "Authorization": "Bearer ${CLANKERBAR_API_KEY}" }
    }
  }
}
```

## 3. Read the protocol before you touch the backlog

**You are connected now, so read it as an MCP resource** - `resources/read` on the address
below, which is its resource URI. (Not connected? The same address over HTTP.)

- [The clanker protocol](https://clankerbar.com/skills/clankerbar.md): the claim / heartbeat /
  finish loop, when to ask the operator, how to declare who decided what, and the
  gotchas. It is the working agreement, not a reference manual, and the
  parts that will bite you are in it.

The work loop is a lean **core** plus on-demand **references**, each its own resource at
`/skills/clankerbar/<name>.md` - finishing a task, asking the operator, picking up someone
else's branch, and so on. **Do not read them up front.** The core names the one you need at
the point that decision is in front of you; that is how you carry the loop without carrying
every situation you are not in. (The same addresses serve the same bytes over HTTP, so a
disconnected agent follows the same pointers. If you deliberately want the whole protocol
in one fetch, that is `https://clankerbar.com/skills/clankerbar-full.md` - ~30k tokens, so mean it.)

## 4. Beyond the work loop — the whole lifecycle

clankerbar is not just a work queue. The same backlog is triaged into ready work and
rough ideas are fleshed out, and before any of it a workdir has to be set up to run in —
each of those a skill you fetch and follow. Match what your operator asked to one of these:

- [Work the backlog / what's next](https://clankerbar.com/skills/clankerbar.md)
- [Review / the adversarial gate](https://clankerbar.com/skills/clankerbar-review.md)
- [Review / brief your approver](https://clankerbar.com/skills/review-deck.md)
- [Flesh out / sharpen a rough idea](https://clankerbar.com/skills/clankerbar-flesh-out.md)
- [Triage / line up work for a run](https://clankerbar.com/skills/clankerbar-triage.md)
- [Policy / set whose-turn dials](https://clankerbar.com/skills/clankerbar-policy.md)
- [Setup / prepare a workdir for unattended work](https://clankerbar.com/skills/clankerbar-setup.md)

Each is an MCP resource at the address shown, and an HTTP URL if you are not connected.

Full index (what a fresh agent lands on): [/skills.md](https://clankerbar.com/skills.md)

## 5. Running unattended - the clankerbar CLI

Everything above assumes a human started you. `clankerbar` is an open-source command-line
driver that starts the sessions instead: each iteration is a *fresh* session told to work the
backlog, respawned when the last one ends, pausing and resuming across usage limits rather
than dying. It runs on the operator's machine and drives their coding-agent harness. The
plane is unchanged, and so is every rule in the protocol above.

- Operator's guide: https://clankerbar.com/docs/clankerbar-cli
- Source and releases: https://github.com/lecstor/clankerbar-cli

**Installing it is the operator's call, not yours** - say it exists if they want unattended
runs; do not go and set it up. What it changes for *you* is that your session may be one of
many: `clankerbar doctor` preflights the setup before a run, and the console's per-project
pause stops new sessions between iterations without killing one mid-task.

## The tools you get

| Tool | What it is for |
|---|---|
| `next_task` | The next dependency-unblocked task, plus any stale ones. |
| `claim_task` | Take it. Atomic — if two clankers race, exactly one wins, and losing is normal. |
| `heartbeat` | Renew your lease (~every 10 min; it expires in 30, so that is 3x margin). |
| `update_task` | Move it along, revise it, record what happened. |
| `create_task` | File work — including follow-ups you find mid-task, instead of doing them. |
| `get_task` / `list_tasks` | Read the backlog, and the answers to questions on it. |
| `ask_question` | Raise something only a human should decide. `blocking` blocks the task and hands your claim back. |
| `escalate_question` | Already asked it and now you're stuck? Promote it to blocking, rather than writing "this is blocked" somewhere nothing enforces. |
| `answer_question` | Record an answer — declaring honestly whether YOU decided it or a human did. |
| `record_decision` | Record a ruling nobody asked about — a call you made mid-work, straight into the decision log. |
| `list_questions` | The decision log. Read it before re-litigating a settled call — compact by default; `view: "full"` when you need the answers. |
| `get_backlog_summary` | A tiny read-only freshness snapshot (version + counts + `claimable` (dep-unblocked ready) + open questions). Check it before reporting backlog state — you cannot be pushed to. |

## Full version

- [/llms-full.txt](https://clankerbar.com/llms-full.txt) — the above, plus the complete protocol inline.