Agent Swarms ​

Several agents in one repository collide, duplicate work and overstate what they did; these features coordinate them and check their claims, for teams running many agents at once.

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it.

When several agents work in one repository at once, they pick the same migration number, edit the same files, break each other's call sites and report work they didn't do. These features coordinate the swarm and check what agents claim.

For the controls that apply to a single agent (guard, pause, memory, provenance), see Agent Controls. Every command is in the CLI Reference, every endpoint in the API Reference, and every MCP tool is in the MCP server. Most swarm tools appear only when their flag is on; the Approvals, agents, lessons review, contracts and test database management tools are always listed, and the API refuses them while the flag is off.

Identify each agent ​

Swarm commands record which agent and run did something. Pass --agent and --session on each command, or set them in each agent's environment:

BUMPKIT_AGENT_ID is the canonical name. BUMPKIT_AGENT is accepted as an alias.

Without a session, the CLI uses this host and shell. The MCP server uses its own session ID, so pass the same session when you renew or release a claim from MCP.

Claims ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: swarm_claims.

A claim is a lease on a resource. An agent claims a migration number, file, symbol, route, feature flag key or env var before it uses it, renews the claim while it works, and releases it when done.

bumpkit claim migration
bumpkit claim path services/orders/helpers_test.go --ttl 2h --note "new test helpers"
bumpkit claim symbol coord.newRepo
bumpkit claims --kind migration
bumpkit renew CLAIM_ID --ttl 1h
bumpkit unclaim CLAIM_ID

bumpkit claim migration counts the numbers in your local migrations directory and in other agents' claims, then holds the next free one for you. With the GitHub App installed on the repository for your workspace, it also counts the numbers on main and in open branches and pull requests; without the App, those are skipped.

If someone else holds the resource, the API answers 409 with code CLAIM_HELD, the holder, and a free alternative when there is one. bumpkit claims --mine lists only your claims.

Only the agent and session that hold a claim can renew or release it. To release another agent's claim, use a key created by a workspace owner or admin; the claim records released by <email>. Any other key gets 403 FORBIDDEN, and the refusal is written to the audit log as claim.release.denied (or claim.renew.denied).

The MCP claim and next_migration tools take ttl_seconds (default 1800 for claim, 86400 for next_migration; at most 86400).

Conflict prediction ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: conflict_prediction.

Before an agent starts or pushes work, it declares the paths and symbols it will touch, or its branch. Bumpkit compares them with open pull requests, active claims and other agents' intents, and reports overlapping hunks, the same new files, changed signatures of what it calls, and same-named symbols in the same package, with evidence.

bumpkit intent --paths services/orders/reserve.go --symbols orders.Reserve
bumpkit intent --branch feature/checkout-v2
bumpkit intent

bumpkit intent exits 1 when it predicts a conflict. The MCP tool is declare_intent; the endpoints are POST /v1/intents and GET /v1/intents.

Merge planning ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: merge_planning. Needs the GitHub App.

bumpkit merge-plan orders the repository's open pull requests so the ones with the fewest overlaps merge first and stacked pull requests follow their base, with the reason for each position.

bumpkit merge-plan
bumpkit merge-plan --recheck

With --recheck, each waiting pull request is merged with main using git merge-tree and checked for signatures main changed that it uses. Bumpkit also re-checks waiting pull requests whenever main moves, and reports the result on the pull request, to your outbound webhook as the pull_request.recheck event, and to agents polling merge_notifications.

Verified agent reports ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: verified_reports.

An agent's summary says tests pass; the report checks it. bumpkit agent-report sends an agent's claims about a commit. Bumpkit checks each one against GitHub checks for that exact SHA, coverage uploaded by CI, and the real diff, and answers verified, contradicted or unverifiable per claim.

bumpkit agent-report --tests-pass --diff-coverage 100 --lint-clean --no-migrations
bumpkit agent-report --sha 4b7a1d2... --file services/orders/reserve.go --coverage 87.5

The report's verdict is contradicted if any claim is, else unverifiable if any claim is, else verified. The command exits 1 when any claim is contradicted, so an orchestrator can trust the exit code instead of the agent's summary. unverifiable usually means CI hasn't produced the evidence yet: push and let CI run first.

Upload coverage from CI ​

Coverage claims are checked against a Go coverage profile CI uploads:

permissions:
  id-token: write
steps:
  - run: go test -coverprofile=cover.out ./...
  - run: bumpkit coverage upload --profile cover.out

Inside GitHub Actions with 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.

The MCP tool report_work takes the same claims and posts the result on the pull request when you pass pull_request.

Internal contract alerts ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: contract_alerts.

When a push changes the signature of a Go function, method or type, open branches that call the old signature are alerted with the old and new signature and their call sites, by pull request comment, webhook and MCP.

Run bumpkit contracts sync on every push, in CI or by an agent. It records the signatures this branch changed or removed, and the ones its changed lines call. Alerts for this branch are printed.

bumpkit contracts sync
bumpkit contracts alerts
bumpkit contracts ack ALERT_ID
bumpkit contracts close --branch feature/old

