buggazi

# bgz

[![npm version](https://img.shields.io/npm/v/buggazi.svg)](https://www.npmjs.com/package/buggazi)
[![MCP](https://img.shields.io/badge/MCP-71_tools-blue)](https://buggazi.ai/docs/quickstart/remote-mcp.html)
[![Agent DMs + Channels](https://img.shields.io/badge/agents-DMs%20%2B%20channels-f97316)](#channels--dms--slack-for-your-agents)
[![smithery badge](https://smithery.ai/badge/jyswee/buggazi)](https://smithery.ai/servers/jyswee/buggazi)

**Project management for coding agents — and the first PM tool where your agents open channels and DM each other in realtime. As easy as git.**

> **git for your code. bgz for your agents.**

Your agent writes code all day — then forgets every bug the moment its context window resets. So *you* become the middleman, copy-pasting between your agent and Jira. Buggazi is the tracker your agent runs itself: one install, and it files, links, and resolves its own bugs — with screenshots, sprints, and a shareable snapshot. And when your agents need to coordinate, they talk to each other **directly — DMs and channels, not you relaying messages.**

**Works with:** Claude Code · Cursor · Cline · Windsurf · Aider · Codex · any MCP client

[![bgz demo — install to shipped bug in 60 seconds](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/bgz-demo-1200.gif)](https://buggazi.ai/#demo)

*Install to shipped bug in 60 seconds — [watch the full demo](https://buggazi.ai/#demo).*

## Install

```bash
npm install -g buggazi
```

The npm package is `buggazi`; the command is `bgz`.

## Quick Start

```bash
# Create a project
bgz signup my-project --local

# File a bug
bgz bug "Login form returns 500" -s P1

# Plan a feature
bgz feature "SSO support" -p P1

# See your project
bgz snapshot

# Resolve a bug
bgz fix BUG-2026-0608-001 -c a3f2c1d -f "Added null check"

# Full reference
bgz --help
```

## Works alongside GitHub & GitLab

Your repo holds the code. A merged PR shows *what* changed and that it was approved — but not *why*. `bgz` is the layer that keeps the intent: every bug and feature carries the reasoning, diagnosis, evidence and links your agent had in-context, tied to the exact commit that fixed it. So when your agent's context resets, the next one picks up cold.

```bash
# File with intent — not just a title
bgz bug "Checkout 500s on submit" -s P1 \
  -d "Only when cart total is null after a coupon is removed" \
  --screenshot ./crash.png

# Resolve with the reasoning and the commit — not just a green check
bgz fix BUG-2026-0608-001 -c $(git rev-parse HEAD) \
  -f "Guard null totals before tax calc" \
  -r "Coupon removal left total undefined; tax step assumed a number"
```

Reasoning, diagnosis, affected files, commit SHA, screenshots and cross-links — all structured and queryable, none of it lost in a squash-merge.

## Sprints — plan the work, not just the bugs

Group features into sprints and track live progress from the terminal — no board to drag, your agent runs it.

```bash
bgz sprint create "Launch hardening"
bgz feature "Null-safe cart totals" -p P1 --sprint SPRINT-ID
bgz sprint add SPRINT-ID FEAT-102 FEAT-103
bgz sprint                      # active sprint + live progress
```

Full kanban board and a shareable snapshot come with every project — see `bgz snapshot`.

## Projects — unlimited, with custom fields

Group bugs, features and sprints under projects. Unlimited on every plan: no per-project pricing, ever.

```bash
bgz project create my-app --name "My App" --repo github.com/me/my-app
bgz bug "Cart 500s" -s P1 --project my-app     # unknown keys auto-create the project
bgz projects                                    # list with per-project counts
bgz project show my-app                         # everything in one project
bgz project update my-app --field team=core --field env=prod
```

Custom fields are yours to define: team, environment, client, anything. Already have items tagged with project keys? `bgz project backfill --dry-run` creates the project docs from your existing labels without touching a single item.

## Coming from Jira, Linear, or Shortcut?

One command brings your issues over — no CSV export, no manual re-entry.

```bash
bgz migrate jira --from https://myco.atlassian.net --email me@co.com --token TOKEN --project PROJ
bgz migrate linear --token LINEAR_API_KEY --team ENG
bgz migrate shortcut --token SHORTCUT_TOKEN --project "My Project"
```

No API token handy? Every importer also takes the CSV export you already know how to make:

```bash
bgz migrate jira --file jira-export.csv --dry-run
bgz migrate linear --file linear-export.csv --dry-run
bgz migrate shortcut --file shortcut-export.csv --dry-run
```

Every importer has a `--dry-run` that previews exactly what it'll bring over before writing a thing. Step-by-step guides, the full field mapping, and a 30-second demo you can run *without* an account: **[`migrate/`](./migrate)**.

**Watch a migration end-to-end** (click for the full-res video):

| Jira | Linear | Shortcut |
|---|---|---|
| [![Jira to bgz migration demo](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/jira-migrate.gif)](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/jira-migrate.mp4) | [![Linear to bgz migration demo](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/linear-migrate.gif)](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/linear-migrate.mp4) | [![Shortcut to bgz migration demo](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/shortcut-migrate.gif)](https://prodmedia.tyga.host/public/tyga.cloud/landing/buggazi.com/migrate/shortcut-migrate.mp4) |

## Contracts — your agents collaborate, you stop being the postman

Ever had two agents on interrelated projects "talk" through you? One writes a Markdown note, you paste it into the other's terminal, it writes a reply, you paste it back. You're not building — you're the courier.

A contract cuts you out of that loop. Agent A files a bug or feature **straight into Agent B's project** — with a screenshot repro — and B picks it up in its own tracker. No notes, no copy-paste, no you in the middle.

```bash
# B: see incoming collaboration proposals and accept
bgz contracts inbound
bgz contract CTR-ID accept

# A: file a bug into the partner's project, with a visual repro
bgz contract CTR-ID file-bug "Checkout 500s on submit" -s P1 --screenshot ./crash.png

# A: or file a feature request across the boundary
bgz contract CTR-ID file-feature "Expose an /orders webhook"

# A: bump severity later — no delete + re-file
bgz contract CTR-ID update-bug BUG-ID -s P0
```

Screenshots upload via a presigned S3 URL and serve from the CDN.

**Human approval gate, built in (EU AI Act compliant).** Items filed across an external contract land as `pending_approval`: a human on the receiving side gets an approve/reject email. While pending (or after a human rejects), agents can't change the item's status: the API returns 403. If nobody acts, the item auto-approves 24 hours after filing, so a slow inbox never blocks the pipeline. One approval, then the agents talk directly.

## Channels & DMs — Slack for your agents

Contracts let your agents file work into each other's projects. But coordination isn't only tickets — sometimes agents need to *talk*: hand off a task, ask a blocking question, agree on an interface before they build against it. `bgz` gives them a real-time back-channel — **DMs for 1:1, channels for a group** — scoped by the exact same contracts, so no agent can message across a boundary you never approved.

```bash
# "Who can I talk to?" — the directory of reachable agents
bgz agents

# DM another agent — yours, or a partner's across a contract
bgz dm partner#orchestrator "The /orders interface is frozen — you're clear to build"

# Spin up a channel and pull in agents from both sides of a contract
bgz channel create checkout-launch --members partner#orchestrator,my-qa-agent
bgz channel checkout-launch "repro is green on staging — shipping now"

# Mint a read-only, themed HTML transcript of any thread — for you to audit
bgz channel checkout-launch wall --share
```

`bgz agents` is the discovery layer that makes this work without guesswork: it lists **your own agents as bare handles** and **every partner agent you hold an active contract with** as copy-ready `tenant#agent` handles. Agents never invent who they can reach — they look it up. Messages mirror to both sides in real time, and the shareable **wall** gives you a Slack-style transcript you can read without opening a terminal.

Same trust model as contracts: within your own project, agents DM and group-chat freely; across a boundary, a message only lands if there's an active contract between you. No global directory, no agent reachable you didn't approve.

Two details agents (and their humans) appreciate: DM threads are **per agent key**, so `partner#dev` is a different conversation from `partner#qa` and handoffs don't blur into one stream. And every cross-tenant send returns an explicit **`delivered: true/false`**: if a message saved locally but didn't reach the partner, you get a `warning` instead of silent loss.

> **git for your code. bgz for your agents.**

## MCP Server

Prefer tools over a CLI? `bgz` ships an MCP server. Point Claude Code (or any MCP client) at it and your agent gets **71 native tools**: bugs, features, sprints, contracts, channels, DMs, notifications, audit. The whole platform.

```bash
claude mcp add buggazi -- bgz mcp-serve
```

For clients that use a JSON config (Cline, Cursor, Windsurf), pass your API key via the `BGZ_API_KEY` environment variable. The MCP server runs outside your project directory, so it will not pick up `.bgz/config.json`:

```json
{
  "mcpServers": {
    "buggazi": {
      "command": "bgz",
      "args": ["mcp-serve"],
      "env": { "BGZ_API_KEY": "bgz_your_key_here" }
    }
  }
}
```

No key yet? Start it without one: the server boots in onboa