Bug Pocket Documentation

Installation

Bug Pocket is distributed as a standard Windows installer (.exe). Download and run the installer. Once installed, Bug Pocket will open automatically.

System Tray & Background Running

Bug Pocket is designed to run in the background while you test other applications.

• When you close the Main Dashboard, Bug Pocket minimizes to the system tray (the icon area near your Windows clock).
• Click the tray icon to quickly open the Quick Capture panel or right-click it for more options (Dashboard, Exit).

Defining Context Lists

Before capturing bugs, set up the context you'll use to tag them. Navigate to Settings > Workspace & Hotkeys and look for the Workspace Field Lists section.

1. Applications: Add the main products you are testing. Application descriptions are mandatory to ensure good workspace hygiene.
2. Modules: Specific areas within an application (e.g., "Checkout", "User Profile"). When you create a new Application, Bug Pocket automatically creates a default 'General' module for you.
3. Environments: E.g., Production, Staging, QA, UAT, Local.
4. User Roles: E.g., Admin, Standard User, Guest.

Jira Workspace URL

If you use Jira, setting your base URL allows Bug Pocket to generate direct links to the "Create Issue" screen.

• Go to Settings > Output & Templates > Jira Workspace URL.
• Enter your instance URL (e.g., https://your-company.atlassian.net).

Opening the Panel

Press Ctrl + Alt + P from anywhere in Windows to bring up the Quick Capture window. It stays compact and on top of other windows.

Filling the Form

The panel asks for the bare minimum: Application, Module, Environment, User Role, and a Bug Note.

• Use Tab to move between fields.
• You can type to filter dropdown options. If an Application or Module doesn't exist, you can create it inline.
• Press Ctrl + Enter to save the entry immediately.
• Press Esc to cancel and dismiss the panel.

Quick Capture Presets

If you repeatedly test the same area, set up a preset to fill context fields instantly.

1. Go to Settings > Capture Presets.
2. Configure up to 3 preset slots with a specific Application, Module, Environment, and Role.
3. When the Quick Capture panel is open, press Alt + 1, Alt + 2, or Alt + 3 to instantly apply that preset.

The Snip Overlay

Press Ctrl + Alt + S globally (or click the Screenshot button in the app) to start snipping.

• The screen will freeze. Click and drag to select a specific region.
• To capture the entire screen instantly without dragging, press Alt + C while the overlay is active.
• Press Esc to cancel the screenshot.

Review Mode vs. Instant Attach

By default, taking a screenshot from the Quick Capture panel opens the image in Review Mode where you can annotate it before saving.

• Click Attach Screenshot to save it to your draft.
• Click Discard if you made a mistake.

Annotation Tools

When reviewing a screenshot in Quick Capture, or when opening an attachment from the Dashboard/Details views, you have access to the canvas annotator:

• Arrow: Click and drag to point out elements.
• Freehand: Draw circles or lines manually.
• Text: Click to place a cursor, type your text, and press Enter to commit it.
• Mask: Click and drag over sensitive data (like real user PII) to redact it with a blur effect.

Non-Destructive Editing

Annotations are non-destructive. When you edit an already-saved attachment, Bug Pocket creates a new image file linked to the original. The raw original screenshot is never overwritten.

• Use Ctrl + Z or the Undo button to revert your last drawing action before saving.

The Entry List

The Dashboard displays 5 high-signal columns: Entry (Title/Note), Context (App/Module/Env), State (Status/Severity/Sync), Created Date, and Attachments.

Filters & Search

Click the Filters toggle to open the collapsible filter panel.

• Filter by Entry Type (e.g., show only Scenarios).
• Filter by Context (App, Module, Env).
• Filter by State (Draft, Reported, Discarded).

The text search box in the header searches across titles and bug notes.

Attachment Spotlight

Click the camera icon (📷) in the attachments column to open the Spotlight preview. You can view, annotate, and download the image without opening the full Bug Details page.

Full Fields

Click any row in the Dashboard to open the Bug Details drawer. Here you can add data you skipped during Quick Capture:

• Taxonomy: Device, Browser, Entry Type.
• Structured Text: Steps to Reproduce, Expected Result, Actual Result, Other Details.
• Tracking: Set the Status (Draft → Reported), Severity, Issue Platform, and paste the external Issue ID/URL.

Autosave Behavior

Bug Pocket relies on autosave. After ~1.5 seconds of typing inactivity, the record saves to SQLite automatically. You will see a subtle "Saved" indicator near the field.

• Navigating back to the Dashboard immediately flushes any pending saves.
• A manual Save Details button is available at the bottom for peace of mind.

Copy Actions

In the Bug Details right sidebar, you will find Report Actions. These actions format your fields using the templates defined in Settings.

• Copy Quick Report: A short summary.
• Copy Full Bug Report: Standard detailed markdown.
• Copy Linear / Jira Format: Tracker-specific markdown variations.

External Launcher

If you click Open Linear or Open Jira, Bug Pocket will build a special URL that opens your default web browser directly to the "New Issue" screen, with the title and description pre-filled from your Bug Pocket data.

Bring Your Own Key (BYOK)

Bug Pocket does not include a shared cloud AI key. You must provide your own. Your key is encrypted using Windows safeStorage and never saved in plain text.

1. Go to Settings > AI Processing.
2. Select a Provider Preset (OpenAI, Grok, OpenRouter, Gemini, or Custom).
3. Ensure the Base URL and Model ID are correct (e.g., google/gemma-4-31b-it:free on OpenRouter).
4. Paste your API key and click Save.

Running Triage

1. Open a bug in the Bug Details view.
2. Click the AI Triage button in the right sidebar.
3. Bug Pocket sends your text and a resized screenshot to your provider.
4. When the AI replies, Bug Pocket automatically populates the Title, Steps to Reproduce, Expected Result, and Actual Result fields.

Connecting to the Cloud

Cloud Sync is not ready yet! Once it is ready, you will simply log in, and Bug Pocket will securely bridge your local SQLite data to your private cloud workspace. Your data remains encrypted and entirely under your control.

1. Go to Settings > Cloud Sync.
2. Use the UI to Log In or Create an Account.
3. The automated sync engine handles the rest behind the scenes.

Background Push

When ready, Cloud Sync will run as a background worker. Captures and edits will be added to a local sync_queue and uploaded sequentially. Your local workflow will never be blocked waiting for a network request.

Content-Addressed Storage

Bug Pocket stores the SQLite database and attachments in your user app data folder. Images are saved by their hash (e.g., a1b2c3d4.png). Do not manually edit the contents of this folder.

Export and Import

Go to Settings > Storage & Backups.

• Export Backup: Creates a .bugpocket archive containing your database and images.
• Restore Backup: Overwrites your current data with an archive. Warning: This is destructive to current data.

Automated Backups

You can set an Auto-Backup Directory. Bug Pocket will periodically export an archive there, keeping only the 3 most recent files to save space.

Global Shortcuts Not Working

If Ctrl+Alt+P or Ctrl+Alt+S do nothing, another Windows application might have registered them first. Go to Settings > Workspace & Hotkeys to record a different combination. Bug Pocket will warn you if a shortcut registration fails.

AI Triage Fails with Network Error

Verify your BYOK provider settings. If using a local model (like Ollama), ensure the server is running. If using a cloud provider, verify your API Key and ensure the Model ID matches the provider's documentation exactly.

"Empty Dropdowns" in Quick Capture

If the Module dropdown is empty, ensure you have selected an Application first. Modules are children of Applications.