✦ Sirius Forester · α Canis Majoris · local-first

The foreman for your coding-agent fleet.

Sirius claims tasks from a local issue tracker, locks the code each task touches, runs your agent, and refuses to call anything done until the affected tests pass. SQLite ledger: no cloud, no accounts, no LLM calls of its own.

one claim per task

one lock per symbol

tests gate completion

a receipt every time

Get started Read the docs

sirius run --workers 2 oak · elm · ndjson

{"worker":"sirius/oak","phase":"claim","issue":"AMT-12"}{"worker":"sirius/elm","phase":"claim","issue":"AMT-15"}{"worker":"sirius/oak","phase":"lock","symbols":["auth::verify"]}{"worker":"sirius/oak","phase":"gate","result":"PASS [subset(3)]"}{"worker":"sirius/elm","phase":"receipt","forward":true,"reverse":true}

Early alpha · v0.1.0 Prebuilt binaries for macOS, Linux, and Windows, each checksummed and Sigstore-signed. The full loop needs Hayvenhurst and Ametrite, both public.

α Why a foreman § 01 / 06

Run three agents against one repo,
and the same four failures appear fast.

Sirius is not an issue tracker, a code graph, CI, or a merge tool. It is the supervisor loop that makes the tools you already have safe to run in parallel.

Failure 01t+00:04

Two agents grab the same task.

Both burn tokens on the same issue, then fight over the merge.

one claim per task, enforced at the ledger

Failure 02t+00:11

Edits collide silently.

Two workers touch the same function; last write wins and nobody notices.

one lock per symbol, claimed before work starts

Failure 03t+00:26

“Done” without running the tests.

An agent declares victory without exercising the tests its change affects.

the gate fails closed: affected tests must pass

Failure 04t+7d

A week later, nobody knows why.

A function changed, the agent is gone, and the reasoning went with it.

every completion files a two-way receipt

β The loop § 02 / 06

Eight phases. Every iteration.

Claim order is enforced: issue first, symbols second, release in reverse. A lock collision releases the issue back with a comment naming the blocker.

claimissue from the tracker

mapissue → symbols

locksymbols in the graph

briefcontext for the agent

workyour agent, your model

gateaffected tests must pass

receipttwo-way provenance

releasereverse claim order

Exit codes: 0 ok · 1 failure · 2 usage error · 3 gate blocked. Every command takes --json.

γ Commands § 03 / 06

Four verbs, honestly instrumented.

Works for humans and CI, not just agents: file a receipt by hand, read provenance in either direction, gate any completion.

sirius linkfile a receipt by hand

$ sirius link AMT-7 --symbols auth::verify,auth::mint
linked issue AMT-7 → 2 symbols (forward: true, reverse: true)

sirius whyprovenance, both directions

$ sirius why auth::verify   # issues & decisions behind this symbol
$ sirius why AMT-7          # symbols this issue touched

sirius gatetest-gate a completion

$ sirius gate AMT-7 --tier safe --target-status in_review
gate safe for AMT-7: PASS [subset(3)] (3 tests) → in_review

sirius runthe loop, N workers

$ sirius run --workers 3 --from todo \
    --agent-cmd 'claude -p "fix the claimed issue"'
# {"worker":"sirius/oak","phase":"gate","result":"PASS"}

δ Provenance § 04 / 06

Every change carries its reason.

A receipt stamps the symbols onto the issue and the issue onto each code node, forward and reverse. Ask sirius why from either side, a week or a year later.

sirius why auth::verify

issue    AMT-7   harden token verify
decision D-3     rotate signing keys quarterly
gate     PASS    2026-07-02 · subset(3)

✦ receipt#000042

issueAMT-7: harden token verify

symbolsauth::verify · auth::mint

decisionD-3

gatePASS [subset(3)] · 3 tests

forwardtrue, symbols stamped on issue

reversetrue, issue stamped on nodes

gate · pass

Measured, not marketed

0double claims — 30-min, 4-worker soak

< 2%gate-escape rate — 95-regression corpus

100%provenance coverage — every done issue

Fixture-mode harnesses today — live numbers when the loop is measured end to end. Reproduce any of them: bun run bench/soak.ts. See the benchmarks

ε Quickstart § 05 / 06

On your machine in two minutes.

No toolchain needed — prebuilt binaries are checksummed and Sigstore-signed. sirius doctor checks the five facts Sirius depends on and tells you exactly what is missing. The gate fails closed until you give it your test command.

~/your-repo · sirius

$ /sirius:install-binary         # Claude Code plugin: verifies + installs the signed binary
# or, without the plugin: curl -fsSL .../install-sirius.sh | sh
# or, from source (needs Rust ≥ 1.74): cargo install --path .
$ cd /path/to/your/repo          # one that has .ametrite/ and .hayven/
$ sirius init                    # creates .sirius/{sirius.db,config.json}
$ sirius doctor
[OK]   amt_present_and_schema: amt 0.1.0, ametrite schema v4 (>= v3)
[FAIL] hayven_daemon_7777: no 200 from http://localhost:7777
CONTRACT DRIFT DETECTED

ζ The fleet § 06 / 06

Four instruments, one suite.

Sirius writes only its own ledger. It talks to its companions strictly through their CLIs.

sirius-forester ↗

The foreman. Claims, locks, gates, receipts. Rust, SQLite, offline.

hayvenhurst ↗

The code graph. Locking, affected-test selection, provenance stamps.

ametrite ↗

The issue tracker. Local Linear+Obsidian for agents; schema ≥ v3.

catryna wikinelli ↗

The wiki. Living MDX docs your agent writes and your team reads, in .docs/.