Usage

Everything bugcap does, from the first capture to handing a report to your agent.

Install

Requires Python 3.10 or newer. Install it as a tool so the bugcap command is on your PATH:

# with the MCP server
pipx install 'bugcap[mcp]'
# or with uv
uv tool install 'bugcap[mcp]'

Leave out [mcp] for the core CLI only. The extra is needed just for bugcap mcp-serve. To update, run pipx upgrade bugcap or uv tool upgrade bugcap.

Set up a capture tool

bugcap calls an existing screenshot and annotation tool instead of reinventing one:

bugcap setup              # reports the detected tool, or recommends one
bugcap setup --yes        # also installs it through your package manager

No capture tool? You can always import an existing image with bugcap capture --image PATH.

Scope captures to a project

Run this once inside a project repo. Reports captured there are tagged to the repo and listed only there.

bugcap init                                  # tag defaults to the folder name, GitHub slug to the origin remote
bugcap init --tag myproj --github owner/repo
bugcap init --images-repo owner/assets      # where synced image copies are committed

This writes .bugcap.toml in the repo. Change the values later with bugcap config repo show and bugcap config repo set. If the change alters the repo identity and reports already exist, bugcap asks whether to move them. In scripts, pass --migrate or --no-migrate.

Capture a bug

Capture launches your screenshot tool. Annotate, save, and bugcap asks for the description.

bugcap capture --title "Dashboard empty after module creation" \
               --note "Created Activity Tracking module, dashboard shows no widgets" \
               --tag ui

• --title is a short summary.
• --note is free text. Repeat --tag to add several tags.

Add more images

Import existing files, globs or URLs. Each is checked by its content (PNG, JPEG, GIF or WebP) and copied into the store.

bugcap capture --no-image --title "Typo on settings page" --note "says 'Setings'"   # text only, no screenshot
bugcap capture --image ./a.png --label login-error --title "Login fails" --note "See @i1 and @login-error"
bugcap attach <id> --image './shots/*.png' --image https://ci.example.com/run/42.png --label after-fix
bugcap attach <id> --image ./after.png --note "after the fix"   # the note is timestamped and tied to the image
bugcap attach <id> --file ./server.log --file './dumps/*.zip' --file-label log   # files of any type (pdf, log, zip...)

Attached files are copied into the store and referred to in notes as @d1, @d2, or by label. Identical files are stored once. In the dashboard they download instead of rendering, and sync never uploads them to GitHub (the issue keeps a "kept local" note in their place).

Manage a report's images:

bugcap images <id>                              # index, label, kind, size
bugcap images <id> relabel login-error sign-in  # refused while notes reference it, unless --force
bugcap images <id> remove 2 --force             # rewrites @ references in the notes

Record the screen

Needs ffmpeg, or wf-recorder on Wayland. The default output is an animated GIF.

bugcap record --id <id> --format animated --max-seconds 10   # Enter or Ctrl+C stops early

Formats: animated (GIF), video, or frames (keyframes). Use --max-seconds, --max-mb and --fps to limit size. Without --id, the recording creates a new report.

Live mode: report many bugs in a row

A small always-on-top window sits in the top-right corner while you test. Needs tkinter and a desktop session.

• Screenshot and Record (then Stop) each add a capture to a staged set. Stage as many images and videos as you like, in any mix.
• Each Screenshot or Record first asks what to capture: all screens, one monitor, a region you drag on the screen, or one window. Your last choice is preselected; Enter confirms, Esc cancels. Options your system can't do are greyed out with the reason:
  • Windows: everything (Flameshot opens on the monitor you picked; a window recording follows that window).
  • Linux X11: everything; picking a window needs wmctrl or xwininfo.
  • Linux Wayland: all screens, a monitor, and a region (needs slurp); no single window.
  • macOS: screenshots of anything; recordings of a screen or a region, not a single window.
  A window recording stops by itself, keeping what it has, when the window is closed, minimised or (X11) moved.
