qqq
Give your coding agents a shared queue.
You write the tasks. Agents claim the next ready one, report progress, and mark it done. qqq keeps the queue in your project, with a terminal dashboard for the work you want to inspect or change yourself.
Get started · Agent setup · Docs
Why a queue?
- Multiple agents, clear ownership. Workers sharing the same local project claim separate tasks.
- Dependencies that mean something. “Build the client” waits until “Build the API” is complete. Priorities choose which ready task comes next.
- Context that survives a session. Descriptions, updates, screenshots, and history stay with the task when you return, retry, or hand off work.
SQLite stores tasks in .qqq/qqq.db; images live in .qqq/images/. No server or
account needed. Your agent runs the code and checks; qqq tracks the work.
Install
Requires Rust 1.85+ and a C compiler. The command is qqq.
Install from source for development features.
Try it
Start in an empty directory so the example task IDs match:
ID STATUS PRI TASK
1 New 0 Build API
2 New 0 └── Build client
Claim the API task. Once your work is done, record an update and complete it:
# Do the work, then:
The last command claims Build client. Completing its parent made it ready.
Repeated next calls return your active task until you complete or release it.
For your own project, run qqq init at its root and use the IDs returned by add.
Commands also work from subdirectories. Add .qqq/ to your .gitignore.
See and edit the work
Pipe multiline descriptions with qqq add --stdin, or load a complete plan with
qqq import plan.json --dry-run followed by qqq import plan.json.
Independent prerequisites can gate integration work while keeping its tree parent:
qqq add "Integrate API and UI" --parent 1 --depends-on 2 --depends-on 3.
Manage extras with edit's --depends-on, --remove-depends-on, and
--clear-depends-on; all prerequisites must complete before a new claim.
See batch schema and piping examples.
Inspect readiness, owners and blockers with qqq status. Preview selection reasons
with qqq next --explain; neither command claims work. Both support --json.
See queue diagnostics for filters and owner context.
Browse the tree, read task details, and edit descriptions in one window. Click a task to load it, scroll each pane, or use the keyboard:
| Key | Action |
|---|---|
| Shift+Up / Shift+Down | Move between tasks and a blank draft |
| Ctrl+S | Save |
| Ctrl+L | Go to task ID; retain unsaved drafts |
| Ctrl+P | Create a child of the selected task |
| Ctrl+/ | Filter tasks |
| Ctrl+G | Open task actions |
| Ctrl+H | Open linked Herdr agent; shown only for tasks with a Herdr link |
| Esc | Close the filter, clear the editor, then exit; changed drafts ask before discard |
Task details and qqq show display assignment in two aligned rows:
Harness session (name) and Orchestrator session (name).
qqq add opens the built-in editor too. Prefer Vim or another editor? Set
EDITOR and use qqq add --edit.
Give your agent the queue
Give each worker a unique, stable session ID, replacing agent-1 for each worker.
To keep working as new tasks arrive, start with this /goal prompt:
/goal Use `qqq next --wait` to pick up the next task and work on it. Complete
each task after its checks pass, then get the next one. Loop indefinitely.
Keep the blocking wait running; don't wake up repeatedly to poll status.
--wait blocks until work is ready. --json returns full task data for the agent.
A restarted worker using the same session gets its current task back; claims do
not expire. Return or retry work when a
worker gets stuck.
Native Codex session discovery can supply identity automatically. Optional
Herdr integration links live agents or opens new agent
tabs. Explicit sessions and --local work independently.