Skip to content
Docs menu

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.

View .md

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-merge

venom 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 after

venom 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.