# Quick Start: AI Agent Teams

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `agent_guard`.

This guide puts Bumpkit inside your coding agents. When you are done, each agent:

- starts every session with what your team learned about the code,
- has its work checked before it finishes, and is sent back once to fix proven problems,
- waits for a person before it runs a risky command,
- and, when several agents share a repository, claims what it uses and stays out of the others' way.

Each step has its own flag. Run `bumpkit features` to see which are on for your workspace.

## 1. Install the CLI and sign in

1. Install the CLI, which includes the MCP server, and put it on your `PATH`. See [Install the CLI](/docs/#install-the-cli).
2. Sign in:

   ```bash
   bumpkit login
   ```

3. The MCP server can use the credentials saved by `bumpkit login`. For CI or an agent running under a separate account, create a key and pass it through that environment:

   ```bash
   bumpkit keys create agents
   export BUMPKIT_API_KEY=bk_live_...
   ```

## 2. Install the hooks for your agent

Run the installer from the root of the repository. Each installer merges into your existing config, so running it twice is safe.

| Agent | Install | Flag |
|---|---|---|
| Claude Code | `bumpkit hooks install --claude` (also the pause hook, see step 4) | `agent_guard`, and `agent_pause` for the pause hook |
| Cursor | `bumpkit hooks install --cursor` (also the pause hook, see step 4) | `agent_guard`, and `agent_pause` for the pause hook |
| OpenAI Codex | `bumpkit hooks install --codex` (also the pause hook, see step 4) | `agent_guard`, `agent_hooks_extended`, and `agent_pause` for the pause hook |
| Gemini CLI | `bumpkit hooks install --gemini` | `agent_guard`, `agent_hooks_extended` |
| Windsurf | `bumpkit hooks install --windsurf` | `agent_guard`, `agent_hooks_extended` |
| Cline | `bumpkit hooks install --cline` | `agent_guard`, `agent_hooks_extended` |
| Any agent or person | `bumpkit hooks install --git` (a pre-push hook) | `agent_guard` |

Then finish the setup in the agent:

- **Codex:** trust the project, and review the hooks with `/hooks`.
- **Gemini CLI:** trust the project hooks the first time they run.
- **Cline:** turn on Enable Hooks in Cline's Feature Settings.

To try it, ask the agent to make a change, then let it finish. If the change has a proven problem, the agent is told what and where, and goes back to fix it. For the exact files each installer writes, see [Agent Hooks](/docs/agent-hooks).

## 3. Connect the MCP server

The MCP server lets the agent call Bumpkit directly: check a release, ask the gate, and read history and memory.

```bash
claude mcp add --transport http bumpkit https://bumpkit.dev/mcp
```

Then run `/mcp` in Claude Code, choose the Bumpkit server and sign in. In the Claude desktop app, add `https://bumpkit.dev/mcp` as a custom connector instead. To run the server next to your checkout, which tools like `release_gate` need, use `claude mcp add bumpkit -- bumpkit mcp`.

`bumpkit mcp` uses your saved `bumpkit login` credentials, or `BUMPKIT_API_KEY` from the client environment. The Codex, Gemini CLI, Windsurf and Cline hook installers configure `bumpkit mcp` for those agents. See [Connect a client](/docs/mcp#connect-a-client).

The server lists only the tools whose features are on for your workspace. See [MCP Server](/docs/mcp) for every tool.

## 4. Pause risky commands

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `agent_pause`.

The pause hook checks each shell command before the agent runs it. It allows it, asks a person, or denies it. For example, `rm -r` on the repository root and a force push to `main` are denied. `git reset --hard`, `terraform apply` and a `DROP TABLE` sent to a database client ask first.

`bumpkit hooks install --claude`, `bumpkit hooks install --cursor` and `bumpkit hooks install --codex` add the pause hook.

1. Try a command by hand:

   ```bash
   bumpkit pause git push --force origin main
   ```

   It prints `allow`, or `ask:` or `deny:` with the reason. Without a key, or with the flag off, it still checks with the built-in rules.

2. Tune the rules in `bumpkit.yml` on your default branch:

   ```yaml
   agent:
     deny: [infra_apply]
     ask: ["make deploy*"]
     remote: true
     timeout: 60s
   ```

   With `remote: true`, a teammate can approve or deny an `ask` in Bumpkit while the agent waits.

The hook reads the committed policy from the default branch (`origin/HEAD`), never from the working copy, so an agent can't loosen it by editing the file. For every rule, see [Pause risky commands](/docs/agent-controls#pause-risky-commands).

## 5. Share what your team learned

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it. Flag: `codebase_memory`.

Memory stores decisions, pitfalls and incidents by path. The hooks load it at the start of each session.

1. Save a memory:

   ```bash
   bumpkit memory add "Webhook handlers must stay idempotent; GitHub retries on timeout." \
     --kind decision --path services/webhooks/github.go
   ```

2. See what an agent will get for an area:

   ```bash
   bumpkit recall --path services/api
   ```

3. Remove a memory once it is no longer true:

   ```bash
   bumpkit memory forget MEMORY_ID
   ```

Agents save and read memories with the `remember`, `recall` and `forget` MCP tools. To have a person approve memories before agents see them, turn on [memory approval](/docs/agent-controls#memory-approval).

## 6. Run several agents in one repository

> **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, these features stop them colliding. Each has its own flag.

### Give each agent an identity

Set these in each agent's environment, with a different value per agent:

```bash
export BUMPKIT_AGENT_ID=claude-1
export BUMPKIT_SESSION=claude-1-run-1
```

Set both. `BUMPKIT_AGENT_ID` is the agent's name everywhere; `BUMPKIT_AGENT` is accepted as an alias. See [Identify each agent](/docs/agent-swarms#identify-each-agent).

### Claim what you use

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

Before an agent uses a migration number or creates a shared file, it claims it:

```bash
bumpkit claim migration
bumpkit claim path services/billing/invoice.go --note "new invoice totals"
bumpkit claims --mine
bumpkit unclaim CLAIM_ID
```

`bumpkit claim migration` holds the next free number for you. If another agent already holds a resource, the claim is refused and names the holder. See [Claims](/docs/agent-swarms#claims).

### Declare intent

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

Before starting, the agent says what it will change:

```bash
bumpkit intent --paths services/billing --symbols billing.ChargeCustomer
```

Bumpkit compares it with open pull requests, claims and other agents' intents. The command exits `1` when it predicts a conflict, so the agent can re-plan before it writes code. See [Conflict prediction](/docs/agent-swarms#conflict-prediction).

### Merge in the right order

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

```bash
bumpkit merge-plan
```

This orders the open pull requests so those with the fewest overlaps merge first, with a reason for each position. Bumpkit re-checks waiting pull requests whenever main moves. See [Merge planning](/docs/agent-swarms#merge-planning).

## Next steps

- See how each coding agent's releases fare: [Agent scorecards](/docs/agent-controls#agent-scorecards).
- Record which agent, model and session made each change: [AI change provenance](/docs/agent-controls#ai-change-provenance).
- Check the claims in an agent's summary against CI: [Verified agent reports](/docs/agent-swarms#verified-agent-reports).
- Share rules every agent follows, set agent budgets and scopes, and review everything that waits for a person in one place: [Swarm lessons](/docs/agent-swarms#swarm-lessons), [Agent budgets and scopes](/docs/agent-swarms#agent-budgets-and-scopes) and the [Approval inbox](/docs/agent-swarms#approval-inbox).
- Follow the full multi-agent workflow: [Run several agents in one repository](/docs/agent-swarms#run-several-agents-in-one-repository).
- See how all the pieces fit: [How Bumpkit Works](/docs/how-it-works).