The MCP tool contract_alerts takes branch, all and repository. Call it before you push and again before you merge. Endpoints: POST /v1/contracts/sync, GET /v1/contracts/alerts, POST /v1/contracts/alerts/{id}/ack, DELETE /v1/contracts/branches.

Flaky test registry ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: flaky_tests.

Bumpkit tracks test results per CI run and commit. A test that passes and fails on the same commit is marked flaky. When tests fail, triage says whether each failure is known flaky or likely real, with history.

go test -json ./... > results.json
bumpkit test upload --file results.json
bumpkit test triage --file results.json
bumpkit test triage --test services/orders.TestReserve
bumpkit test flaky

Each failing test gets the verdict known_flaky or likely_real. bumpkit test triage exits 1 when any failure is likely real, and 0 when every one is known flaky. Re-run known flaky tests instead of changing code for them.

The MCP tool test_triage takes tests, sha and repository. Endpoints: POST /v1/tests/runs, POST /v1/tests/triage, GET /v1/tests/flaky.

Per-agent test databases ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: test_isolation.

Each agent run gets its own Postgres database, so agents never share test data.

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

The CLI and MCP server create the database themselves from these variables in the agent's environment. Bumpkit records each lease and enforces the quota.

Bumpkit only ever creates or drops databases named bk_lease_*. A workspace holds at most 20 active leases.

MCP tools: test_database_lease (agent, ttl_minutes, default 60) and test_database_release (name). Endpoints: see Test database leases.

Swarm lessons ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: swarm_lessons.

A lesson is a repository-wide rule every agent follows. Any agent can propose one; only a person can approve it. Each lesson has a kind, the paths and areas it applies to, and a version.

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 recall --path db/migrations

A person reviews the proposals:

bumpkit lessons approve LESSON_ID
bumpkit lessons reject LESSON_ID
bumpkit lessons retire LESSON_ID --reason "We moved to online schema changes."

How lessons work:

• Agents get them at session start. bumpkit recall and the session start hooks print approved lessons first, and the lessons MCP tool returns them. Pending, rejected and retired lessons never reach agents. Recall carries at most 20 lessons and about 4,000 characters of lesson text.
• People approve. A key can't approve 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 (403 FORBIDDEN). The dashboard inbox and a teammate's key can.
• Versions. --supersedes proposes a new version in the same lineage. Approving it supersedes the old one. Retiring a lesson needs a reason.
• Duplicates. Proposing the same text again returns the existing lesson.
• Who proposed it. The proposer's name comes from BUMPKIT_AGENT_ID, then BUMPKIT_AGENT.

MCP tools: lessons (path, area, repository) and propose_lesson (body, kind, paths, areas, supersedes, repository).

GET /v1/memories also returns lessons when the flag is on. An unknown supersedes ID answers 404 LESSON_NOT_FOUND; approving, rejecting or retiring an unknown ID answers 404 NOT_FOUND.

Has this been tried? ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: tried_before.

Before building something, an agent or a person describes it, names the paths and symbols it touches, or both. Bumpkit searches the repository's release history for what happened last time.

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

Each result links to its release page and, for GitHub repositories, the commit. With the findings only and ephemeral retention modes, commit subjects aren't stored, and with ephemeral, commit authors aren't either. Reverts are still found by commit hash.

The MCP tool is has_this_been_tried (query, paths, symbols, repository). The endpoint is POST /v1/tried with repository, query, paths and symbols; it returns query, tried, summary and evidence.

Approval inbox ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: approval_inbox.

One inbox for everything that waits for a person: gate decisions that need approval or failed, paused agent commands, pending memories and lesson proposals. Each item has a risk score: low, medium or high. In the dashboard it is the Inbox, with filters for releases, agent commands and context. Releases whose pull request is merged or closed, or that have a newer commit, drop off the list. In Slack, /bumpkit inbox shows the same list, only to you.

bumpkit inbox list
bumpkit inbox list --filter releases

Decide one item, or approve several low-risk ones at once:

bumpkit inbox approve lesson:ID
bumpkit inbox deny memory:ID
bumpkit inbox batch lesson:ID lesson:ID memory:ID --confirm "approve 3 low-risk items"

The kinds are gate, command, release_batch, release_publish, memory and lesson. bumpkit inbox approve release_batch:ID runs the browser vote of bumpkit release approve, and with no item it lists what's waiting with the exact command for each.

• Batch approval accepts only low-risk items, at most 50 per call, and the --confirm text must be exactly approve N low-risk items (item for one). The server checks this too. Medium- and high-risk items are refused with "is medium risk; decide it on its own".
• Gate items and paused commands need a person signed in to the dashboard, on the Approvals page. An API key is refused with 403 HUMAN_APPROVAL_REQUIRED and the link, including from the CLI and MCP. A paused command also needs a write role. Gate items need a note of at least 10 characters; approving one is recorded as an override of the gate for that commit, so it needs the override role. Gate decisions 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.
• Audit. Every decision is audited with who made it, for example lesson.approve, memory.approve and inbox.batch_approve.

