tq — Task Queue
Job-queue based orchestration system for Claude Code. Combines a CLI/TUI with a Claude Code Plugin to manage multiple sessions via tmux.
Humans give instructions in natural language and monitor progress via TUI. The manager agent handles task breakdown, prompt tuning, and dispatching actions to worker sessions.
Highlights
- Job queue model — actions are queued and processed asynchronously by workers, with configurable concurrency limits (default: 3 interactive sessions)
- Manager agent — one Claude Code session manages others; humans just talk to it
- Delegates to Claude Code — no custom workflow language; just runs
claude in tmux, so skills, sub-agents, worktrees, and remote execution all work as-is
- CLI is for agents — JSON-only output,
--jq flag, agent-oriented --help; humans don't need to learn the CLI
- Schedule support — cron-based action generation for recurring tasks
Install
Prerequisites: tmux (required for dispatching interactive sessions)
# Homebrew (macOS / Linux)
brew install MH4GF/tap/tq
# Claude Code Plugin
claude plugin marketplace add MH4GF/tq
claude plugin install tq@tq-marketplace
Or download a binary from GitHub Releases.
Quick Start
# Register a project (sets working directory for tasks)
tq project create myapp ~/src/myapp
# Create a task under the project
tq task create "Implement feature X" --project 1
# Launch the TUI (starts the queue worker)
tq ui
Then open Claude Code in another terminal and talk to the manager agent:
/tq:manager
To create an action (spawns a new Claude Code session):
/tq:create-action Implement feature X and create a PR
The agent will tune the instruction, associate it with the right task, create the action, and the queue worker will automatically pick it up.
See CLI Reference for the full command list.
Configuration
The database lives at ~/.config/tq/tq.db by default. Override with:
--db <path> flag (highest precedence)TQ_DB_PATH environment variable
Useful for running multiple isolated queues (e.g. a separate DB for demos or testing).
Data Model
project → task → action
- project: groups tasks, sets default working directory
- task: unit of work (status: open, done, archived)
- action: dispatchable unit of work with an instruction (status: pending, running, done, failed, cancelled)
Design Principles
- SQLite is SSOT — the database is the canonical state store
- Queue Worker — processes one action at a time, keeping context fresh
- AI is hands only — Go handles orchestration; AI executes as a
claude worker
- TUI is read-only — humans observe via TUI; operations are issued through CLI
Action State Machine
dispatch/claim
┌─────────────────────────────┐
│ ▼
┌───────────┐ ┌───────────┐
│ pending │ │ running │
└───────────┘ └─────┬─────┘
▲ │ │
│ success│ │fail
│ ▼ ▼
│ ┌────────┐ ┌────────┐
│ │ done │ │ failed │
│ └────┬───┘ └───┬────┘
│ │ │
│ on_done │ │ reset
│ (new action) │ │
└───────────────────────┘ │
└──────────────────────────────────┘
* running → pending: reset command (kills tmux pane)
* done is terminal, but on_done can spawn a new action
Worker Types
Controlled via --meta on action create / schedule create:
| mode | Description |
|---|
interactive (default) | claude in tmux — fire-and-forget, worker reports via tq action done / tq action fail |
noninteractive | claude -p — captures stdout, auto-completes |
remote | Dispatched to remote worker |
Additional metadata keys:
permission_mode — Claude permission mode (e.g. "plan", "auto")worktree — Run in a git worktree for isolation (true/false)claude_args — Additional CLI arguments for claude (JSON array of strings, e.g. ["--max-turns","5"])
License
MIT
