README
¶
disbug
Disbug CLI and MCP server for AI coding agents.
A single Go binary that reads bug-report sessions from your team's Disbug instance, plus downloaded local report JSON files. Use the CLI from shell-capable agents, or connect its MCP server to an MCP-native agent.
Install
macOS / Linux (Homebrew)
brew install disbug-io/tap/disbug
Windows (Scoop)
scoop bucket add disbug https://github.com/disbug-io/scoop-bucket
scoop install disbug
Direct download
Grab a binary for your OS/arch from Releases and put it on your PATH.
Quickstart
For the short Developer setup, identify the invoking coding agent and run, for
example, disbug onboard --agent codex. The CLI opens account authorization,
uses the default project, creates the default-named Disbug agent, configures the
selected coding agent, and prints the Chrome Web Store URL. It does not open the
store automatically.
Use --api-url http://localhost:8000 for a local backend, --no-browser to print
browser URLs, or --manual to paste the redirect URL privately into the terminal
when a loopback callback cannot reach the CLI. The browser callback is correlated
with a random state and the CLI waits for up to five minutes. Keep the process
running while completing browser authorization.
Agents can read progress without prompts or wait for a verified milestone:
disbug onboard --status
disbug onboard --wait-for extension_installed
disbug onboard --wait-for first_report_captured --project-id 42
These return JSON using the saved profile (--profile work is supported). Waits
time out after five minutes and can be rerun. Pass the selected project ID when it
is not the default project. agent_connected confirms account authorization;
disbug doctor checks local agent configuration. widget_configured confirms
ingestion is enabled, not that the widget has been installed on a site.
For individual setup steps:
disbug login # authenticate in the browser
disbug configure # connect detected agents and install the workflow skill
disbug doctor # verify login, backend, MCP, and skill setup
disbug sessions --status open
disbug session https://app.disbug.io/acme/projects/2/sessions/5/
disbug pin 'https://app.disbug.io/acme/projects/2/sessions/5/?pin=1' --fields console,network
disbug attachment download 'https://app.disbug.io/acme/projects/2/sessions/5/?pin=1' 42 --output ./notes.md
disbug pin status 'https://app.disbug.io/acme/projects/2/sessions/5/?pin=1' resolved --note 'Fixed and verified checkout validation.'
disbug session status https://app.disbug.io/acme/projects/2/sessions/5/ resolved --note 'All reported pins verified.'
disbug inspect ./disbug-report-example.json
disbug configure currently supports Codex, Claude Code, and Cursor. It shows the files it will change and asks for confirmation. For non-interactive setup, select an agent explicitly, for example disbug configure --agent codex --yes.
The installed using-disbug skill teaches investigation workflow and capability selection. Command syntax remains in disbug --help and disbug <command> --help; MCP tool syntax remains in each tool's schema.
Inspect a downloaded local report
The Chrome extension can download a self-contained local report JSON when a user does not want to save a session to cloud. Inspect it without dumping screenshots or replay bytes into the terminal:
disbug inspect ./disbug-report-example.json
disbug inspect ./disbug-report-example.json --pin 2 --fields console,network
disbug inspect ./disbug-report-example.json --pin 2 --fields screenshot,replay
screenshot and replay fields are decoded to local cache file paths only when requested. The default summary prints pin feedback, URLs, artifact availability, and log counts.
Use as an MCP server
Disbug exposes read MCP tools for cloud reports: whoami, list_sessions, get_session, get_pin, get_pins, download_attachment, search_sessions, and search_pins. Session and pin results include attachment filenames and IDs; download_attachment returns the selected file's content directly to the agent. Explicit status writes use set_session_status and set_pin_status; both accept an optional agent note.
For downloaded local report JSON files, use inspect_local_report with a filesystem path. It returns the same lightweight summary as disbug inspect, and can inspect a single pin with selected fields without needing native host setup or a cloud upload.
Run disbug configure for Codex, Claude Code, or Cursor. Manual setup recipes and unsupported-client fallbacks are also available:
Multi-profile
disbug --profile work login
disbug --profile work configure
disbug --profile personal login
disbug --profile personal configure
Each configured profile points the selected agent at disbug --profile <name> mcp.
Exit codes
| Code | Meaning |
|---|---|
| 0 | OK |
| 2 | Usage error (bad ref, bad flag) |
| 4 | Auth error (no token, 401) |
| 5 | Network unreachable |
| 6 | Not found (404) |
| 7 | Forbidden (403, including free-tier locked) |
| 8 | Rate limited (429) |
| 9 | Server error (5xx) |
Development
make install-hooks
make ci
The pre-commit hook runs make fmt-check and make lint.
For release and package publishing, see docs/release.md.
License
MIT - see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
disbug
command
|
|
|
internal
|
|
|
client/openapi
Package openapi provides primitives to interact with the openapi HTTP API.
|
Package openapi provides primitives to interact with the openapi HTTP API. |
|
mcp
Package mcp registers the Disbug MCP tools and runs the stdio JSON-RPC server.
|
Package mcp registers the Disbug MCP tools and runs the stdio JSON-RPC server. |
|
selfupdate
Package selfupdate performs a best-effort check for a newer released disbug CLI and formats an upgrade nudge.
|
Package selfupdate performs a best-effort check for a newer released disbug CLI and formats an upgrade nudge. |