Metadata-Version: 2.3
Name: devpanel
Version: 0.2.0
Summary: Chrome DevTools panel with terminal and browser context injection for Claude Code
Author: Fredrik Angelsen
Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
Requires-Dist: aiohttp>=3.13.5
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# devpanel

Chrome DevTools panel with an embedded terminal and browser context injection for Claude Code.

## What it does

Opens a terminal inside Chrome DevTools. Claude Code runs in that terminal with a hook that automatically injects browser context into every prompt.

**Select elements** — click Select, Chrome's native crosshair picker activates. Click an element, type an annotation in the prompt, repeat. Selectors queue for the next Claude Code prompt.

**Capture network** — snapshot recent requests from `devtools.network.getHAR()`. Full HAR spills to a JSON file the agent can grep.

**Screenshot** — CDP `Page.captureScreenshot` with clip from the selected element. PNG spills to disk, agent can read it.

**Page HTML** — captured automatically on first element selection. Full HTML spills to a file for grep/read.

Everything drains on prompt submit. Claude Code sees the browser context without you describing it.

## Architecture

```
Chrome DevTools (DevPanel tab)
  ├── Terminal (xterm.js) ──ws──→ PTY daemon (:random)
  ├── Select button ──CDP──→ Overlay.setInspectMode → selector + annotation
  ├── Network button ──→ devtools.network.getHAR()
  └── Screenshot button ──→ chrome.debugger → Page.captureScreenshot

Service Worker
  ├── Native messaging → spawn PTY daemon
  ├── CDP element picker (Overlay domain)
  └── Screenshot relay (chrome.debugger, not available in panel)

PTY daemon (Python, aiohttp)
  ├── WebSocket /ws → terminal I/O
  ├── POST /stack → push context (spills large data to disk)
  ├── GET /stack → drain + clear (formatted text for hook)
  ├── GET /stack?peek=true → raw JSON (for panel UI)
  └── GET /controls → dev endpoint (port, pid, stack size)

Claude Code (in terminal)
  └── UserPromptSubmit hook → curl /stack (drain)
```

## Install

```bash
pip install devpanel  # or: uv tool install devpanel
devpanel install --extension-id=EXTENSION_ID
```

Then load the extension in `chrome://extensions` → Load unpacked → point to the printed path.

The `--extension-id` is shown on the extensions page after loading. Re-run `devpanel install` with the correct ID.

## Usage

1. Open Chrome DevTools on any page
2. Click the **DevPanel** tab
3. A terminal opens with your shell (fish/bash/zsh)
4. A `claude` shell function is injected — it wraps `claude` with `--settings` to add the drain hook
5. Click **Select** → pick elements → annotate → they queue in the stack
6. Type `claude` in the terminal → send a prompt → hook fires, Claude sees the queued context

## Dev

```bash
# Extension
cd extension-src
npm install
npm run build          # required — hot reload doesn't work with CRXJS service workers
npm run check          # svelte-check
npm run lint           # prettier + eslint

# Daemon (standalone, for testing)
uv run devpanel start
# Then: curl localhost:PORT/controls, curl POST/GET /stack

# Full build (extension + Python wheel)
make build
```

## How the hook works

The daemon writes `~/.config/fish/conf.d/devpanel.fish` (cleaned up on daemon exit) that defines:

```fish
function claude
  command claude $argv --settings '{"hooks":{"UserPromptSubmit":[{"matcher":"","hooks":[{"type":"command","command":"curl -s http://127.0.0.1:PORT/stack"}]}]}}'
end
```

For bash, a rcfile with the equivalent function is loaded via `--rcfile` on the PTY shell.

The function shadows the real `claude` binary. `$argv` comes first so wrapper flags (like `--use VERSION`) are parsed before `--settings`. The `--settings` flag merges with other Claude Code settings.

## Drain format

When the hook fires, the agent sees:

```
## Browser Context

### Page HTML
- https://www.wikipedia.org/ → /run/user/1000/devpanel/page-abc.html

### Selected elements
- `div.central-textlogo` — this is the logo
- `nav.central-featured` — language links

### Network
- 8 requests, 1 errors → /run/user/1000/devpanel/network-def.json

### Screenshots
- /run/user/1000/devpanel/screenshot-ghi.png
```

Large data (HTML, HAR, screenshots) spills to disk. The agent uses Read/Grep on the file paths.
