Git, review and shipping commands
Find the commit that broke a test, try a goal several ways at once, track intents, sign and verify who made a change, revert it, and ship a branch or a stack of them.
These commands work on a git repository. None of them push, merge or open anything unless the command says so.
venom bisect "npm ci && npm test" --good v1.4.0 --explain
venom try "make the parser accept trailing commas" -n 3 --check "npm test"
venom provenance HEAD
venom ship --no-mergevenom bisect
venom bisect "<test-command>" [--good <ref>] [--bad <ref>] [--explain] [--model <id>] [--timeout <s>] [--json] finds the commit that broke a test with git bisect run, in a throwaway worktree: your checkout is never touched. The test runs as sh -c "<test-command>" at each step: exit 0 is good, 125 skips the commit, anything else is bad.
| Option | Default | What it does |
|---|---|---|
--bad <ref> |
HEAD |
A commit where the test fails. |
--good <ref> |
found | A commit where it passes. Without it, first-parent history is walked back (1, 2, 4 … 128 commits) until the test passes. |
--explain |
off | Ask the model (the session's, or --model) why the culprit broke the test: one request with its diff and the test output, secrets scrubbed. |
--timeout <s> |
1800 |
Give up after this long. |
--json |
off | {ok, good, bad, steps, culprit, explanation, …}. |
A fresh worktree has no dependencies: install them in the command ("npm ci && npm test"). Exit 0 when a culprit is found, 1 when not, 2 on usage.
venom try
venom try "<goal>" -n <N> [options] runs the same goal as N attempts in N git worktrees at once, possibly on different gears, ranks them with a verifier and names the best. Nothing is merged: venom workspace merge <name> lands the winner (see Workspaces).
| Option | Default | What it does |
|---|---|---|
-n, --try <N> |
3 |
Attempts per round, 2–8. |
--check <cmd> |
none | The verifier, run in each worktree; exit 0 passes ("npm test"). |
--gears a,b,c |
the configured model | Gears to cycle through, one per attempt. |
--rounds <R> |
1 |
Rounds, 1–4; each round starts from the previous winner. |
--risk <tier> |
low |
low, medium or high, as for venom do. |
--budget <usd> |
1 |
Spend cap per attempt. |
--model <id>, --cwd <dir>, --json |
The model, the repository, JSON output. |
A passing check ranks first, then the smaller diff. Without --check the ranking is by diff size alone, which is weak evidence.
venom intent
The intent ledger: what is wanted, claimed by an agent, closed with evidence. Files live in ~/.venom/intents/, offline. Ids may be shortened to a unique prefix.
| Command | What it does |
|---|---|
venom intent new <title> [--goal <text>] [--constraint <text>]… [--accept <check>]… [--parent <id>] [--risk-usd <n>] |
Record an intent with its acceptance checks. |
venom intent list [--status open|claimed|closed|abandoned] [--parent <id>] |
List intents. |
venom intent show <id> |
One intent with its evidence. |
venom intent claim <id> [--by <name>] |
Claim it (default: $VENOM_AGENT, else you). |
venom intent evidence <id> <text> [--kind <kind>] [--ref <ref>] |
Attach evidence. |
venom intent close <id> [--evidence <text>] [--abandon] |
Close it; needs evidence (or --abandon), refused while sub-intents are open. |
All take --json.
venom provenance
Signed receipts for code changes: who made a commit and why.
| Command | What it does |
|---|---|
venom provenance <sha> [--trust <key id>…] [--depth <n>] [--json] |
Verify a commit's receipt (signature, tree and parents, the Venom-Receipt trailer, the links to earlier receipts) and print who made the change: agent, models, tools, permission decisions and human approvals. Exit 0 when it verifies and its signer is trusted (this machine's key, or --trust), 1 otherwise. |
venom provenance record [--session <id|latest>] [--intent <id>] [--no-amend] |
Sign a receipt for HEAD from a saved session, add the Venom-Receipt trailer to its message (amends HEAD; --no-amend leaves it, so the commit won't verify) and store the receipt in refs/notes/venom-provenance. --intent (default $VENOM_INTENT) names the intent it was made for. |
venom provenance key |
The key id of this machine's signing key (~/.venom/provenance.key, made on first use). |
Share receipts with git push origin refs/notes/venom-provenance.
venom revert
| Command | What it does |
|---|---|
venom revert <intent> [--rev <rev>] [--include <sha>…] [--json] |
List the commits whose verified receipt names the intent, the later commits that touch the same files (shown first: they may depend on it), the order of the reverts, and whether they apply cleanly (tried in a throwaway worktree). |
venom revert <intent> --apply [--dir <path>] [--test <cmd>] |
Make branch venom-revert/<intent> in a new worktree, revert the commits there newest first, and run --test in it. Nothing is pushed or merged. |
--include adds commits whose receipt was lost (a squash merge). Exit 0 when the reverts apply (and --test passes), 1 on a conflict, a failing test or no match, 2 on usage.
venom evidence
venom evidence [--base <ref>] [--json | --markdown] [--extra <file.json>] [--coverage <file>]… [--post <pr>] prints the evidence bundle for the current change: changed files, tests added, the impacted-test selection, diff invariants, and whatever --extra supplies (test runs, bench and eval deltas, session, screenshots, risk). Nothing runs and no model is called. --base defaults to HEAD (uncommitted changes; use main for a branch). --coverage takes a Go cover profile or lcov file and lists the added lines no test reaches. --post <pr> posts the markdown as one comment with gh.
venom ship
venom ship [--base <ref>] [--title <title>] [--no-merge] ships the current branch: the gate plan, the evidence bundle, a pull request, and the merge queue. --base defaults to origin/main, --title to the branch's last commit subject; --no-merge opens the pull request and posts the evidence without queueing it. Run it from a feature branch with a clean tree. The outcome is merged, needs-human, or failed with the stage. /ship does the same in a session.
venom stack
venom stack <status|submit|restack|land|split> [--base <ref>] [--dry-run] manages stacked pull requests: the branches between the trunk and HEAD, each on the one below.
| Subcommand | What it does |
|---|---|
status |
The stack, bottom first, with each branch's pull request. |
submit |
Push every branch and open (or retarget) its pull request on the branch below. |
restack |
Rebase every branch onto the one below. |
land |
Land the stack bottom up through the gate, one pull request at a time. |
split |
Cut this branch into a stack of small ones, dependencies first: --max-lines N (default 400), --name <n>, --check <cmd> run on every layer. |
--base is the trunk (default origin/main); --dry-run prints the order or plan for land and split.
venom capture
venom capture run --snapshot ./out --out before -- ./build.sh
venom capture diff before aftervenom capture run [--snapshot <dir>]… [--out <dir>] [--input <text>]… [--timeout <s>] [--cols N --rows N] -- <cmd…> records a command under a pseudo-terminal: a journal of input, output and exit, the rendered terminal frames, and before and after snapshots of the --snapshot directories. venom capture diff <a> <b> compares two recordings (for instance before and after a refactor): output, final screen and file effects, ignoring timestamps. It exits 1 when they differ. Offline; secrets are redacted. Defaults: --out ./venom-capture-<time>, --timeout 60, 80x24.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
venom bisect finds no culprit |
The test passes at --bad, fails at --good, or every candidate was skipped (exit 125). |
venom provenance exits 1 on your own commit |
It was amended or rebased after record, or recorded with --no-amend. |
venom revert matches nothing |
The commits' receipts were lost in a squash merge: add them with --include. |
venom ship or venom stack refuses |
Both need a clean tree; ship runs from a feature branch, stack from the top branch of the stack. |