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.89+ 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
Open your coding agent in this directory and send this prompt:
Use `qqq next --wait --json` to wait for the next task and work on it. Mark it complete, then repeat. Keep one waiter running; don't repeatedly poll for work.
The agent completes Build API before Build client becomes ready.
Repeated next calls return your active task until you complete or release it.
If no task is available, next exits with status 1 and prints the pickup message
(or null with JSON output). This also applies to --dry-run; --wait keeps
waiting instead. --explain remains a successful diagnostic, even for an empty queue.
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.
Recognized agent callers get JSON by default: native Codex sessions
(CODEX_THREAD_ID or CODEX_SESSION_ID), Claude Code sessions
(CLAUDE_CODE_SESSION_ID), and exact Herdr panes reporting an
agent. Use global --human for readable text, or --json to request JSON
explicitly. Ordinary shells keep readable output, including when piped.
Help and version output stay text.
See and edit the work
Browse tasks, read their details, and edit descriptions in one window. Click a task to open it, or use the keyboard:
| Key | Action |
|---|---|
| Shift+Up / Shift+Down | Move between tasks and a blank draft |
| Ctrl+S | Save |
| Ctrl+L | Edit tags |
| Ctrl+F | Filter tasks |
| Ctrl+G | Open task or bulk actions |
See the full TUI guide for navigation, child tasks, saved views, bulk selection, and shortcuts.
With optional Herdr integration, Ctrl+H creates a worker for a saved New task or opens its linked agent. Creation requires the pane's shell profile to start Codex.
For CLI workflows, see adding and editing, batch imports, and bulk actions.
Give your agent the queue
Use the prompt above in each agentic coding tool you want to work through the queue. Each worker needs a unique, stable identity.
--wait blocks until work is ready. --json returns full task data for the agent.
A worker using the same identity gets its active task back. Claims have no time
limit, but qqq marks tasks error when their owner is confirmed dead.
Return or retry work when a worker gets
stuck or its task needs recovery.
Native Codex or Claude Code session discovery can supply identity automatically.
Optional Herdr integration links live agents and lets Ctrl+H
create a queue worker from a saved New task. next always claims for its caller.
Leave --session and QQQ_SESSION unset for normal agent use. They force manual
ownership and bypass automatic session discovery and Herdr linking.
Route specialist workers by stored tags:
Repeated tags require every exact label; case and Unicode stay distinct. Existing owned tasks return even after selectors change. See tag matching and filter examples.
Save shared CLI/TUI selectors as project views:
Additional selectors combine with saved criteria using AND. Ctrl-B switches views
without losing unsaved drafts. Commit .qqq-views.json to share definitions.
See named views, visibility overrides and picker.