---
title: "Coding agents"
description: "Give a coding agent safe access to Bucky through the CLI — a dedicated profile, readiness checks, the agent-context contract, and installing Bucky in MCP clients."
last_updated: "2026-10-04"
---

Agents with a shell (Claude Code, Codex, Cursor, and others) can use the CLI directly.
It is the broadest agent surface Bucky has: everything the web app can do with your
projects, with previews and receipts on every change. For chat assistants without a
shell, use [MCP](/docs/mcp) instead.

## 1. Give the agent its own profile

Sign a separate profile in once, yourself, so your password never goes near the agent:

```bash
bucky --profile agent auth login
```

Sign it in as a dedicated Bucky user who is a member of only the projects the agent
should touch. The agent then runs every command with `--profile agent` (or
`BUCKY_PROFILE=agent`).

## 2. Check readiness

```bash
bucky --profile agent --json agent check
bucky --profile agent --json agent check \
  --require projects:read,projects:create,chat:write,knowledge:read
```

`agent check` runs a few quick, read-only probes and reports for each capability
whether the command exists, the profile is signed in, Bucky is reachable, and the user is
authorized. It never creates anything or sends a message. A missing capability fails the
check (exit `1`, `AGENT_CHECK_FAILED`).

## 3. Read the contract

```bash
bucky --json agent-context
```

`agent-context` describes every command an agent may use: arguments, types, enums,
bounds, defaults, pagination, and for each write whether it supports a dry run, needs
confirmation, is idempotent, can be undone, and how to recover from an unknown outcome.
It runs offline. Prefer it over parsing `--help`. (`capabilities` was removed in
0.14.0; use `agent-context --index`.)

## 4. Follow the write rules

- Always `--json`.
- Run a write with `--dry-run` first, then repeat it with `--yes`.
- Never loop retries around a write. Use `--retry-operation <receipt-id>` where it is
  supported, and otherwise follow the command's recovery hint. See
  [Safe writes](/docs/cli/safe-writes).
- Use `--full` only when the compact payload is missing something you need.

For the `agent` profile, `screen create` previews by default and saves only with
`--yes`.

## Install Bucky in an MCP client

The CLI can add the Bucky MCP server to a local AI client for you:

```bash
bucky mcp install              # finds installed clients and asks which one
bucky mcp install claude-code
bucky mcp install cursor --dry-run
```

Supported clients: `claude-code`, `claude-desktop`, `codex`, `cursor`, `vscode`,
`windsurf`, `zed`, and `cline`. The CLI merges a Bucky entry into the client's config
file without touching your other servers, then starts the client's sign-in where it can.
`--skip-oauth` writes the config only.

To see and revoke the MCP connections on your account:

```bash
bucky mcp connections list
bucky mcp connections revoke <grant-id>
```

You can do the same in the web app under **Settings → Connections**.

## Discovery for humans

- `bucky` with no arguments opens a searchable command palette in a terminal. It only
  prints the command; it never runs a write.
- `bucky help` suggests next steps from your profile, recent projects, and recent
  conversations, using quick read-only checks.
- `bucky chat resume` picks a recent conversation and prints the command to continue it.

The first time you run `bucky` interactively, it walks you through choosing a profile
and signing in.


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.