Skip to content

About

Per-repository progress tracker for AI orchestrators: tasks on a Gantt chart, stateful markdown tickets, a log, and a self-contained dashboard regenerated on every command

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

agent-progress icon: four coloured Gantt bars and a red now-line on a dark rounded square

agent-progress

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

Watch your agents work: the Progress tab of the Example Storefront board in light mode, animated from 09:10 to 13:36 as the now-line sweeps across, Gantt bars grow under their epic heads, pills move from unstarted to wip to reviewing to done, and review rows appear above their tickets

Every ticket on one board: the Kanban tab with lanes To do, In progress, Review, Awaiting merge, Done and a collapsed Abandoned lane; cards show priority, type, tokens, what a ticket waits on and when it moved

Light or dark: the same Progress tab split diagonally, light theme on the left and dark on the right Click for the whole story: the detail panel of ticket #002 listing its six phases with how long each lasted
Tickets an agent can build unasked: the Tickets tab with priorities, a waiting-on note and branches Know what every agent cost: the token column of the chart in dark mode

What waits on what

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.

See what waits on what: the Waves tab with a Done column and waves Now, Wave 2, Wave 3 and Wave 4; Wave 3 holds only #012 One-page checkout and is marked one at a time, and pointing at #012 lights the chains behind it, from #001 in Done, from #004 and from #008 through #011, and the two tickets it frees, #013 and #014

Every epic, wave by wave: the Epics tab with the Checkout redesign and Customer account cards, each with its roll-up and three dependency rows: the tickets of the other epic it waits on, its own tickets in the board's waves, and the other epic it frees through #012 or through #004 and #008 Point at a card, see its prerequisites: the Kanban tab narrowed to the Checkout redesign epic with To do ordered by wave, Now, Wave 2 and a one-at-a-time Wave 3; hovering #012 One-page checkout draws arrows from #011 in To do and #001 in Done

About

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.

Highlights

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.

How it works

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.

One ticket, start to merge: you describe the work, the orchestrator files a ticket, on your go the dispatcher starts a builder in a worktree, a fresh agent reviews it, a large rework loops to another round, otherwise release fast-forwards main and done means merged; findings outside scope become low-priority tickets and the SubagentStop hook adds tokens to the row

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.

Where everything goes — the architecture

Everything goes through one CLI: you talk to the orchestrator session, which launches the dispatcher, which runs builders and reviewers; all of them and the SubagentStop hook call the agent-progress CLI, which locks, writes atomically and re-renders; the CLI writes .agent-progress/, which becomes progress.html in your browser; reviewers fast-forward main on release

Get started

1. Install once

git clone https://github.com/AlexDM0/agent-progress.git && cd agent-progress
./setup.sh

Terminal output of setup.sh: Bun found, dependencies installed and agent-progress on your PATH, then Tooling ready

It 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.

2. Adopt a repository

cd ~/code/example-storefront
agent-progress init --project "Example Storefront"

Terminal output of agent-progress init for Example Storefront, listing tracker, brief, dashboard, .gitignore entry, CLAUDE.md block, SubagentStop hook, dispatcher workflow and worker agent, followed by agent-progress open

init writes nine things:

  • .agent-progress/, the tracker: the state file, the log (log.jsonl), a tickets/ folder, the dashboard and its lock.
  • The briefs: .agent-progress/agent-brief.md, the orchestrator's, and builder-brief.md and review-brief.md beside it, each agent's own.
  • .agent-progress/version.json, the install version of everything the tool installs.
  • A .gitignore entry for .agent-progress/, unless git already ignores it.
  • A managed block in CLAUDE.md telling every session in the repository to track its work here.
  • A SubagentStop hook in .claude/settings.local.json, which records each agent's tokens.
  • The dispatcher, .agent-progress/agent-progress-dispatch.js, generated by init and update.
  • 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-po whenever a session is asked to file a ticket, bug or research question (or on /agent-po), and agent-progress-orchestrate for the session that runs the board, which loads agent-po for 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.

3. Run 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.

Privacy

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.

Information

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

Further reading

  • CLI reference: every command and flag, the exit codes, what init and update write, 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.

About

Per-repository progress tracker for AI orchestrators: tasks on a Gantt chart, stateful markdown tickets, a log, and a self-contained dashboard regenerated on every command

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages