Label a card. Get a commit and a comment back.
A small worker watches Docket's boards, takes a card, and works it end to end in its own headless Claude Code session. It never spends API credits, never deploys, and leaves the evidence on the card.
The Docket agent in about a minute
Claim a card, make the change, check it, and hand off what is stuck: a read-only triage first, a claim that fails safe, spare usage only, and more than one Mac on one queue.
Read the film’s text version
Title: Docket agent. Claim. Fix. Check. 2026. A bright synth swell and a whoosh open the film.
Waiting: “93 open cards” climbs with one mark for each card, under “Waiting in Docket,” and three sample cards land. “Someone has to pick them up.”
Which cards it takes: “The agent picks.” Five cards. Three ways in light up on the beat: label it claude, assign it to Claude, or put it on a board the agent sweeps. Two more cards dim because of their needs review and no agent labels. “A label can say no.”
Claim: As the first big drop lands: “Claim.” The agent reads a card, claims it, and moves it. The card takes a Claude assignee and slides from To Do to In Progress. “Someone changed it first? The claim fails. The agent moves on.” A second card's claim comes back as a 409 and is left alone.
A fresh session: One card, one session. Sonnet makes the change, Opus checks the diff, and an arrow loops back when it is wrong. The change is committed and pushed once. “Sonnet does it. Opus checks it.” “Never deployed.”
Spare usage: Two bars show the gates: at 80 percent of the five-hour window no new card starts, at 95 percent a running session pauses, and at 90 percent of the week no new card starts. “No new card more than 10% ahead of pace.” “Only what the week would leave unused.”
Never the API: “Subscription. Never the API.” The API keys are removed from every session, and a check reads “no API key in use.” Anything else stops the session.
How it ends: As the second big drop lands: “Fixed.” A card sits in QA with its resolution comment, and four outcomes appear one a beat: fixed, superseded, deferred, failed. Then “Stuck.” A card is flagged needs review and assigned to a person, with its failure comment. “Failures go to a person.”
Triage first: “Triage first.” A card goes into a “read-only check,” and six verdicts land one at a time: valid, fixed, obsolete, duplicate, gated, and unclear. A bracket around the three that close a card (fixed, obsolete, and duplicate) carries an “Opus” chip. “Opus confirms before it closes.”
More Macs: “More Macs. One queue.” Three drawn Macs, each labeled only “Mac,” feed one box labeled “Docket.” The film states no number of machines.
Close: On the final chord, the Docket icon, “Docket agent,” “Claim. Fix. Check.,” and this page's address.
What the agent is
The Docket agent is a background worker that runs on a Mac and works Docket cards without anyone at the keyboard. It polls Docket, finds a card that is ready, reads it first to check that it is still a real problem, and then starts one headless Claude Code session for that card, in the card's own repository. When the session ends, the agent checks what actually happened on the card and in the repository, and fixes the board if the session left it in a mess.
It does what a person does when they work a board by hand: read the description and every comment, change the code, check the change, commit, push, and say so on the card. It talks to Docket through the same service as the web app and the MCP tools, and it is written in Python's standard library alone.
| Runs as | A macOS LaunchAgent. It looks at Docket every two minutes, and every 30 seconds while a session is running. |
|---|---|
| Starts | One headless claude -p session per card, in that card's repository on main. |
| Model | Opus at high effort by default. The session hands the code to a Sonnet agent and reviews the diff itself. |
| Pace | One work session at a time by default, and never two in one repository. Up to two read-only triage sessions run beside it. |
| Billing | The Claude subscription only. A session that could bill API credits is stopped. |
| Never | Deploys. Anything that needs a decision or a deploy goes back to a person. |
A card's path
From a label to a resolution comment, with the board kept honest at every step.
Pick
A person adds the
claudelabel to a card, or assigns it to Claude. Cards on the boards the agent sweeps by default are picked up too, in Docket's own order.Claim
The agent re-reads the card, assigns it to Claude, and moves it to In Progress. The claim is a compare-and-set write, so if anyone changed the card first, the agent walks away.
Work
The session reads the description and every comment, and the newest comment from a person wins. A Sonnet agent writes the change, and Opus checks its diff and sends it back until it is right.
Commit and push
Only the card's own files are committed, then pushed to
mainonce. A rejected push is rebased and pushed again. It is never forced, and nothing is deployed.Report
The card moves to QA with a resolution comment that names the commit. If the session cannot finish, the card goes back to To Do, flagged
needs review, with the reason.
A card that turns out to be fixed already, or no longer true, is closed the same way: the session proves it with a commit, the code, or a passing test, comments Fixed, Superseded, or Still valid, and moves the card to QA.
Triage comes first
Before a card gets a work session, it gets a short read-only look, so the agent doesn't spend a session on a card that is already fixed, no longer true, or waiting on a person.
Read
A Sonnet session gets the card's title, description, and newest comments, and checks the code as it stands. It may only read: git history, searches, and files. It cannot edit, run tests, or install anything, and it has 20 minutes and a $5 cap.
Decide
It ends with a verdict (valid, fixed, obsolete, duplicate, gated, or unclear), a confidence, and the evidence, which the agent stores on the card. A verdict stays fresh for 14 days, and a card with a fresh verdict can go to work.
Confirm
A verdict of fixed, obsolete, or duplicate at 0.8 confidence or better goes to a second read-only session on Opus, which checks the evidence on its own, in 10 minutes. Only a confirmed verdict closes the card: the agent comments with the evidence and the commits, moves it to the board's done column (QA when it has none), and says to move it back to To Do if it is wrong.
A gated card is flagged and labeled needs review, with a comment naming the gate. A valid or unclear card goes on to work. A closing verdict below 0.8, or one the second session does not confirm, is recorded as unclear with a comment saying why, and the card stays where it is. If a triage session fails, the card is left alone and tried again after a cooldown. docket-agent sweep-report writes a Markdown report of what triage found across the boards.
How a card ends
After every session the agent decides the outcome from three things: the card, the session's result, and the repository. It does not take the session's word for it.
| Fixed or superseded | The card is in QA, Review, Completed, or Done. The agent records the outcome on the card and posts a line to Chirp. |
|---|---|
| Deferred | The card is back in To Do, flagged. The session found something only a person can settle, such as a decision, a deploy nobody ordered, or spend. The agent posts a blocker line. |
| Failed | A crash, a timeout, an error, or a card left in the wrong place. The agent comments with the run, the reason, the commits it made, and the files it left uncommitted. It flags the card, adds needs review, assigns it to a person, moves it to the top of To Do, and posts a failure line. |
| Waiting for usage | The session was stopped because the account ran low. The card stays In Progress, and the same conversation resumes after the limit resets. |
| Login or billing trouble | The card goes back to To Do where it was, with its earlier assignee. The agent pauses itself and posts a blocker. |
Safety rails
Every rail below is in the agent's code, and each one has tests.
- Subscription only, with a billing guard
- Each session starts without any
ANTHROPIC_*variable and without the switches for Bedrock, Vertex, or Foundry, because a key in the environment would bill the API. The first event of every session must report that no API key is in use. If it reports anything else, the agent stops the session at once, returns the card to To Do, pauses itself, and posts a blocker. Thedoctorcommand checks the login the same way. - A usage gate
- The agent only takes capacity the account would otherwise leave unused. It reads the account's own rate-limit events, and runs a tiny Haiku probe when the last reading is more than ten minutes old. It holds back when any window is rejected, when the five-hour window is at 80 percent or more, when the seven-day window is at 90 percent or more, or when the seven-day window is more than ten points ahead of the week's pace. While it holds, it does not even read the boards.
- A stop line mid-session
- If a running session pushes the five-hour window to 95 percent, or any window is rejected, the agent stops it: an interrupt, then a terminate after 30 seconds, then a kill after 60. The card stays In Progress. After the reset, the agent resumes the same conversation, up to three times.
- Compare-and-set claims
- A claim carries the card's last-updated stamp, and the server checks it under a row lock. A 409 means someone else changed the card first, so two runners can never take the same card.
- The clean-repo rule
- A session starts only in a repository whose tracked files are clean, that is on its main branch, that has no merge or rebase in progress, and that no other run holds. A dirty tree means a person is working there, so the agent waits. If a run leaves tracked changes behind, the repository is held until it is clean again. The brief tells the session never to stash, reset, clean, or check out anyone else's work.
- It never deploys
- The brief tells every session not to deploy, not to spend, and to defer anything gated: it comments why, flags the card, adds
needs review, assigns a person, and moves the card back to To Do. - Exclusions beat every trigger
- Boards, repositories, and single cards can be excluded by configuration. An excluded card is skipped whatever its label or assignee, and the agent does not touch it.
- Time limits
- A session that reaches 240 minutes gets one 20-minute wrap-up before it is stopped. A session that is silent for 45 minutes draws one warning, and is not killed.
- Read-only triage is enforced
- Triage sessions start with deny rules for the edit tools and for git writes, rm, mv, package managers, test runners, and make. The rules are not trusted alone: after every triage session, whatever happened, the agent checks the repository. If anything moved, the verdict is thrown away and never reaches the card. If the session ran nothing that could write (another session committed in the meantime, say), the card is simply tried again soon. If its own record shows a command that could write, the repository is also held until a person clears it, a patch of the change is saved, and a person is told. Nothing is restored or reset.
- It runs a release, not a work tree
- The agent runs a copy of the committed code that never changes after it is built. An uncommitted edit in the working tree changes nothing, not even the brief a new session reads. An upgrade is one switch of a link plus a restart that leaves running sessions alone, and the previous release stays for a rollback. If one cycle of the agent hangs for 15 minutes, it writes out what it was doing and exits so launchd restarts it.
- No secrets in logs
- Tokens are read from the environment or the configuration and are never written to a log, a brief, or a Chirp line. The tests assert it.
More than one Mac
Other Macs can join the same boards. They run the same code, so the claim rules, the usage gate, and the billing guard apply to each, and they go easy on the machine's other jobs.
| Runner role | Only the primary Mac comments on a card that no repository matches. A runner skips it, so the comment is written once. A card whose repository is not on a Mac is skipped there, never deferred. |
|---|---|
| Triage only | A runner can be set to triage only: it reads cards and records verdicts but never starts a work session, for a Mac that can read the code but not push it. |
| A list of repositories | Each Mac works only the repositories under its own allowed paths, and a card outside them is skipped there. |
| Subscription token | A runner signs in with a subscription token kept in a file, with its own Claude configuration folder. The billing guard still requires that no API key is in use, and the token is never logged. |
| Polite load | Sessions start under nice, and none starts or resumes while the Mac's load per core is above a limit, so a film render or a test run wins. A runner starts with a nice value of 10 and a limit of 1.5. |
When a session runs long
When a session reaches its time limit, the agent does not just stop it. It stops that segment and resumes the same conversation once, with 20 minutes, and asks it to commit and push only if the change is complete and its tests pass. Otherwise it leaves the tree alone, says exactly where things stand (what is done, what is left, and which files changed), and sends the card back to To Do, flagged and labeled needs review.
If the wrap-up runs out too, or a run fails for any other reason and leaves tracked changes behind, the agent saves a patch of them in its records folder, a record it keeps, and names the patch and the files in the card's comment. It never restores, stashes, or resets anything, and the repository is held until it is clean.
Steering the agent
A person decides what the agent touches, and can stop it at any time.
| Opt in | Add the claude label to a card, or assign it to Claude. It works on any board the agent has a repository for, and opt-in cards go ahead of the sweep. |
|---|---|
| Opt out | Add the no agent label (or no-agent). The agent skips the card. |
| Flag it | A flagged card is left alone. So is an archived card, and so is any card outside a To Do column. |
| Send it back | The agent adds needs review when it defers or fails, and skips every card that carries it. Remove the label and the flag, and the card is eligible again. |
| Set the order | Opt-in cards come first. Within a board, cards keep Docket's own position order, which is the person's ranking, and the agent goes round-robin across the boards it sweeps. |
| Pause it | docket-agent pause stops new work until docket-agent resume. Sessions already running keep running. |
docket-agent install # write the config and load the LaunchAgent
docket-agent doctor # Claude login, Docket reachable, repository map, LaunchAgent
docket-agent candidates # dry run: what it would take next, and why it skips the rest
docket-agent status # heartbeat, usage gate, running cards, held repositories
docket-agent pause --reason "deploy freeze"
docket-agent resume
docket-agent dispatch <card-id> --ignore-usage-gate --wait # one card now
docket-agent sweep-report --project "<name>" # what triage found, as Markdown
docket-agent clear-hold <repo> # after a person has looked at a repository a triage session changed
docket-agent upgrade # switch to the newest committed release and restart
Keeping the board honest
Every state change is written to the card's metadata, so the board shows what the agent is doing, not what it meant to do. Each finished run adds a line to a ledger, and the agent posts to Chirp when it comes online, takes a card, finishes, defers, fails, holds for usage, resumes, or pauses.
Restarting the agent never kills a session. Each session runs in its own process group, and the agent adopts live runs again after a restart and reconciles the ones that died from their logs.
Questions about this tool?
Write to Renkara Media Group and a person will answer.