• Upload image... and Attach file... open a file picker (several files at once) and stage what you pick, exactly like attach --image and attach --file. Images are checked; files can be of any type and are referred to as @d1, @d2, and so on.
• Every staged item is listed in the window and in the bug form. Click one to open it in your usual app (videos too); ✕ removes it after a confirmation. Tags don't shift when an item is removed: after removing @i2 the others stay @i1 and @v3, and they are renumbered in the saved report.
• New bug from N items turns the staged set into one report; refer to the items in the notes with @i1, @v2, and so on. The form's Repo field defaults to the launch repo but can be switched to any repo you've already run bugcap init in.
• Add to existing bug attaches the staged set, plus an optional note, to a bug you already filed.
• New bug (note only) files a bug with no media: a title, a note and optional tags.
• The bug form remembers what you typed until you Save or Discard: Back (or closing the form) keeps the title, notes, tags, status and repo for the next time you open it. Add to existing bug also remembers the chosen bug and note after Cancel, while live mode runs.
• The bug in progress (fields and staged items) is autosaved every few seconds. After a crash, or after quitting, the next bugcap live offers to restore it.

Keyboard shortcuts work while a bugcap window has focus (never system-wide); every button shows its key, and F1 lists them all. On macOS, Ctrl is ⌘ and Alt is Option.

bugcap live
bugcap live --repo-dir ~/code/myproj        # scope reports to that repo's .bugcap.toml

List and triage

bugcap list                         # reports in the current repo
bugcap list --all                   # reports from every repo
bugcap show <id>                    # one report, with its images and resolved notes

bugcap edit <id> --status resolved --note "fixed in #42"
bugcap tag <id> add ui
bugcap tag <id> remove ui

bugcap delete <id>                  # asks first; --yes skips the prompt (images are removed too)

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

Accepted statuses:

openin-progressresolvedclosedwontfix

References in notes

Point at a report's media, or at another report, from its notes:

Media references are checked when a note is saved: an unknown one is refused and the valid ones are listed. The number is the one show and images print. Older notes that use @1 still work. Code spans, fenced blocks and email addresses are never treated as references. show resolves them, and sync turns them into links or images in the GitHub issue.

Dashboard

A local web page to browse, filter and triage reports:

bugcap dashboard --open                 # http://127.0.0.1:8765 by default
bugcap dashboard --port 0               # pick a free port

GitHub

bugcap uses your gh login. Run gh auth login once if you haven't.

Import issues as reports

bugcap github pull --repo owner/repo --label bug --limit 20 --ask

Pulling is idempotent: running it again skips issues already imported. --ask prompts you to add a screenshot to each issue.

Push a report to an issue

bugcap sync <id> --to github --images-repo owner/assets --yes

This creates or updates the issue and commits a plain copy of each image to the images repo, so agents can read it. Media over the size limit is skipped with a warning. The limit is [sync] max_upload_mb, 25 MB by default.

Connect your agent (MCP)

The MCP server lets an agent list reports, read them (images included), request a screenshot, pull issues, attach images or files and update notes.

claude mcp add bugcap -- bugcap mcp-serve

Or add it to a project's .mcp.json:

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

Tools

Logs

The server logs to logs/mcp-server.log in the data directory (rotated, 1 MB × 3) and to stderr. Stdout is reserved for the protocol. Set the level with --log-level, BUGCAP_LOG_LEVEL or [log] level in config.toml. Note text is only logged at debug.

Where data lives

Reports and images are plain files, independent of any tracker.

Set BUGCAP_HOME to move both. Reinstalling bugcap never touches your data. Schema changes are migrated in place.

Windows notes

bugcap is fully supported on Windows; this section covers the install path and a couple of platform quirks.

pipx install 'bugcap[mcp]'
bugcap setup --yes        # detects flameshot, or installs it with winget
cd C:\code\myproj && bugcap init

bugcap setup installs flameshot through winget (or scoop/choco if you use one of those instead). Recording needs ffmpeg on PATH; without it, record and live mode's Record button report that no recorder was found, but screenshots and note-only bugs still work.

Data lives in %LOCALAPPDATA%\bugcap, config in %APPDATA%\bugcap (see Where data lives).

bugcap live needs tkinter, which ships with the standard python.org installer; it's fine out of the box with pipx/uv tool install.