# CLI: Agents

Run Bumpkit inside your coding agents and coordinate several of them.

## MCP server

To connect Claude without installing anything, use the hosted connector: `claude mcp add --transport http bumpkit https://bumpkit.dev/mcp` in Claude Code, or `https://bumpkit.dev/mcp` as a custom connector in the Claude desktop app. `bumpkit mcp connect` prints both, and `bumpkit mcp connections list` and `bumpkit mcp connections revoke` manage the apps you connected.

Run the built-in server with `bumpkit mcp`. Your agent starts this command and communicates over stdio. It uses your saved `bumpkit login` credentials or `BUMPKIT_API_KEY`, with the same workspace permissions and feature access.

```bash
bumpkit login
claude mcp add bumpkit -- bumpkit mcp
```

`bumpkit mcp config` prints copyable JSON for Cursor, Claude Desktop, and other MCP clients without changing files or including credentials. `bumpkit mcp --help` explains how to connect. See [MCP Server](/docs/mcp) for client configuration and tools.

## bumpkit guard

> **Beta, early access.** Flag: `agent_guard`.

Check an agent's work before it finishes or pushes. `guard` gates the working tree against `--base` with the policy at the base. As an agent's hook, it sends the agent back with the proven problems or the approval it needs. Run directly, as the git `pre-push` hook does, a change that only needs approval prints the approval the pull request will need and its dashboard link, then exits `0` so the pull request can be opened; proven problems still exit `1`. Every message names the workspace it checked, because approvals recorded in another workspace don't count. When Bumpkit can't be reached or the feature is off, it prints a note and exits `0`. With Close the loop on (Beta, flag `close_the_loop`), it also blocks while fix tasks are open on this branch, even when the gate passes. See [Agent Hooks](/docs/agent-hooks).

```text
bumpkit guard [--base REF] [--hook claude|cursor|codex|gemini|windsurf|cline]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--base` | Where this branch left the default branch; on the default branch itself, `HEAD` | Ref to compare against |
| `--hook` | | `claude`, `cursor`, `codex`, `gemini`, `windsurf` or `cline` to run as that agent's finish hook. `codex`, `gemini`, `windsurf` and `cline` need the `agent_hooks_extended` flag. |

## bumpkit hooks

> **Beta, early access.** Flag: `agent_guard`.

Install the agent and git hooks in this repository. With no flags, `hooks install` installs the Cursor and git hooks, plus the Claude Code hooks when the repository has a `.claude/` directory or a `CLAUDE.md`. See [Agent Hooks](/docs/agent-hooks).

```text
bumpkit hooks install [--claude] [--cursor] [--git]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--claude` | `false` | Install Claude Code hooks in `.claude/settings.json` (`recall` at session start, `pause` before shell commands, reads and writes, `guard` when the agent stops) and the MCP server in `.mcp.json` |
| `--cursor` | `false` | Install Cursor hooks in `.cursor/hooks.json`: `recall` at session start, `pause` before shell commands and `guard` when the agent stops |
| `--git` | `false` | Install a git `pre-push` hook that runs `bumpkit guard`. An existing `pre-push` hook isn't overwritten: add the line `bumpkit guard` to it yourself. |

### Beta: Codex, Gemini CLI, Windsurf, Cline and provenance

> **Beta, early access.** Flags: `agent_hooks_extended`, `agent_pause`, `change_provenance`.

```text
bumpkit hooks install [--claude] [--cursor] [--git] [--codex] [--gemini] [--windsurf] [--cline] [--provenance [--prompts]]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--codex` | `false` | Install Codex hooks in `.codex/hooks.json` (`recall` at session start, `pause` before shell commands and patches, `guard` before the agent stops) and the MCP server in `.codex/config.toml` |
| `--gemini` | `false` | Install Gemini CLI hooks and the MCP server in `.gemini/settings.json`: `recall` at session start and the release check after each agent turn |
| `--windsurf` | `false` | Install Windsurf hooks in `.windsurf/hooks.json` (the release check before Cascade runs `git push`), the MCP server in your user config, and the git `pre-push` hook |
| `--cline` | `false` | Install Cline hooks in `.clinerules/hooks` (`recall` when a task starts, the release check before `attempt_completion`), the MCP server in the Cline CLI settings, and the git `pre-push` hook |
| `--provenance` | `false` | Also record AI change provenance from each agent's sessions and tool calls (opt-in) |
| `--prompts` | `false` | With `--provenance`, also send a redacted summary of each prompt (opt-in) |

