bugcap

Bug reports your AI agent can actually read.
Annotated screenshots and notes, stored on your machine, readable by coding agents over MCP, and synced to GitHub issues when you choose.

Website · Usage guide · Quick start · Agents (MCP) · Changelog

Why bugcap

Reviewing an app for bugs usually leaves you with two disconnected things: a screenshot and a mental note. By the time you file the issue, the context is gone. Once the screenshot is attached to a GitHub issue, it becomes unreadable to an API token. The CDN only resolves in a browser session, so an agent using gh can read the text but never the picture that explains the bug.

bugcap keeps the whole loop in one place:

Quick start

# install from PyPI
pipx install 'bugcap[mcp]'

bugcap setup --yes                      # detects or installs a capture tool
cd ~/code/myproject && bugcap init      # scope reports to this repo

bugcap capture --title "Login fails" --note "Error toast after submit" --tag auth
bugcap list
bugcap dashboard --open                 # browse and triage in the browser

The usage guide covers every command: images and labels, recording, live mode, @ references, GitHub pull and sync, and the MCP tools.

If a report ID is not found, the error suggests bugcap list --all to see report IDs across all repos.

Connect your agent (MCP)

Requires the mcp extra. Then give your agent access to the reports:

claude mcp add bugcap -- bugcap mcp-serve

Or in a project's .mcp.json:

{ "mcpServers": { "bugcap": { "command": "bugcap", "args": ["mcp-serve"] } } }

The server exposes six tools: list_reports, get_report (returns the screenshot), request_screenshot, pull_issues, attach_image, attach_file and update_notes. Logs go to logs/mcp-server.log in the data directory, never to stdout.

Ask your agent something like "list the open bugcap reports for this repo and fix the one with the error toast". It can read the picture because it's a local file, not a CDN link.

How it works

 capture ──► local store (SQLite + images/) ──► MCP / dashboard / CLI   (read by agents and you)
                       │
                       └──► sync ──► GitHub issue  +  committed image copy  (readable with gh api)

• capture / attach / record write to the store.
• mcp-serve, dashboard, list, show read from it.
• sync is the only thing that talks to a tracker, and only when you run it.

Status

Working. Roadmap items 1–5, 7 and 8 are implemented and tested, along with spec 002 (images, @ references, recording, live mode and the dashboard). S3/R2 object storage (item 6) and other trackers (item 9) are deferred. The Destination seam is in place, so they can be added without changing the CLI. See ROADMAP.md.

Installation

Requires Python 3.10 or newer. The core CLI uses only the standard library (plus tomli before Python 3.11). The MCP server is an optional extra.

pipx install 'bugcap[mcp]'   # recommended
uv tool install 'bugcap[mcp]'
pip install -e '.[dev,mcp]'                                             # development

Supported capture backends: flameshot (cross-platform, recommended), satty with grim (Linux/Wayland), and screencapture (macOS). Run bugcap setup to see what's detected. You can always import an existing image with bugcap capture --image PATH.

Documentation

Full guide: amenalahassa.github.io/bugcap/usage.html covers capture, images, recording, live mode, triage, @ references, the dashboard, GitHub pull and sync, MCP, and where data lives per OS.

Notes on the more involved behaviour:

• References. In a note, @i1 is image 1, @v2 a video, @g3 an animated GIF, @f4 a frame set, @d5 an attached file (attach --file, any type), and @login-error a labelled item. #3 points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs --force.
• Repo values (init, sync, config repo set) are checked for format and, with gh, for existence. Changing the repo identity offers to move existing reports.
• Media sync over [sync] max_upload_mb (default 25) is skipped with a warning.

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the workflow and project rules, and the Code of Conduct. Report security issues privately, see SECURITY.md.

Development

See DEVELOPMENT.md. Run the tests with:

uv run --extra dev --extra mcp pytest -q

Architecture

Module map (src/bugcap/):

The store is the one shared surface. Capture writes to it; the CLI, the MCP server, and the sync layer only read/update it — nothing talks to a tracker except sync.py (via ghcli.py), and nothing requires a tracker to exist for capture to be useful.

Extension seam (roadmap 6 & 9): sync.py depends only on the small Destination protocol (ensure_ready, repo_visibility, get_file, put_file, create_issue, comment, supports_attach) and on the report's synced_refs. A future object store or tracker implements that protocol — the CLI and store don't change. Refs are namespaced per destination:

• github.issue → owner/repo#N
• github.comment_hash → sha256 of the last synced content (so re-sync comments only on change)
• github.image.<basename> / github.media.<basename> → owner/repo:path@commit (so each file is committed at most once)
• github.frame.<idx>.<n> and github.frames.<idx> → keyframes of a recording (one commit per frame; GitHub's contents API commits one file at a time)

These refs also make pull and sync idempotent and resumable: each step is persisted as it succeeds, so a re-run skips what is already recorded.

Roadmap

See ROADMAP.md.

Design notes / deliberate non-goals

• No cloud storage by default, no vendor account. The store is plain files on your disk. Sync (GitHub, and optionally an S3/R2 object store) is opt-in and explicit, per report.
• Not a GitHub attachment replacement. The CDN-attached image stays for humans browsing the issue normally; the repo-committed copy exists purely so agents can read it. Both are written on sync, deliberately redundant.
• Not using Git LFS for synced copies. GitHub's Contents API returns LFS pointer files, not the real bytes, for LFS-tracked paths — which would silently defeat the entire point of committing the copy. Plain commits are used instead; if screenshot volume ever outgrows that, the right next step is an external object store with its own token-authable download URLs, not LFS.
• Annotation UI is not reinvented. bugcap is glue around an existing capture/annotate tool, not a new one.

License

MIT — see LICENSE.