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.

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

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

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.

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

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

Beta, early access. Flags: agent_hooks_extended, agent_pause, change_provenance.

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

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.

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.

bumpkit memory ​

Beta, early access. Flag: codebase_memory.

What your team and agents learned about this code. See Agent Controls.

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.

bumpkit recall ​

Beta, early access. Flag: codebase_memory.

Print what your team learned about this code: approved 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.

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

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.

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

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.

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

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.

bumpkit claim KIND [RESOURCE] [flags]

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.

bumpkit renew ​

Beta, early access. Flag: swarm_claims.

Extend a claim you hold.

bumpkit renew CLAIM_ID [flags]

bumpkit unclaim ​

Beta, early access. Flag: swarm_claims.

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

bumpkit unclaim CLAIM_ID [flags]

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.

bumpkit intent [flags]

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.

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.

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.

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.

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.

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.

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.

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.

bumpkit agent-report [claims] [flags]

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.

test upload flags:

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.

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.

testdb lease flags:

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.

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

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.

bumpkit tried [DESCRIPTION] [flags]

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.

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.

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.

agents spend flags:

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.

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