Mission control for your Claude Code agents.
Describe the work. Agents build it in their own worktrees, a fresh agent reviews it, main is fast-forwarded,
and one self-contained page shows every step as it happens.
| SKILLS 2 for Claude Code |
CLI Bun + TypeScript |
RUNTIME DEPENDENCY 1 marked |
DASHBOARD 1 file no server |
AGENTS AT ONCE up to 10 2 by default |
|
|
|
|
Tickets that wait on others are laid out in waves: what can run now, what the next wave frees, and a wave only one ticket wide, where the work cannot spread over agents, marked as the bottleneck.
|
|
Running one coding agent is easy to follow. Running five is not: which one is on what, which branch is safe to merge, who checked the work, and what did it all cost? The answers end up scattered across terminal tabs and a context window that gets compacted halfway through the afternoon.
agent-progress puts the answers on a board. You talk to one orchestrator session in Claude Code. It
questions you until each request is testable, then files it as a ticket. When you say go, a
dispatcher runs a builder agent per ready ticket, hands every finished build to a reviewer agent that
never saw it being written, and releases the result onto main. Every one of those steps is an
agent-progress command, and every command redraws progress.html. You keep that tab open and watch.
Nothing on the board is edited by hand.
The board draws itself. Each command takes the tracker's lock, writes its state atomically and re-renders the page before letting go. The page can never show a state the files did not hold, and it reloads itself within a minute of new data when idle, keeping your place.
Every ticket gets its own worktree. Builders work on a ticket-<id> branch in .claude/worktrees/,
never in your checkout. All worktrees write to one tracker, found through git's common directory, so
five agents still make one chart.
The reviewer did not write the code. Each review round is a fresh agent that starts from the builder's Handoff and the diff, is told to show the ticket does not hold, and re-runs every claim itself. It fixes what is in scope and files everything else as a low-priority ticket.
The rules live in code, not in prompts. Slots, review rounds and parking are decided by the dispatcher script. Another review round happens only when a pass reworked more lines of code than the dispatcher's rework threshold (comments and docs do not count). Two failed passes park a ticket for you; two agents in a row returning nothing stop the run as an outage instead of blaming the tickets.
Releases cannot collide. release checks the ticket, fast-forwards main and closes the review bar in
one lock hold. A branch that fell behind is told main-moved, rebases and tries again. Store the repository's
check line once with agent-progress checks "<line>", and every release first runs it on the exact commit it
would merge, in the branch's worktree; a failure is refused as checks-failed and changes nothing. On this board
a row's done pill means merged.
You see what every agent cost. The SubagentStop hook that init installs adds everything an agent processed,
cache reads included, to its row. agent-progress usage audits the same figures from the transcripts.
| Role | Runs as | Does |
|---|---|---|
| You | yourself | Describe the work, answer questions, say go, say stop. |
| Product owner | any other Claude Code session, with the agent-po skill it loads when asked to file |
Files tickets with a brief, its fact-finding in subagents, so grilling and research stay out of the orchestrator's context. Dispatches nothing. |
| Orchestrator | your Claude Code session, with /agent-progress-orchestrate |
Files tickets with a brief, launches the dispatcher, triages what comes back. Writes no code, reads no diffs. |
| Dispatcher | a Workflow script in .agent-progress/ |
Starts a builder per free slot, a reviewer per built ticket, decides rounds and parking. |
| Builder | a subagent, Opus at medium effort unless the ticket names another | Claims the ticket, builds in its worktree, leaves green checks and a Handoff. |
| Reviewer | a fresh subagent, the ticket's same model and effort | Tries to prove the build wrong, fixes, rebases, releases. |
| CLI and hook | agent-progress |
Holds the state, draws the page, records tokens when an agent stops. |
You can keep filing tickets while a run is going; it picks them up when its next agent returns, and a high-priority one goes first. Say stop and the agents in flight finish, unfinished builds pause, and the next run resumes them. The dispatcher's state and run id live on the board, so a compacted or restarted orchestrator picks up where it left off.
git clone https://github.com/AlexDM0/agent-progress.git && cd agent-progress
./setup.shIt offers to install Bun if it is missing and links the CLI; it changes nothing in your projects and installs no
skill globally: agent-progress init copies both skills into each repository it adopts. Getting the code running
walks through each step.
Updating. A git pull in this checkout updates the CLI and the skills' source. Then run
agent-progress update in every repository it tracks: it regenerates the dispatcher, the brief, the
skill copies and the other files it installed, and records their install version in .agent-progress/version.json. When the
pull changed the install version, most commands in that repository refuse at exit 1 until it has run
there, and say to run it; see
Install version.
cd ~/code/example-storefront
agent-progress init --project "Example Storefront"init writes nine things:
.agent-progress/, the tracker: the state file, the log (log.jsonl), atickets/folder, the dashboard and its lock.- The briefs:
.agent-progress/agent-brief.md, the orchestrator's, andbuilder-brief.mdandreview-brief.mdbeside it, each agent's own. .agent-progress/version.json, the install version of everything the tool installs.- A
.gitignoreentry for.agent-progress/, unless git already ignores it. - A managed block in
CLAUDE.mdtelling every session in the repository to track its work here. - A
SubagentStophook in.claude/settings.local.json, which records each agent's tokens. - The dispatcher,
.agent-progress/agent-progress-dispatch.js, generated byinitandupdate. - The worker agent definition,
.claude/agents/agent-progress-worker.md, set to Opus at medium effort. - The two skills, copied into
.claude/skills/agent-po/and.claude/skills/agent-progress-orchestrate/and git-ignored there, so Claude Code loads them in this repository only:agent-powhenever a session is asked to file a ticket, bug or research question (or on/agent-po), andagent-progress-orchestratefor the session that runs the board, which loadsagent-pofor its intake. - The reference,
.agent-progress/reference.md: the ticket format, the moves and the exit codes, which the briefs cite for an agent to read on demand.
The managed block, the hook, the dispatcher and the agent definition each have an opt-out flag, and agent-progress update refreshes the tool's files later,
never touching your tickets and log. agent-progress open shows the board.
Open Claude Code in the repository and type:
/agent-progress-orchestrate
Then describe what you want, one request or ten. Answer the questions until each ticket is testable, and say go. The board fills in from there.
Tip
The board allows two agents at once by default. agent-progress concurrency <n> raises it, up to ten.
| No network agent-progress itself makes no network request: no server, no telemetry, no CDN, no web fonts. |
Plain files All state is JSON and markdown in .agent-progress/ at the repository root, git-ignored. |
Your own agents The agents it tracks are your own Claude Code sessions. The page's view choices stay in your browser. |
Downloads happen only at setup: bun install fetches the packages, and if Bun is missing setup.sh
offers its official installer.
| Requires | Bun (1.2 or newer recommended), git, Claude Code |
| Runs in | your terminal and your Claude Code sessions; the dispatcher runs as a Claude Code Workflow script |
| Runtime dependency | marked, for ticket bodies on the page |
| Storage | .agent-progress/ at the repository root, shared by every worktree |
| Dashboard | one self-contained progress.html: Kanban · Progress · Tickets tabs, the Kanban board beside the Tickets tab rather than in place of it, an Epics tab once the board has epics and a Waves tab once a ticket waits on another; light, dark or auto. |
| Agents | builders and reviewers on Opus at medium effort, per ticket overridable; 2 at once by default, 10 at most |
| Source | github.com/AlexDM0/agent-progress |
- CLI reference: every command and flag, the exit codes, what
initandupdatewrite, the dashboard in detail and the files on disk. - Developing agent-progress: getting a checkout running, the checks every change must pass, the repository layout, the test helpers and guard specs, and the decisions behind the design.












