---
title: Intent ledger
description: 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.
section: reference
order: 150
audience: [user, builder, agent]
sources: [docs/intents.md, cli/src/intent.ts, packages/harness/src/intents]
features: [reference.doc-intents]
---

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.

```bash
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 {#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 {#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 {#code}

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

## Related

- [x-venom headers](/docs/reference/headers.md)
- [Error codes](/docs/reference/errors.md)
