Robb Doering
All work

piq

Lets an agent look at a web page, window, or terminal and ask what it shows.

Source on GitLab Python · MIT · v0.1.0
piq takes a target and dispatches on its syntax (an explicit prefix, a URL, a live session name, or a command on PATH) to one of four capture backends: web: drives headless Chrome or Chromium through Playwright, tui: spawns the program in a kitty window, win: locates an existing window through KWin, and image: reads an image file as it is. The capture goes to the vision layer, which probes for a local server first (ollama, llama-server, vllm) and, when none answers, sends the image through the gateway on port 4000 (cyan), which relays it to a remote model. The result is a report: a written answer plus the path of the screenshot. piq <target> web: playwright tui: kitty win: kwin image: file vision local, if up ollama llama-server vllm else gateway :4000 report answer + png path

piq gives an agent eyes. Point it at a web page, a terminal program, a window, or an image, and it captures it and (optionally) asks a vision model what it shows, grounded with the page or terminal text when that's available.

It prefers local models when one is running and only falls back to a remote gateway after that. I use it constantly, including to review the screenshots on this site.

$ piq image:$PWD/page.png -m openrouter/google/gemini-3.5-flash -q 'In two sentences: what is this page, and what can a visitor do here?'
● image: tmp1767474   via: file   model: openrouter/google/gemini-3.5-flash
● screenshot: file://~/ai/scratch/demo-t/piq/page.png
● pixels sent to: PIQ_GATEWAY (http://localhost:4000)

This page is the introduction to "Origami Odyssey," an educational website featuring precise, step-by-step origami folding lessons. Visitors can click the "Open the lessons" button to begin learning how to fold a sailboat, access a user guide, or customize the website's visual theme.
piq captures a web page, terminal program, window, or image and grounds the capture with page or terminal text when it is available. It then resolves a vision provider in order: an explicit --provider, then PIQ_BASE_URL or PIQ_GATEWAY, then a reachable local OpenAI-compatible server (Ollama, llama-server, or vLLM, defaulting to the gemma3 model), and only then the configured gateway. A real piq doctor run on this machine confirmed that order resolves to the gateway when no local server is reachable. web tui win image capture + page/terminal text anything else error: cannot resolve target. Tried: URL, live session, command. None resolved. --provider PIQ_BASE_URL / PIQ_GATEWAY local: ollama, llama-server, vLLM model: gemma3 gateway: localhost:4000 vision model → answer piq doctor, this run confirms the order: resolves to the gateway