With agent pause, the Claude Code hooks also run `bumpkit pause --hook claude` before each shell command, read and write.

### Beta: open a pull request that adds the hooks

> **Beta, early access.** Flag: `agent_hooks_pr`. Owners, admins and policy admins.

```text
bumpkit hooks pr [--repo OWNER/NAME] [--json]
```

Opens the **Add Bumpkit agent hooks** pull request through the GitHub App. It adds the Claude Code, Cursor and Codex hooks with provenance recording (no prompt summaries) and the MCP servers in `.claude/settings.json`, `.mcp.json`, `.cursor/hooks.json`, `.codex/hooks.json` and `.codex/config.toml`, merged into the files already on the default branch, byte for byte what `bumpkit hooks install --claude --cursor --codex --provenance` writes. Running it again returns the open pull request, and says so when the default branch already has the hooks. `--repo` defaults to the origin remote. See [Agent Hooks](/docs/agent-hooks#add-the-hooks-with-a-pull-request).

## bumpkit memory

> **Beta, early access.** Flag: `codebase_memory`.

What your team and agents learned about this code. See [Agent Controls](/docs/agent-controls).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `add` | `bumpkit memory add TEXT [flags]` | Save a decision, pitfall, note or incident about a path |
| `list` (alias `ls`) | `bumpkit memory list [PATH]` | List memories for the repository or a path |
| `forget` | `bumpkit memory forget MEMORY_ID` | Delete a memory |

| Flag | Default | Description |
|------|---------|-------------|
| `--repository` | The origin remote | Repository URL (all `memory` subcommands) |
| `--kind` | `note` | `memory add`: `note`, `decision`, `pitfall` or `incident` |
| `--path` | The whole repository | `memory add`: file or directory it's about |

```bash
bumpkit memory add "Never call the billing API from a migration" --kind pitfall --path db/migrations
```

### Beta: memory approval

> **Beta, early access.** Flag: `memory_approval`.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `pending` | `bumpkit memory pending` | List memories agents saved that wait for a person's approval |
| `approve` | `bumpkit memory approve MEMORY_ID` | Approve a pending memory so agents recall it |
| `reject` | `bumpkit memory reject MEMORY_ID` | Reject a pending memory; it is never recalled |

## bumpkit recall

> **Beta, early access.** Flag: `codebase_memory`.

Print what your team learned about this code: approved [lessons](#bumpkit-lessons) first (Beta, flag `swarm_lessons`), then memories for the repository or a path, and the finding kinds recent releases were flagged for. As a session start hook, it hands the same text to the agent as context. It exits `0` unless a flag is wrong.

```text
bumpkit recall [--path PATH] [--hook claude|cursor|codex|gemini|cline]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--hook` | | `claude`, `cursor`, `codex`, `gemini` or `cline` to run as that agent's session start hook. `codex`, `gemini` and `cline` need the `agent_hooks_extended` flag. |
| `--path` | The whole repository | A file or directory |

## bumpkit pause

> **Beta, early access.** Flag: `agent_pause`.

Check a command before an agent runs it: allow, ask a human, or deny. As a hook, `pause` reads the tool call from standard input and replies in the agent's hook format, always exiting `0`. Run directly, it checks `COMMAND`, prints `allow` or the decision and reason, and exits `1` unless the command is allowed. Ask and deny decisions are recorded in Bumpkit; allowed commands aren't. With `agents:` budgets on (Beta, flag `agent_budgets`), the hooks also deny file writes outside the paths the agent is allowed, with the reason shown to the agent.

When you're not signed in, the feature is off for your workspace, or Bumpkit can't be reached, `pause` still checks the command, with the built-in local rules plus the repository's `agent:` section, and records nothing. See [Agent Controls](/docs/agent-controls).

```text
bumpkit pause [--hook claude|cursor|codex] [COMMAND...]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--hook` | | `claude`, `cursor` or `codex` to run as that agent's hook before a tool or shell command runs |

```bash
bumpkit pause rm -rf build/
```

## bumpkit provenance

> **Beta, early access.** Flag: `change_provenance`.

Turn on, turn off or read the record of who or what made a change: the agent, its version and model, the session, the tools it used and the human sponsor. See [Agent Hooks](/docs/agent-hooks).

```text
bumpkit provenance enable [--prompts] | disable | record --hook AGENT [--prompts] | show CHECK_ID | attest CHECK_ID
```

| Subcommand | Description |
|------------|-------------|
| `enable` | Add provenance recording to the agent hooks already installed here. `--prompts` also sends a redacted summary of each prompt (opt-in). |
| `disable` | Remove provenance recording from the installed hooks |
| `record` | Record one hook event. `--hook` names the agent whose hook payload is on stdin: `claude`, `cursor`, `codex`, `gemini`, `windsurf` or `cline`. |
| `show CHECK_ID` | Print a check's provenance as JSON |
| `attest CHECK_ID` | Print a check's provenance attestation as JSON |

## bumpkit claim

> **Beta, early access.** Flag: `swarm_claims`.

Lease a migration number, file, symbol, route, flag or env var before you use it, so other agents in the swarm don't take it at the same time. `KIND` is `migration`, `path`, `symbol`, `route`, `flag`, `env` or `other`. Leases expire after `--ttl` unless renewed with `bumpkit renew`. Release them with `bumpkit unclaim`. `bumpkit claim migration` without a number hands out the next free migration number, counting main, open branches, pull requests and other claims. See [Agent Swarms](/docs/agent-swarms).

```text
bumpkit claim KIND [RESOURCE] [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `$BUMPKIT_AGENT_ID`, or `cli` | Who holds the lease |
| `--dir` | `db/migrations` | The migrations directory, for `claim migration` |
| `--note` | | Why you need it, shown to other agents |
| `--repository` | The origin remote | `owner/name` |
| `--session` | `$BUMPKIT_SESSION`, or this host and shell | Which run of the agent |
| `--ttl` | `30m`; `24h` for `claim migration` without a number | How long the lease lasts before it must be renewed (at most `24h`) |

```bash
bumpkit claim path services/orders/helpers_test.go --ttl 2h
```

## bumpkit claims

> **Beta, early access.** Flag: `swarm_claims`.

List the active claims in this repository.

| Flag | Default | Description |
|------|---------|-------------|
| `--kind` | | Only claims of this kind |
| `--mine` | `false` | Only claims held by this agent (`$BUMPKIT_AGENT_ID`) |
| `--repository` | The origin remote | `owner/name` |

## bumpkit renew

> **Beta, early access.** Flag: `swarm_claims`.

Extend a claim you hold.

```text
bumpkit renew CLAIM_ID [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `$BUMPKIT_AGENT_ID`, or `cli` | Who holds the lease |
| `--session` | `$BUMPKIT_SESSION`, or this host and shell | Which run of the agent |
| `--ttl` | `30m` | How much longer the lease lasts |

## bumpkit unclaim

> **Beta, early access.** Flag: `swarm_claims`.

Release a claim you hold, so other agents can use the resource.

```text
bumpkit unclaim CLAIM_ID [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `$BUMPKIT_AGENT_ID`, or `cli` | Who holds the lease |
| `--session` | `$BUMPKIT_SESSION`, or this host and shell | Which run of the agent |

## bumpkit intent

> **Beta, early access.** Flag: `conflict_prediction`.

Declare what you will touch and see which branches, claims and agents it collides with. Bumpkit compares your declared paths and symbols, or your branch, with open pull requests, active claims and other agents' intents, and names each overlap. With no `--paths`, `--symbols` or `--calls`, the CLI reads your branch's changes since `--base` itself. It exits `1` when it predicts a conflict.

```text
bumpkit intent [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--adds` | | Symbols you will add, as `pkg.Func` |
| `--agent` | `$BUMPKIT_AGENT_ID`, or `cli` | Who holds the lease |
| `--base` | `origin/HEAD` | What your branch started from, when reading changes locally |
| `--branch` | | Your branch, compared once it is pushed |
| `--calls` | | Symbols your change calls, as `pkg.Func` |
| `--paths` | | Files or directories you will change |
| `--repository` | The origin remote | `owner/name` |
| `--session` | `$BUMPKIT_SESSION`, or this host and shell | Which run of the agent |
| `--symbols` | | Symbols you will change, as `pkg.Func` |
| `--ttl` | `2h` | How long other agents see this intent |

```bash
bumpkit intent --paths services/orders/reserve.go --symbols orders.Reserve
```

## bumpkit merge-plan

> **Beta, early access.** Flag: `merge_planning`.

A safe merge order for the open pull requests, and what main broke in each. Pull requests with the fewest overlaps merge first, and stacked pull requests follow their base. With `--recheck`, each waiting pull request is checked against main for signatures main changed that it uses. Needs the Bumpkit GitHub App.

| Flag | Default | Description |
|------|---------|-------------|
| `--recheck` | `false` | Re-check every waiting pull request against main now |
| `--repository` | The origin remote | `owner/name` |

## bumpkit stack

> **Beta, early access.** Flag: `stacked_prs`.

Show stacked pull requests, their merge order and each one's decision. A pull request whose base branch is another open pull request's head branch is stacked on it. Bumpkit tracks stacks from GitHub App events, checks each pull request on its own changes against its parent's head, and re-checks it when the parent's head moves or GitHub retargets it. Needs the Bumpkit GitHub App.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `list` | `bumpkit stack list --repository OWNER/REPO` | List the repository's stacks in merge order with each pull request's decision |
| `show` | `bumpkit stack show NUMBER --repository OWNER/REPO` | Show one pull request's stack, its position and what must merge first |

| Flag | Default | Description |
|------|---------|-------------|
| `--repository` | The origin remote | `owner/name` |
| `--json` | `false` | Print the stack as JSON |

A decision shows as current only when it was saved for the pull request's exact head and base commits. Otherwise the pull request reads `Not checked at this head and base`, and no decision is implied.

```bash
bumpkit stack list --repository acme/shop
bumpkit stack show 131 --repository acme/shop --json
```

## bumpkit contracts

> **Beta, early access.** Flag: `contract_alerts`.

Alert branches when an internal function, method or type they call changes. See [Agent Swarms](/docs/agent-swarms).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `sync` | `bumpkit contracts sync [--base REF] [flags]` | Record this push's signature changes and the symbols this branch calls |
| `alerts` | `bumpkit contracts alerts [flags]` | List contract alerts for a branch |
| `ack` | `bumpkit contracts ack ALERT_ID` | Acknowledge an alert once the call sites are updated |
| `close` | `bumpkit contracts close [--branch NAME] [flags]` | Stop tracking a merged or abandoned branch |

Run `contracts sync` on every push, in CI or by an agent. Other open branches calling a changed symbol's old signature are alerted by pull request comment, webhook and MCP. Alerts for this branch are printed, and the command exits `1` when there are any.

| Flag | Default | Description |
|------|---------|-------------|
| `--base` | The pull request base, the push's before, or the merge base with origin | Where the change starts |
| `--branch` | The current branch | Branch |
| `--owner` | `BUMPKIT_AGENT_ID`, else this API key | Who to alert for this branch |
| `--pr` | The one GitHub Actions is running for | This branch's pull request |
| `--repository` | The origin remote | Repository |

`contracts alerts` takes `--all` (include acknowledged alerts), `--branch` and `--repository`. `contracts close` takes `--branch` and `--repository`.

## bumpkit coverage

> **Beta, early access.** Flag: `verified_reports`.

Upload CI coverage as evidence for agent reports.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `upload` | `bumpkit coverage upload --profile cover.out [flags]` | Upload a Go coverage profile for a commit, signed by the CI job's OIDC token |

In GitHub Actions with `permissions: id-token: write`, the upload carries the job's OIDC token, so Bumpkit knows the profile came from CI for that repository and SHA, not from an agent. Bumpkit computes total coverage, and diff coverage against each report's diff.

| Flag | Default | Description |
|------|---------|-------------|
| `--diff-percent` | | Diff coverage as measured by CI (trusted only with an OIDC token) |
| `--no-oidc` | `false` | Upload with the API key only, without the CI job's OIDC token |
| `--profile` | `cover.out` | The Go coverage profile |
| `--repository` | The origin remote | Repository |
| `--sha` | `HEAD` | The commit the profile measured |

## bumpkit agent-report

> **Beta, early access.** Flag: `verified_reports`.

Report what an agent claims about a commit and have Bumpkit verify each claim. Bumpkit checks each claim against the GitHub checks for that exact SHA, coverage uploaded by CI, and the real diff, and answers verified, contradicted or unverifiable per claim. The command exits `1` when any claim is contradicted, so an orchestrator can trust the exit code instead of the agent's summary.

```text
bumpkit agent-report [claims] [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `BUMPKIT_AGENT_ID` | The agent making the claims |
| `--base` | The pull request's base, else the parent | The commit the change starts from |
| `--branch` | The current branch | Branch |
| `--coverage` | | Claimed total coverage percent |
| `--diff-coverage` | | Claimed coverage percent of changed lines |
| `--file` | | A file the commit changes (repeatable; claims the exact set) |
| `--files-count` | | Claimed number of files changed |
| `--lint-clean` | `false` | Claim lint is clean |
| `--migration` | | A migration the commit adds (repeatable) |
| `--no-migrations` | `false` | Claim the commit adds no migrations |
| `--pr` | The one GitHub Actions is running for | Pull request number to comment on |
| `--repository` | The origin remote | Repository |
| `--sha` | `HEAD` | The full commit SHA the claims are about |
| `--tests-pass` | `false` | Claim the tests pass (`--tests-pass=false` claims they fail) |

```bash
bumpkit agent-report --tests-pass --diff-coverage 100 --lint-clean --no-migrations
```

## bumpkit test

> **Beta, early access.** Flag: `flaky_tests`.

Flaky test registry and regression evidence: upload results and triage failures.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `upload` | `bumpkit test upload --file results.xml [flags]` | Upload a CI run's test results (JUnit XML or `go test -json`) |
| `triage` | `bumpkit test triage [--file results.json] [--test NAME] [flags]` | Say whether failing tests are known flaky or likely real, with history |
| `flaky` | `bumpkit test flaky [flags]` | List known flaky tests |
| `expected` | `bumpkit test expected [--base REF] [--head REF]` | List the tests a change's blast radius expects, and why (Beta, flag `regression_evidence`) |
| `attest` | `bumpkit test attest --file results.xml [--base REF] [--head REF]` | Upload test results and the tests expected for this commit, attested by the CI job (Beta, flag `regression_evidence`) |
| `evidence` | `bumpkit test evidence [--sha SHA] [--pull-request N]` | Show which expected tests passed, failed or didn't run on a commit (Beta, flag `regression_evidence`) |

`test upload` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--attempt` | `GITHUB_RUN_ATTEMPT` | The run attempt |
| `--branch` | The current branch | Branch |
| `--file` | | JUnit XML or `go test -json` output |
| `--format` | Detected | `junit` or `go-test-json` |
| `--repository` | The origin remote | Repository |
| `--run-key` | `GITHUB_RUN_ID` | Identifies the CI run |
| `--sha` | `HEAD` | The commit the tests ran on |

`test triage` reads failing tests from `--test` names or from the run's output in `--file`. It exits `1` when any failure is likely real, `0` when every one is known flaky. It takes `--file`, `--format`, `--repository`, `--sha` (the commit the tests failed on) and `--test` (a failing test's name, like `pkg/path.TestName`, repeatable). `test flaky` takes `--limit` (default `100`, max 500) and `--repository`.

`test expected` takes `--base` (default: the pull request's base, else the latest tag), `--head` (default: the pull request's head, else `HEAD`) and `--policy`. `test attest` takes the same flags, plus `--file`, `--format` (`junit` or `go-test-json`, default detected) and `--repository`. It exits `0` when tests fail, because the gate reads them; it exits `1` when the upload fails. `test evidence` takes `--repository`, `--sha` and `--pull-request`, which counts merge-commit attestations only from that pull request. See [Regression evidence](/docs/release-checks#regression-evidence).

## bumpkit testdb

> **Beta, early access.** Flag: `test_isolation`.

Lease an isolated Postgres database for one agent run. The CLI creates each lease on your test server, the one in `TEST_DB_ADMIN_URL`, copied from `TEST_DB_TEMPLATE` when set, and refuses any server whose host isn't in `TEST_DB_ALLOWED_HOSTS`. Bumpkit records the lease. Once its TTL passes, the next `testdb lease` or a `testdb sweep` drops it; nothing drops it on a timer, so run `testdb sweep` on a schedule if leases can sit idle. The CLI only ever creates or drops databases named `bk_lease_*`, and caps the active leases on the server (`TEST_DB_MAX_LEASES`, default `20`). See [Beta variables](/docs/cli-flags#beta-variables).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `lease` | `bumpkit testdb lease [--ttl 1h] [flags]` | Create a test database and print its URL |
| `list` | `bumpkit testdb list` | List this workspace's leased test databases |
| `release` | `bumpkit testdb release NAME` | Drop a leased test database now |
| `sweep` | `bumpkit testdb sweep` | Drop every expired leased database on the test server |

`testdb lease` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `BUMPKIT_AGENT_ID` | The agent run it's for |
| `--ttl` | `1h` | How long the lease lasts before a sweep may drop it (1m to 24h) |

```bash
export DATABASE_URL=$(bumpkit testdb lease --agent "$BUMPKIT_AGENT_ID")
go test ./...
```

## bumpkit lessons

> **Beta, early access.** Flag: `swarm_lessons`.

Rules every agent in the swarm follows, proposed by agents and approved by people. A lesson has a kind (`practice`, `pitfall`, `decision`, or `dropped` for something the team chose not to build), applies to paths and areas, and is versioned: `--supersedes` proposes a new version, and approving it supersedes the old one. Approved lessons reach agents first in `bumpkit recall`, the session start hooks and the `lessons` MCP tool, capped at 20 lessons and about 4,000 characters. Pending, rejected and retired lessons never reach agents.

A key can't approve or reject a lesson proposed with a key of the same person, or with a key that was since deleted, and a key that isn't tied to a person can't approve anything. Review those in the dashboard inbox, or ask a teammate to use their key. The proposer's name comes from `BUMPKIT_AGENT_ID`, then `BUMPKIT_AGENT`.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `propose` | `bumpkit lessons propose TEXT [flags]` | Propose a lesson (up to 1000 characters); it reaches agents once a person approves it |
| `list` (alias `ls`) | `bumpkit lessons list [flags]` | List approved lessons, or others with `--status` |
| `approve` | `bumpkit lessons approve LESSON_ID` | Approve a proposed lesson so every agent gets it |
| `reject` | `bumpkit lessons reject LESSON_ID` | Reject a proposed lesson |
| `retire` | `bumpkit lessons retire LESSON_ID --reason TEXT` | Retire an approved lesson that no longer holds; the reason (at least 10 characters) is kept with it |

Every subcommand takes `--repository` (repository URL, default: the origin remote).

| Flag | Subcommand | Default | Description |
|------|------------|---------|-------------|
| `--area` | `propose`, `list` | | An area it's about, like `migrations`, `tests`, `auth`, `api`, `ui` or `billing` (repeatable on `propose`) |
| `--kind` | `propose` | `practice` | `practice`, `pitfall`, `decision` or `dropped` |
| `--path` | `propose`, `list` | The whole repository | A path or glob it applies to (repeatable on `propose`) |
| `--supersedes` | `propose` | | The lesson ID this is a new version of |
| `--status` | `list` | `approved` | `approved`, `pending`, `retired`, `superseded`, `rejected` or `all` |
| `--reason` | `retire` | | Why it no longer holds |

```bash
bumpkit lessons propose "Every migration runs inside a transaction; never edit a migration that already shipped." --kind pitfall --path db/migrations --area migrations
bumpkit lessons list --status pending
```

## bumpkit tried

> **Beta, early access.** Flag: `tried_before`.

Has this been tried? Before you build something, describe it, name the paths and symbols it touches, or both. Bumpkit searches release history for matching reverts, removed features and APIs, dropped decisions and past gate blocks. Each result links to its release and, for GitHub repositories, the commit.

```text
bumpkit tried [DESCRIPTION] [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--path` | | A path the change touches (repeatable) |
| `--repository` | The origin remote | Repository URL |
| `--symbol` | | A function, type or route it touches (repeatable) |

```bash
bumpkit tried "realtime websocket notifications" --path services/notify --symbol Stream
```

## bumpkit inbox

> **Beta, early access.** Flag: `approval_inbox`.

One approval inbox for the swarm, ranked by risk (low, medium or high): gate decisions that need approval or failed, paused agent commands, memories waiting for approval and lesson proposals. Items are named `KIND:ID`, with kind `gate`, `command`, `release_batch`, `release_publish`, `memory` or `lesson`. The inbox needs a key tied to a person, and every decision is audited with the approver.

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `list` (alias `ls`) | `bumpkit inbox list [--filter all\|releases\|commands\|context]` | What waits for a person, ranked by risk. Merged, closed and superseded releases are left out |
| `approve` | `bumpkit inbox approve [KIND:ID] [--note TEXT] [--no-browser] [--timeout 10m]` | Approve one item |
| `deny` | `bumpkit inbox deny [KIND:ID] [--note TEXT] [--no-browser] [--timeout 10m]` | Deny or reject one item |
| `batch` | `bumpkit inbox batch KIND:ID... --confirm "approve N low-risk items"` | Approve several low-risk items at once |

Gate items (`gate:ID`) and paused commands (`command:ID`) need a person signed in to the dashboard, on the **Approvals** page. With an API key, `approve` and `deny` print a `403 HUMAN_APPROVAL_REQUIRED` refusal with the link. On that page, approving a gate item needs a note of at least 10 characters and the override role (owners, admins and policy admins). It isn't an approval vote: it records a break-glass override of that exact commit. The gate's approval rules, such as "anyone except the author", don't count it, and someone else reviews it later with `bumpkit override review`. The pull request's GitHub check re-runs with the override right away. Gate items can't be denied from the inbox. A gate run on a local diff with no commit SHA doesn't appear; CI and API gate runs at a full SHA do.

A release draft (`release_batch:ID`) runs the same browser vote as `bumpkit release approve ID` or `bumpkit release deny ID`: it prints a link and a one-time code, and you confirm in your browser. Approving an approved release (`release_publish:ID`) publishes it, like `bumpkit release publish ID`.

Without `KIND:ID`, `approve` and `deny` list what's waiting. In a terminal you pick one by number, and a gate item asks for its note. Otherwise each item is printed with its exact command and the command exits `1`.

`batch` approves up to 50 low-risk items, and `--confirm` must be exactly `approve N low-risk items` (`item` for one). The server checks this too, and refuses medium- and high-risk items: decide those one at a time.

```bash
bumpkit inbox list
```

## bumpkit agents

> **Beta, early access.** Flags: `agent_budgets` (`spend`, `usage`, `violations`), `agent_track_records` (`records`).

Agent budgets, scopes, violations and track records. Budgets and scopes live under `agents:` in `bumpkit.yml`, keyed by an agent id or a glob: `max_open_prs`, `max_changed_lines`, `paths_allow`, `paths_deny`, `areas_deny`, `spend_limit` (US dollars per calendar month, UTC) and `on_violation` (`block` or `approve`). The gate checks every agent on a change, and each broken limit becomes a reason that fails the gate or asks for approval. See the [bumpkit.yml Reference](/docs/bumpkit-yml).

| Subcommand | Usage | Description |
|------------|-------|-------------|
| `spend` | `bumpkit agents spend --agent ID --usd AMOUNT [flags]` | Record what an agent spent, counted against `spend_limit` |
| `usage` | `bumpkit agents usage` | Open pull requests, open changed lines and this month's spend per agent |
| `violations` | `bumpkit agents violations [--limit 50]` | Recent times an agent went outside its budget or scope (max 500) |
| `records` | `bumpkit agents records [--days 90]` | Each agent's track record by work type: releases, clean, reverted, fixed up within 7 days, blocked by the gate and failed required checks, with a score |

`agents spend` flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--agent` | `BUMPKIT_AGENT_ID`, then `BUMPKIT_AGENT` | The agent id |
| `--note` | | What it was for |
| `--repository` | | The repository the work was for |
| `--usd` | | Amount in US dollars |

Track records count checks of the same commits as one release, by work type (`tests`, `migrations`, `auth`, `api`, `ui`). `gate.require_approval: [{agent_track_record_below: 0.8}]` asks a person to approve changes from agents below the bar.

```bash
bumpkit agents spend --agent claude --usd 7.50 --note "model tokens for the refund task"
bumpkit agents usage
bumpkit agents records --days 90
```