bugshot-skill

# BugShot Skill — AI Bug Fixer for Vibe Coders

**The autonomous debugging agent for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).** Say "it's broken" and your AI agent captures, diagnoses, and fixes the bug — no screenshots, no forms, no tickets. Just fixed code.

> Built for the vibe coding era. You describe the vibe, AI writes the code — and now AI fixes the bugs too.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
[![MCP](https://img.shields.io/badge/MCP-claude--in--chrome-blue)](https://modelcontextprotocol.io)

---

## Why BugShot?

If you're **vibe coding** with Claude Code, Cursor, or any AI coding tool — you've hit this loop:

1. Build a feature with AI
2. Open browser, something's broken
3. Manually screenshot, copy console errors, describe the bug
4. Paste it all back to the AI
5. Wait for a fix, refresh, repeat

**BugShot eliminates steps 2-4 entirely.** Claude looks at the browser itself, reads the errors, finds the broken code, fixes it, and verifies the fix. One command. Zero context-switching.

---

## What It Does

```
You: "the page is broken"
         ↓
    ┌─ CAPTURE ──────────────────────┐
    │  Screenshot the viewport       │
    │  Read console errors           │
    │  Catch failed API requests     │
    │  Inspect the DOM tree          │
    │  Detect framework (Next/React) │
    └────────────────────────────────┘
         ↓
    ┌─ DIAGNOSE ─────────────────────┐
    │  Correlate errors → source     │
    │  Trace API failures → handlers │
    │  Classify root cause           │
    │  Framework-specific patterns   │
    └────────────────────────────────┘
         ↓
    ┌─ FIX ──────────────────────────┐
    │  Edit the broken source files  │
    └────────────────────────────────┘
         ↓
    ┌─ VERIFY ───────────────────────┐
    │  Re-screenshot, re-read errors │
    │  Confirm fix worked            │
    │  Iterate if needed             │
    └────────────────────────────────┘
         ↓
    Fixed: [root cause]
    Changed: [files]
    Verified: pass ✓
```

---

## Quick Start

### Prerequisites

| Tool | Why |
|---|---|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | The AI coding CLI |
| [Claude in Chrome](https://chromewebstore.google.com/detail/claude-in-chrome/adnobificppgfhiodegadklanaopmkfc) | Gives Claude browser access via MCP |
| A running dev server | localhost:3000, 5173, 8080, etc. |

### Install (one-liner)

```bash
mkdir -p .claude/skills && git clone https://github.com/Sreelal727/bugshot-skill.git /tmp/bs && cp -r /tmp/bs/skills/bugshot .claude/skills/ && rm -rf /tmp/bs
```

### Or install globally (all projects)

```bash
mkdir -p ~/.claude/skills && git clone https://github.com/Sreelal727/bugshot-skill.git /tmp/bs && cp -r /tmp/bs/skills/bugshot ~/.claude/skills/ && rm -rf /tmp/bs
```

That's it. No npm, no build, no config.

---

## Usage

### Auto-Fix Mode (default) — just vibe

```
/bugshot
```

Or just talk naturally — the skill auto-triggers:

```
> it's broken
> blank white screen
> getting a 500 error
> the login page looks wrong
> something's not rendering
> there's a console error
```

Claude captures everything from the browser, diagnoses the root cause, fixes your code, and verifies the fix. You don't lift a finger.

### Report Mode — shareable HTML bug report

```
/bugshot report
```

Generates a self-contained dark-theme HTML file with embedded screenshot, AI diagnosis, console errors, network failures, and environment info. Share it with your team or attach to a PR.

### GitHub Issue Mode — auto-file bugs

```
/bugshot github
```

Captures everything and files a GitHub issue via `gh` CLI with full bug report + AI root cause analysis.

### Watch Mode — continuous monitoring

```
/bugshot watch
```

Polls the browser every 30 seconds. When new errors appear, captures full state and alerts you. Perfect for catching bugs during rapid vibe coding sessions.

---

## Example Session

```
$ claude

> my dashboard is showing a blank page

  Capturing browser state...
  ├ Screenshot: white page at localhost:3000/dashboard
  ├ Console: TypeError: Cannot read properties of undefined (reading 'map')
  │          at Dashboard.jsx:42:18
  └ Network: GET /api/users → 500 Internal Server Error

  Diagnosing...
  Root cause: API handler at src/api/users.js:15 throws because
  DATABASE_URL env var is undefined. Frontend crashes at
  Dashboard.jsx:42 trying to .map() over the undefined response.

  Fixing...
  ├ src/pages/Dashboard.jsx — added loading state + null-safe access
  └ src/api/users.js — added env var validation with descriptive error

  Verifying...
  ├ Screenshot: dashboard renders with user list ✓
  ├ Console: 0 errors ✓
  └ Network: GET /api/users → 200 ✓

  Fixed: Missing DATABASE_URL env var caused API 500; frontend had no null guard
  Changed: src/pages/Dashboard.jsx, src/api/users.js
  Verified: pass
```

---

## Framework Detection

BugShot auto-detects your framework and applies specialized AI diagnosis:

| Framework | Detection | Known Patterns |
|---|---|---|
| **Next.js** | `__NEXT_DATA__` | `Unexpected token '<'` (API returning HTML), hydration mismatch, RSC errors |
| **React** | `[data-reactroot]` | `Cannot read properties of undefined`, invalid hook calls, missing keys |
| **Vue** | `[data-v-]` | Reactivity issues, missing component registration |
| **Nuxt** | `__NUXT__` | SSR hydration, async data fetch failures |
| **SvelteKit** | `__svelte_meta` | Load function errors, SSR mismatches |
| **Remix** | `__REMIX_DEV_TOOLS` | Loader/action failures, route errors |
| **Vite** | `vite-error-overlay` | Pre-transform errors, HMR disconnects, import resolution |

---

## How It Works Under the Hood

BugShot is a Claude Code **skill** — a markdown file that teaches Claude new capabilities. It uses the **Model Context Protocol (MCP)** via [Claude in Chrome](https://chromewebstore.google.com/detail/claude-in-chrome/adnobificppgfhiodegadklanaopmkfc) to give Claude direct browser access:

| MCP Tool | What BugShot Uses It For |
|---|---|
| `computer` | Screenshot the viewport |
| `read_console_messages` | Capture console errors, warnings, uncaught exceptions |
| `read_network_requests` | Catch failed HTTP requests (4xx/5xx) |
| `read_page` | Inspect DOM / accessibility tree |
| `javascript_tool` | Collect page metadata, detect framework |

Then it uses Claude Code's built-in tools (`Grep`, `Read`, `Edit`) to find the broken source files and fix them.

**No Chrome extension needed** beyond Claude in Chrome. BugShot doesn't need the [BugShot Chrome Extension](https://github.com/Sreelal727/bugshot) — it replaces the entire capture-and-report workflow with agentic AI.

---

## BugShot Chrome Extension vs BugShot Skill

| | [Chrome Extension](https://github.com/Sreelal727/bugshot) | This Skill |
|---|---|---|
| **For** | QA, PMs, manual testers | Vibe coders using AI |
| **Captures** | Screenshot + annotate + form | Autonomous — Claude does it all |
| **Output** | Bug ticket (GitHub/Jira/Slack) | Fixed code |
| **Diagnosis** | Human reads the errors | AI reads, correlates, classifies |
| **Verification** | Human checks the fix | AI re-checks the browser |
| **Requires** | Chrome extension installed | Claude Code + Claude in Chrome |

---

## File Structure

```
bugshot-skill/
├── README.md
├── LICENSE
└── skills/
    └── bugshot/
        ├── SKILL.md                  # Skill definition (~290 lines)
        └── report-template.html      # Dark theme HTML report template
```

Two files. That's the entire skill.

---

## Troubleshooting

| Problem | Fix |
|---|---|
| `/bugshot` not recognized | Verify `SKILL.md` is at `.claude/skills/bugshot/SKILL.md` or `~/.claude/skills/bugshot/SKILL.md` |
| "No tab found" | Open Chrome with Claude in Chrome extension active |
| Browser tools not r

[truncated…]