Skip to main content
Docs

Coding agents

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.

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

1. Give the agent its own profile

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

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

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

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

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:

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.

Last updated on