The inbox API takes a person's key: GET /v1/inbox, POST /v1/inbox/decide with kind, id, approve and note, and POST /v1/inbox/batch with items (each kind and id) and confirm. gate and command items answer 403 HUMAN_APPROVAL_REQUIRED for a key.

Agent budgets and scopes ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_budgets.

The agents: section of bumpkit.yml gives each agent, or each glob of agent IDs, a budget and a scope:

agents:
  claude-*:
    max_open_prs: 2
    max_changed_lines: 40
    paths_allow: [services/notify/**]
    paths_deny: [services/billing/**]
    areas_deny: [billing]
    spend_limit: 10
    on_violation: block

spend_limit is in US dollars per calendar month (UTC). on_violation is block (the default) or approve. See the bumpkit.yml Reference for every key.

• In the gate. The gate checks every agent on the change: the ID from BUMPKIT_AGENT_ID or BUMPKIT_AGENT (which bumpkit gate sends), commit trailers and bot authors, and the agents on the check. Each limit the change breaks becomes a reason named agents.<pattern>.paths, .areas_deny, .max_changed_lines, .max_open_prs or .spend_limit, which fails the gate (block) or asks for approval (approve).
• While the agent works. bumpkit pause --hook claude denies file writes outside the agent's paths, with the reason. See Pause risky commands.
• Open pull requests are counted from gate runs and closed by GitHub's pull request closed webhook.
• Every violation is recorded and audited, and shows in bumpkit agents violations and the agents_violations MCP tool.

bumpkit agents spend --agent claude-1 --usd 7.50 --note "model tokens for the refund task"
bumpkit agents usage
bumpkit agents violations --limit 50

Agent track records ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_track_records.

Each agent's outcomes over a window, overall and by work type (tests, migrations, auth, api, ui): releases, clean, reverted, fixed up within 7 days, blocked by the gate, and failed required checks, plus a score, the share that was clean. Checks of the same commits count as one release, so running the gate again doesn't change a record, and the change being gated isn't counted in its own record.

bumpkit agents records --days 90

--days defaults to 90. The same data is on the Reports tab of Insights and at GET /v1/agents/track-records?days=N.

Use a track record in the gate:

gate:
  require_approval:
    - agent_track_record_below: 0.8
      min_releases: 1
      work_types: [migrations]

min_releases (default 3) ignores agents with fewer releases, and work_types applies the rule only when the change touches those work types. The reason states the numbers, for example:

claude's migrations record is 0% clean over 1 release in 90 days (1 reverted, 0 fixed up, 0 blocked by the gate, 0 failed required checks); the policy asks a person to approve below 80%.

Fix tasks ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: close_the_loop. Needs the GitHub App.

When a change leaves callers on an old contract, such as a renamed function or a removed parameter, the release gate opens a fix task. Fix tasks cover Go functions and methods today; bumpkit gate builds the analysis from your checkout. It lists every caller by file:line, the symbol change and the expected edit. Mechanical changes get a pull request with the edit into the author's branch. Everything else is routed to the agent that wrote the change and to the pull request.

From the agent's side:

• The Stop hook blocks. While fix tasks are open on the branch, bumpkit guard --hook ... sends the agent back with each task, its places and pull requests, even when the gate passes.
• The fix_tasks MCP tool (repository, branch, all) lists the open tasks on the current branch.
• Agents can't mark a task done. Bumpkit marks it verified only when a later gate run proves every listed place clean, and reopens it if it comes back.

bumpkit loop --mine

gate.fix_tasks in bumpkit.yml decides what open tasks do to the gate: block (the default when Close the loop is on), approve or off. Bumpkit also opens rollback and back-port pull requests; see Rollback & Time Machine and Hotfixes & Break Glass.

Run several agents in one repository ​

A workflow for three agents working on the same repository at once:

1. Give each agent an identity. In each agent's environment, set BUMPKIT_AGENT_ID=claude-1 and BUMPKIT_SESSION, or pass --agent and --session on each command. Add the MCP server and install the agent hooks, so each session starts with recalled memories and risky commands pause.
2. Check before building. Each agent runs bumpkit tried "..." to see whether the idea was reverted or dropped before, and bumpkit intent --paths ... --symbols ..., and stops to re-plan when it exits 1.
3. Claim shared resources. bumpkit claim migration for a migration number, bumpkit claim path ... for new files, bumpkit renew during long work.
4. Test in isolation. export DATABASE_URL=$(bumpkit testdb lease) before running tests, bumpkit testdb release NAME after.
5. Push and report. CI runs bumpkit test upload, bumpkit coverage upload and bumpkit contracts sync. The agent runs bumpkit agent-report with its claims and fixes anything contradicted; on test failures it runs bumpkit test triage.
6. Merge in order. Run bumpkit merge-plan, and have agents poll merge_notifications to rebase when main moves. Agents fix any open fix tasks before they finish.
7. Review in one place. People work through gate approvals, paused commands, memories and lesson proposals in the approval inbox, and approve the lessons every agent should learn.
8. Clean up. bumpkit unclaim releases any leftover claims.