screen-leads-app/README.md

Screen Leads

Turn a browser tab you have open on a profile into a structured lead. The tool screenshots the screen, scrolls, runs the images through Claude vision, and saves normalised leads to a database you browse and control from a dashboard.

Screen-capture only: it reads pixels a human already chose to display and never touches the target site's servers or DOM. LinkedIn is the first supported site; new sites drop in as recipes.

How it works

Start (dashboard) → detect front tab → [stop unless it's an enabled
site's target page, e.g. a LinkedIn profile] → scroll + screenshot loop →
Claude vision extraction → normalise to canonical Lead → SQLite → dashboard

• Guard — runs only when the front tab is an enabled recipe's target page (a LinkedIn /in/ profile). On anything else it stops (set SCREEN_LEADS_ON_INVALID_PAGE=wait to poll instead).
• Detection — reads your own browser's URL where possible (macOS reliably), otherwise the AI reads the address bar from the screenshot. Both are passive.
• Contact info — name/headline/company come from the profile page. Email & phone live behind LinkedIn's Contact info panel: open it yourself before capture and the tool will read whatever is shown. Often it simply isn't there.
• Funnel — every lead is normalised to one schema and advances NEW → ENRICHED → CONTACT_FOUND → EXPORTED as data completeness grows.

Setup

# 1. Get the code
git clone https://git.thecaoffice.com/OpenSource/screen-leads-app.git
cd screen-leads-app

# 2. One-time setup — venv, dependencies, and prompts for your API key
./setup.sh          # Windows: setup.bat

# 3. Run it
./run.sh            # Windows: run.bat

setup.sh creates the virtualenv, installs dependencies, and writes your ANTHROPIC_API_KEY to .env. run.sh launches the dashboard — open http://127.0.0.1:8000 and use Start / Pause / Stop.

Manual steps (no scripts)

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python main.py

OS permissions (grant once)

OS	Needs
macOS	System Settings → Privacy & Security → Screen Recording and Accessibility for your terminal/app. Automation permission for the browser enables exact URL detection.
Windows	Usually none. pip install uiautomation enables native URL detection.
Linux	Use an X11 session. Wayland can't capture/scroll via mss/pyautogui — switch to X11 or use the desktop screenshot portal.

Usage

1. Open a LinkedIn profile in your normal browser (optionally open Contact info).
2. Click Start on the dashboard.
3. The tool scrolls, captures, extracts, and saves the lead; it then waits for you to open the next profile. Navigating away from a profile stops the run (default) so it never runs on non-target pages.

Project layout

screen-leads/
  agent/          capture loop pieces: screenshot, scroll, detection
    platform/     native URL helpers (mac / windows / linux)
  ai/             Claude vision extraction + per-site recipes
    recipes/      base.py, linkedin.py, registry (__init__.py)
  core/           canonical models + capture controller (state machine)
  db/             SQLite persistence (leads + runs)
  api/            FastAPI: /api/start /pause /resume /stop /status /leads
  dashboard/      single-file web UI
  config.py  main.py

Adding a new site

1. Add ai/recipes/<site>.py implementing SiteRecipe (matches, extraction_schema, extraction_prompt, to_canonical).
2. Register it in ai/recipes/__init__.py.

Nothing in the capture loop changes — the guard and pipeline are recipe-driven.

Compliance note

Automated scraping of LinkedIn violates its Terms of Service. This tool is built for low-volume, human-in-the-loop use on profiles you manually open and are allowed to view. Keep pacing conservative and use it accordingly.