38604-vm/aiea/LOCAL_SCREENSHOT_EXTENSION.md

Local Chrome Screenshot Extension (Unpacked)

This is a local-only setup (no publishing) that:

1. Captures the visible tab as a PNG from a Chrome extension popup.
2. Sends it to a local HTTP server on 127.0.0.1.
3. Extracts simplified page content (text + a pruned “content tree”) from the active tab.
4. The server saves it into ./screenshots/ and optionally runs a local script.

1) Start the local server

From the project root (recommended: use a venv):

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

export OPENAI_API_KEY="..."

python3 tools/local_screenshot_bridge.py --port 8765 --out-dir screenshots --ai

Notes:

• The server listens on http://127.0.0.1:8765/screenshot.
• If you omit --ai, it will only save files (no OpenAI call).
• If you set --ai, it will generate reply suggestions and return them back to the extension (and also save *.ai.json).
• If you're debugging, add --log-level debug (or set AIEA_LOG_LEVEL=debug) for more detail.
• Optional: you can still use --run ... as a post-save hook.

2) Load the extension (unpacked)

1. Open Chrome: chrome://extensions
2. Enable "Developer mode"
3. Click "Load unpacked"
4. Select: chrome_screenshot_ext/

3) Use it

1. Click the extension icon.
2. Confirm the endpoint is http://127.0.0.1:8765/screenshot.
3. Optionally add "Extra instructions" (saved locally in the extension).
4. Click "Capture".
5. Use the "History" dropdown + "Show" to view older AI suggestions.

Saved files land in screenshots/:

• YYYYMMDDTHHMMSSZ-<title-slug>.png
• YYYYMMDDTHHMMSSZ-<title-slug>.json
• YYYYMMDDTHHMMSSZ-<title-slug>.content.json
• YYYYMMDDTHHMMSSZ-<title-slug>.ai.json (when OPENAI_API_KEY is set)

Alternatively create .env in the project root:

OPENAI_API_KEY=...