README
¶
heavyq
Agents say done. heavyq knows.
Your coding agent says the tests pass. Which commit did they pass on? heavyq keeps a ledger of every heavy command it runs, keyed by the exact code it ran on, so "proven" is a lookup and not a claim. It is also a priority, resource-aware queue that keeps six agents from running six test suites at once.
curl -fsSL https://github.com/LysCongThanh/heavyq/releases/latest/download/install.sh | sh # checks the sha256; or: go install github.com/LysCongThanh/heavyq@latest, see docs/install.md
heavyq hook install claude # Claude Code agents use the queue without being told
heavyq init --agents-md # write heavyq.toml, tell agents to run the gate first
Claude Code plugin: see docs/claude-code.md.
What it is
heavyq is a single static Go binary with no daemon: the queue is a directory and the proof is a JSONL
ledger on your machine. It is local-first. Nothing leaves the box unless you add an SSH remote
yourself. It works with Claude Code today (a PreToolUse hook, heavyq hook install claude) and with
any agent that can run a shell command; a Codex adapter is next. Linux first, macOS supported.
Run, Prove, Steer
Run. Wrap a heavy command. Lower number goes first, light jobs jump ahead, and a job starts only if the machine has RAM and CPU left. Identical runs on the same commit share one result.
heavyq 3 --lane api -- npm test # waits its turn; exit 75 if --max-wait runs out
heavyq 4 --cache -- npm test # same clean commit already tested? reuse that result
heavyq status # what runs, what waits, and why
Prove. A gate in heavyq.toml (or one detected from go.mod, package.json, pytest, Cargo.toml)
says what "done" means. gate status answers from the ledger in about 20 ms, for the exact tree checked
out now, uncommitted edits included.
heavyq gate status # PROVEN or NOT PROVEN on this tree; exit 0 or 1
heavyq gate run # run what is not proven yet, through the queue, cached
Steer. When the caller is an agent, heavyq says little and ends with a digest the agent can act on.
Work items (heavyq item ls|claim|release|done|block: claim, prove, finish) are in docs/items.md.
heavyq brief is the thread of the work in 300 tokens, injected after every compaction; heavyq steer guard adds a
Stop gate that will not let an agent stop while the item it holds is unproven (docs/steer.md).
heavyq: FAIL go test ./... · exit 1 · tree 3f2a9c1d7b0e · 12s
--- FAIL: TestRun (0.01s)
run_test.go:42: got 1, want 2
log: ~/.local/state/heavyq/logs/20261102T010203.123456Z-4242-wt-api.log (full output, 212 KiB)
next: fix the failure above, then re-run this command
Dashboard
heavyq dash is read-only; heavyq dash --control lets the page cancel jobs, change priorities and pause
machines. It listens on loopback only. See docs/dashboard.md.
Documentation
| Topic | Page |
|---|---|
Install (script, go install, archives), verify signatures, completions, man page |
docs/install.md |
| The queue: priorities, slots, resource gate, quickstart | docs/queue.md |
Gates, heavyq.toml, what "proven" means |
docs/gates.md |
| Claude Code hook (zero config) and what it relies on | docs/claude-code-hook.md, docs/claude-code.md |
| Agent mode: terse output and the result digest | docs/agent-mode.md |
| History as a ledger (commit, tree, session) | docs/history.md |
Receipts: a shareable, privacy-rounded summary (heavyq receipts --share) |
docs/receipts.md |
Ledger tail reader, indexes, heavyq doctor --reindex |
docs/ledger.md |
| Cache and coalescing: never run the same gate twice | docs/cache-and-coalescing.md |
| Spare machines over SSH, by exact commit | docs/remote.md |
| Pools: ports, databases, browsers handed out to parallel agents | docs/pools.md |
Mentor: break repeat failures, measured with a holdout (heavyq mentor) |
docs/mentor.md |
| Dashboard, JSON snapshot, control API | docs/dashboard.md |
heavyq top: a terminal monitor for a tmux pane, with display modes |
docs/top.md |
heavyq flow: where work waits (needs-you, the constraint, throughput), derived from the ledger, leases and hooks |
docs/flow.md |
heavyq statusline (a segment for Claude Code's status line, with a forecast and local notices) and heavyq recap |
docs/statusline.md, docs/recap.md |
| Configuration and environment variables | docs/configuration.md |
Editor support: JSON Schemas for heavyq.toml, the user config and status --json |
docs/configuration.md |
| Exit codes | docs/exit-codes.md |
Work items: claim, prove and finish (heavyq item) |
docs/items.md |
Steer: the brief after compaction, the stop gate (heavyq steer off|guard|destroy), the delivery canary |
docs/steer.md |
Preflight: GO or NO-GO before an unattended run, and the run span it opens (heavyq preflight, heavyq run end|ls|current) |
docs/preflight.md |
| Long runs: the 10-minute path from preflight to recap, for unattended Claude Code agent runs | docs/long-runs.md |
| Stances, leases, anchor | docs/stances.md, docs/leases.md, docs/anchor.md |
Comparison with pueue, task-spooler, flock |
docs/comparison.md |
| Platform support (Linux, macOS) | docs/platform-support.md |
The GIFs are recorded from real runs: docs/tapes/proof.tape (regenerated in CI on every release) and
demo/demo.tape.
Contributing
See CONTRIBUTING.md. Issues labelled good first issue are scoped to an afternoon. Coding agents: start with AGENTS.md. Security reports: SECURITY.md.
License
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
agentmode
Package agentmode is what heavyq says to a coding agent instead of a person: detection of who is calling, the bounded capture of a command's output, the result digest printed after it, and the usage card of `heavyq help agents`.
|
Package agentmode is what heavyq says to a coding agent instead of a person: detection of who is calling, the bounded capture of a command's output, the result digest printed after it, and the usage card of `heavyq help agents`. |
|
anchor
Package anchor reads the durable "what is left" list of a repository: the goal and the checklist items in .heavyq/anchor.md, plus read-only checklists found in other markdown files (plan phases, docs).
|
Package anchor reads the durable "what is left" list of a repository: the goal and the checklist items in .heavyq/anchor.md, plus read-only checklists found in other markdown files (plan phases, docs). |
|
cache
Package cache stores the output and exit code of commands keyed by the exact committed code they ran on, and coalesces identical in-flight runs.
|
Package cache stores the output and exit code of commands keyed by the exact committed code they ran on, and coalesces identical in-flight runs. |
|
cli
Package cli implements the heavyq command line.
|
Package cli implements the heavyq command line. |
|
config
Package config loads and validates the heavyq TOML configuration.
|
Package config loads and validates the heavyq TOML configuration. |
|
control
Package control carries operator requests (cancel a ticket, change its priority, pause a machine) from the dashboard or the CLI to the heavyq processes that own the tickets.
|
Package control carries operator requests (cancel a ticket, change its priority, pause a machine) from the dashboard or the CLI to the heavyq processes that own the tickets. |
|
dash
Package dash serves the heavyq dashboard: an embedded single-page app and a small JSON/SSE API over the queue snapshot, history and control mailbox.
|
Package dash serves the heavyq dashboard: an embedded single-page app and a small JSON/SSE API over the queue snapshot, history and control mailbox. |
|
deadline
Package deadline bounds the time a hook handler may take.
|
Package deadline bounds the time a hook handler may take. |
|
flow
Package flow derives how work moves: a timeline of states per work item (else per session span), fleet aggregates, throughput and the current constraint.
|
Package flow derives how work moves: a timeline of states per work item (else per session span), fleet aggregates, throughput and the current constraint. |
|
flow/collect
Package collect holds the optional collectors of internal/flow: the sources that need git or gh and so can never be part of the pure derivation.
|
Package collect holds the optional collectors of internal/flow: the sources that need git or gh and so can never be part of the pure derivation. |
|
flowstate
Package flowstate is the I/O around internal/flow: the materialised state at <git common dir>/heavyq/flow/state.json (atomic, debounced, written under flock) and the append-only log of hook observations beside it.
|
Package flowstate is the I/O around internal/flow: the materialised state at <git common dir>/heavyq/flow/state.json (atomic, debounced, written under flock) and the append-only log of hook observations beside it. |
|
flowview
Package flowview is what the status line, the recap and the notifier need around the materialised flow state (<git common dir>/heavyq/flow/state.json): the file-system repository finder, which keeps the status line free of git, and the adapters from a *flow.Snapshot to the forecast and the notifier.
|
Package flowview is what the status line, the recap and the notifier need around the materialised flow state (<git common dir>/heavyq/flow/state.json): the file-system repository finder, which keeps the status line free of git, and the adapters from a *flow.Snapshot to the forecast and the notifier. |
|
forecast
Package forecast answers the one question a person has while agents work: "will it be done when I need it, and is it on track?".
|
Package forecast answers the one question a person has while agents work: "will it be done when I need it, and is it on track?". |
|
gitutil
Package gitutil wraps the few git queries heavyq needs.
|
Package gitutil wraps the few git queries heavyq needs. |
|
history
Package history is the run ledger: one JSON line per finished run, bound to the code it ran on (commit, tree, dirty) and to who ran it (session, item, gate).
|
Package history is the run ledger: one JSON line per finished run, bound to the code it ran on (commit, tree, dirty) and to who ran it (session, item, gate). |
|
history/historytest
Package historytest generates synthetic run ledgers for tests and benchmarks of the ledger readers (tail reader, indexes, hook latency).
|
Package historytest generates synthetic run ledgers for tests and benchmarks of the ledger readers (tail reader, indexes, hook latency). |
|
hook
Package hook decides whether an agent's shell command should run through heavyq and produces the Claude Code PreToolUse response that rewrites it.
|
Package hook decides whether an agent's shell command should run through heavyq and produces the Claude Code PreToolUse response that rewrites it. |
|
itemstatus
Package itemstatus derives the status of a work item from facts, and only from facts: the anchor line (declared proof, needs, checkbox), the lease store, the events log and the proofs in the run ledger.
|
Package itemstatus derives the status of a work item from facts, and only from facts: the anchor line (declared proof, needs, checkbox), the lease store, the events log and the proofs in the run ledger. |
|
lease
Package lease lets parallel agents, in different worktrees of one repo, claim items without ever working on the same one.
|
Package lease lets parallel agents, in different worktrees of one repo, claim items without ever working on the same one. |
|
ledgerindex
Package ledgerindex keeps small, rebuildable indexes next to the run ledger so that hot paths (gate status, hooks, why, the Tower) never scan it.
|
Package ledgerindex keeps small, rebuildable indexes next to the run ledger so that hot paths (gate status, hooks, why, the Tower) never scan it. |
|
mentor
Package mentor breaks repeat failures and measures whether it helps.
|
Package mentor breaks repeat failures and measures whether it helps. |
|
metrics
Package metrics measures machine resources used by the admission gate.
|
Package metrics measures machine resources used by the admission gate. |
|
notify
Package notify pushes a local notice when the flow changes in a way a person should know about, once per state change and never more than a daily budget:
|
Package notify pushes a local notice when the flow changes in a way a person should know about, once per state change and never more than a daily budget: |
|
pools
Package pools hands out named resources (ports, database names, browser seats) to parallel runs.
|
Package pools hands out named resources (ports, database names, browser seats) to parallel runs. |
|
preflight
Package preflight decides, before a long unattended run, whether it can succeed without a human: a goal and items exist, every item has a runnable proof, nothing waits on an answer, the machine has room, no permission prompt would block the agent, and the quota is not nearly spent.
|
Package preflight decides, before a long unattended run, whether it can succeed without a human: a goal and items exist, every item has a runnable proof, nothing waits on an answer, the machine has room, no permission prompt would block the agent, and the quota is not nearly spent. |
|
procinfo
Package procinfo reads process identity and CPU usage.
|
Package procinfo reads process identity and CPU usage. |
|
proof
Package proof answers one question: has this exact code passed this command? It is derived entirely from the run ledger.
|
Package proof answers one question: has this exact code passed this command? It is derived entirely from the run ledger. |
|
queue
Package queue stores tickets as files in a queue directory.
|
Package queue stores tickets as files in a queue directory. |
|
recap
Package recap answers "how is it going, what landed, what should I do?" in one screen, from facts the caller has already gathered (items, the flow state, recent ledger records).
|
Package recap answers "how is it going, what landed, what should I do?" in one screen, from facts the caller has already gathered (items, the flow state, recent ledger records). |
|
receipts
Package receipts summarises what heavyq did over a window of the ledger: exact counts (Compute) and a privacy-rounded version of them (Share).
|
Package receipts summarises what heavyq did over a window of the ledger: exact counts (Compute) and a privacy-rounded version of them (Share). |
|
redact
Package redact hides likely secrets in command lines.
|
Package redact hides likely secrets in command lines. |
|
remote
Package remote runs work on spare machines: metrics probes, pushing exact commits to a bare repo there, and running a job in a temporary worktree.
|
Package remote runs work on spare machines: metrics probes, pushing exact commits to a bare repo there, and running a job in a temporary worktree. |
|
repoconfig
Package repoconfig loads the per-repository file heavyq.toml, which lives at the git root and says what "proven" means for that repository: named gates, each a list of shell commands.
|
Package repoconfig loads the per-repository file heavyq.toml, which lives at the git root and says what "proven" means for that repository: named gates, each a list of shell commands. |
|
runident
Package runident defines what "the same run" means, once: the run_id.
|
Package runident defines what "the same run" means, once: the run_id. |
|
runspan
Package runspan records a run span: the plan of one long, usually unattended stretch of agent work (a harness turn, a workflow, a night).
|
Package runspan records a run span: the plan of one long, usually unattended stretch of agent work (a harness turn, a workflow, a night). |
|
schedule
Package schedule holds heavyq's pure scheduling rules: who may claim which machine, the resource gate, and when a command is safe to run remotely.
|
Package schedule holds heavyq's pure scheduling rules: who may claim which machine, the resource gate, and when a command is safe to run remotely. |
|
sessionmeta
Package sessionmeta keeps one small record per coding-agent session: the model, the agent version and the rate-limit headroom, at <git common dir>/heavyq/sessions/<session>.meta.json.
|
Package sessionmeta keeps one small record per coding-agent session: the model, the agent version and the rate-limit headroom, at <git common dir>/heavyq/sessions/<session>.meta.json. |
|
slots
Package slots implements execution slots as flock(2) lock files.
|
Package slots implements execution slots as flock(2) lock files. |
|
snapshot
Package snapshot defines the machine-readable state of heavyq: the output of `heavyq status --json` and the payload the dashboard streams.
|
Package snapshot defines the machine-readable state of heavyq: the output of `heavyq status --json` and the payload the dashboard streams. |
|
stance
Package stance holds "stances": short documents that describe a way of thinking (breakthrough, converge, skeptic, ...).
|
Package stance holds "stances": short documents that describe a way of thinking (breakthrough, converge, skeptic, ...). |
|
statusline
Package statusline prints heavyq's segment of Claude Code's status line and keeps it honest about its budget: Claude Code debounces the status line at 300 ms and a slow script blocks updates, so everything here reads files that already exist (the materialised flow state), never runs git and never computes flow.
|
Package statusline prints heavyq's segment of Claude Code's status line and keeps it honest about its budget: Claude Code debounces the status line at 300 ms and a slow script blocks updates, so everything here reads files that already exist (the materialised flow state), never runs git and never computes flow. |
|
steer
Package steer is what heavyq says to an agent without being asked: the brief that survives compaction, and the stop gate that wants proof.
|
Package steer is what heavyq says to an agent without being asked: the brief that survives compaction, and the stop gate that wants proof. |
|
tomlkeys
Package tomlkeys is the strict-key check shared by the config parsers (internal/config, internal/repoconfig): which key of a decoded TOML file the schema does not define, and the line where it is written.
|
Package tomlkeys is the strict-key check shared by the config parsers (internal/config, internal/repoconfig): which key of a decoded TOML file the schema does not define, and the line where it is written. |
|
tui/app
Package app is the heavyq top program: a model that turns keys and snapshots into view state, a fetcher that builds snapshots without overlapping, a painter that writes only changed lines, and the loop that ties them to a terminal.
|
Package app is the heavyq top program: a model that turns keys and snapshots into view state, a fetcher that builds snapshots without overlapping, a painter that writes only changed lines, and the loop that ties them to a terminal. |
|
tui/input
Package input turns the raw bytes of a terminal in raw mode into keys and commands.
|
Package input turns the raw bytes of a terminal in raw mode into keys and commands. |
|
tui/render
Package render draws the heavyq top screen.
|
Package render draws the heavyq top screen. |
|
tui/term
Package term owns the terminal for a full-screen program: raw mode, the alternate screen, and giving the terminal back in every way a program ends.
|
Package term owns the terminal for a full-screen program: raw mode, the alternate screen, and giving the terminal back in every way a program ends. |
|
tui/width
Package width measures and cuts text by what a terminal shows, in cells.
|
Package width measures and cuts text by what a terminal shows, in cells. |
|
tools
|
|
|
changelog
command
Command changelog folds changelog.d/ fragments into CHANGELOG.md and checks pull requests for one.
|
Command changelog folds changelog.d/ fragments into CHANGELOG.md and checks pull requests for one. |
|
mangen
command
Command mangen writes the heavyq(1) manual page, generated from the command table in internal/cli.
|
Command mangen writes the heavyq(1) manual page, generated from the command table in internal/cli. |
Click to show internal directories.
Click to hide internal directories.