A lightweight screenshot and annotation tool for developers and QA.
Draw a box on screen → optionally resize → annotate → save or copy instantly.
BugShot was created to simplify the workflow of capturing and communicating UI bugs during development and QA. Instead of juggling multiple tools for screenshots, resizing, and annotation, BugShot provides a streamlined workflow in a single lightweight application.
This project is fully open source and intended to evolve with community feedback.
BugShot is also an experiment in AI-assisted software development, where AI agents are used as development partners to help design, implement, and iterate on features.
The project focuses on:
- Fast screenshot capture
- Built-in annotation tools
- Optional standardized image sizing
- Simple configuration
- Cross-platform Python support
- About
- Demo
- Features
- Requirements
- Quick Start
- Workflow
- Settings
- Troubleshooting
- AI-Assisted Development
- Project Status
- Contributing
- License
- Region screenshot capture
- Optional preset image resizing
- Built-in annotation tools (arrows, blur, shapes)
- Copy to clipboard or save instantly
- Global hotkey support
- Multi-monitor support
- Lightweight Python application
- Python 3.9+
- macOS, Windows, or Linux
Check if Python is installed:
python3 --versionIf you see Python 3.9 or higher, you’re set. If the command is missing or the version is too old:
- macOS (Homebrew): Install Homebrew if you don’t have it, then run:
Use
brew install python@3.12
python3or the path brew shows (e.g./opt/homebrew/bin/python3) for the steps below. - Windows: Install from python.org or the Microsoft Store; ensure “Add Python to PATH” is checked.
- Linux: Use your package manager (e.g.
sudo apt install python3 python3-venvon Debian/Ubuntu).
# Clone the repo
git clone https://github.com/Mrmothy/bugShot
cd bugShot
# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run the app
python app.pyOn first run, a settings window opens. Save location, output size, and hotkey are preconfigured in config.json (in the repo); you can change them in the UI and click Save settings. The Save settings button highlights when you change anything so you know to save.
macOS: For the global hotkey to work, add Terminal (or your Python app) under System Settings → Privacy & Security → Accessibility and enable it. Without this, the hotkey won’t be detected; the app and Capture now still work.
Multi-monitor: When you have more than one monitor, a monitor picker appears first: choose which screen to capture (e.g. "Monitor 1 — 1920×1080" or "Monitor 2 — 2560×1440"). Then the overlay and region selection run on that screen only. With one monitor, the picker is skipped. Requires the mss dependency (included in requirements.txt).
- Capture – Draw a rectangle on screen (or use Capture now in the app, or press the hotkey). The selection is cropped.
- Resize (optional) – If “Scale to preset size” is on, the crop is scaled to your configured width×height; otherwise the drawn size is kept.
- Annotate – The editor opens. Add arrows, blur regions, rectangles, or ellipses. Use ⌘S / Ctrl+S to save to your save location, or ⌘C / Ctrl+C to copy to clipboard, then the window closes.
The full-screen image used for selection is not saved to disk (only a temp file that is removed after the crop).
| Method | Command | Use case |
|---|---|---|
| App (recommended) | python app.py |
Settings UI, Capture now button, and hotkey in one window. Leave it open; hotkey works from any app. |
| Hotkey only | python hotkey_launcher.py |
No UI. Listens for the hotkey; press it to capture. Quit with Ctrl+C. |
| One-off capture | python bugshot.py |
Single capture (overlay → editor). No hotkey listener. |
The repo includes a default config.json. If it’s missing (e.g. you deleted it), the app creates one on first run. Edit it by hand or use the app UI (recommended).
| Key | Description |
|---|---|
| save_location | Where “Save to Desktop” writes (e.g. "~/Desktop"). Filenames: bugshot_YYYYMMDD_HHMMSS.png. |
| use_preset_size | true = scale crop to output_width × output_height before the editor. false = keep the drawn size. Toggle in the app with “Scale to preset size” / “Keep drawn size”. |
| output_width, output_height | Target size in pixels when use_preset_size is true. |
| canvas_color | RGB list for the background when scaling (e.g. [255, 255, 255] for white). |
| hotkey | Global hotkey (e.g. "ctrl+shift+b" or "cmd+shift+b" on macOS). |
- Hotkey does nothing – On macOS, grant Accessibility to Terminal (or Python). Restart the app or
hotkey_launcher.pyafter enabling. - “Hotkey stopped” in the app – The hotkey helper process exited (e.g. no Accessibility). Grant permission and click Save settings to restart the listener.
- Import or module errors – Run
pip install -r requirements.txtfrom the project directory and use the same Python when runningpython app.pyorpython bugshot.py.
BugShot is developed with the help of AI coding assistants and agents.
AI tools are used to help with:
- feature prototyping
- architecture suggestions
- debugging assistance
- documentation generation
- rapid iteration of ideas
All design decisions, testing, and final code integration are reviewed and directed by the project maintainer.
The goal is to explore how human creativity and AI tooling can work together to accelerate open-source development.
BugShot is currently in active development.
Features and functionality may evolve as the project grows. Feedback, bug reports, and feature suggestions are welcome.
Contributions are welcome.
If you'd like to help improve BugShot:
- Fork the repository
- Create a feature branch
- Submit a pull request
Ideas, bug reports, and feature suggestions are also appreciated via GitHub Issues.
This project is licensed under the MIT License.
See the LICENSE file for details.
v0.1.0 – Initial public release