proto-buddy

Proto Buddy — Design Companion

Interactive design review server. Compare HTML options as tabs, click elements to annotate, choose quick actions, iterate with live hot reload. Real-time feedback via log watching.

Startup Sequence

Execute these steps in order:

1. Start server

${CLAUDE_PLUGIN_ROOT}/scripts/start.sh --dir <DIR> --port 3333

Default dir: .ai/brainstorm. Customize with --actions "keep,remove,size-up,size-down,recolor".

2. Open browser

open http://localhost:3333

3. Write initial design options

Write HTML files to the watched directory. Each file becomes a tab.

# Fragments get wrapped automatically
write <DIR>/option-a.html   # Tab "Option A" appears
write <DIR>/option-b.html   # Tab "Option B" appears

4. Start watching for feedback

Run in background — you get notified when the user annotates:

${CLAUDE_PLUGIN_ROOT}/scripts/watch-one.sh <DIR>

This watches for one new event then exits. Run in background — when it completes, read the output for new annotations. Re-arm after each event.

If there are unread events when the watcher starts, it returns them immediately without blocking.

Each line is JSON:

{"type":"comment","tab":"option-a.html","selector":"div > h1","coords":[340,120],"comment":"too much padding","action":"size-down"}

5. React to feedback

When the watcher produces output:

1. Parse the JSON event(s)
2. Find the selector in the source HTML file (tab field)
3. Apply the action and address the comment
4. Write the updated HTML — tab hot reloads automatically
5. Re-arm the watcher for the next event

6. Repeat

Loop between writing designs and reacting to feedback until user is satisfied.

Events File Format

<DIR>/.events — JSONL, append-only. Canonical record of all annotations:

{"type":"comment","tab":"option-a.html","selector":"div > h1","coords":[340,120],"comment":"too much padding","action":"size-down"}
{"type":"update-comment","tab":"option-a.html","selector":"div > h1","comment":"better now","action":"keep"}
{"type":"apply-all","tab":"option-a.html"}
{"type":"tab-reloaded","tab":"option-a.html"}

Two Feedback Modes

• Live mode (default): each annotation fires immediately. React as comments come in.
• Batch mode: user accumulates annotations, clicks "Apply All" when ready. Process the batch.

Quick Actions

Default: keep, remove, size-up, size-down. Extensible via --actions flag on start.sh.

Browser Features

• Tab bar with comment count badges per tab
• "NEW" indicator on tabs when Claude pushes changes user hasn't seen
• History panel (H key or button) — all annotations with click-to-navigate and element highlighting
• Mode toggle — Live/Batch with Apply All button
• DevTools-style inspector — hover to see element outlines, click to annotate
• Annotation badges — numbered circles on annotated elements, click to edit

Stop Server

${CLAUDE_PLUGIN_ROOT}/scripts/stop.sh --dir <DIR>

Keyboard Shortcuts (Browser)

• 1-9 — switch tabs
• L / B — live / batch mode
• H — toggle history panel
• Enter — submit comment (in popover) or apply all (batch mode, outside popover)
• Shift+Enter — newline in comment
• Escape — close popover