Skip to content
Docs menu

Intent ledger

Record what is wanted as an intent with goals, constraints and acceptance checks, and let agents claim it, attach evidence and close it with venom intent.

View .md

An intent records what is wanted, not a task to schedule. Each has a goal, constraints, acceptance checks and an optional risk budget. An agent claims it, attaches evidence as it goes, and closes it with evidence, or abandons it. Sub-intents hang off a parent, and a parent cannot close while one of them is open or claimed.

venom intent new "Fix the flake" --goal "no flaky test" --constraint "no new deps" \
  --accept "10 green runs" --risk-usd 1.5 [--parent <id>]
venom intent list [--status open|claimed|closed|abandoned] [--parent <id>]
venom intent show <id>
venom intent claim <id> [--by name]
venom intent evidence <id> "10 runs green" [--kind test] [--ref <url-or-path>]
venom intent close <id> [--evidence <text>] [--abandon]

Rules

Rule Behaviour
Ids Can be shortened to a unique prefix.
Claiming Exclusive. The same claimer again is a no-op; another name is refused (exit 1). --by defaults to VENOM_AGENT, else the OS user.
Closing Needs evidence unless you pass --abandon.
Output --json prints the record. Usage errors exit 2.
Storage One JSON file per intent under ~/.venom/intents/, mode 0600, written by rename. No network.

The ledger only records. It never grants a permission or decides a merge, and nothing from it enters the model's prompt or tool list.

Intents on the orchestrator

Requests can be charged to an intent with the X-Venom-Intent header (at most 128 bytes). The orchestrator keeps a spend account per intent and refuses a request over its budget with 402 intent_budget_exceeded. A commit's provenance receipt can record the intent it was made for, and venom revert <intent> finds the commits by it.

From code

The library is @venom/harness/intents (IntentStore), for apps that want the same ledger.