drpwchen/deja-browser

Your AI agent gets its own browser — and remembers each site, so the next visit skips reading the page (~50× less text in the demo below).
A real run against hn.algolia.com: first visit 29,427 characters of page for the model to read,
recipe replay 588 characters of JSON. Wall time (median of 3) 3.5 s plus model reading vs 1.1 s.
Learn once, replay. The first visit finds the site's JSON endpoint or form and saves it as a
recipe; later visits replay it without reading the page — ~50× less text for the model.
Not your browser. A separate Chromium profile driven over CDP on 127.0.0.1. No extension
in your everyday browser; your mail, bank and broker are simply not logged in there.
No telemetry, tested. tests/egress/run.sh
traces every connect() in a loopback-only network namespace and fails on anything else.
No passwords in the browser. Secrets stay in your OS keyring or password-manager CLI;
recipes only name them.
Works with any agent that can run shell commands — Claude Code, Codex CLI, Gemini CLI, Cursor,
Aider — and from plain Python. MIT. Early release (0.1): tested on Windows 11 (Edge), macOS on
Apple Silicon (Chrome) and Linux (headless Chromium).
## Quick start
Requirements & cost. Python ≥ 3.11 and an installed Edge, Chrome, Chromium or Brave (Windows, macOS or Linux). Free (MIT), no accounts, no API keys; the only optional paid-account feature is the opt-in hCaptcha solver, which uses your own Gemini key.
sh
pip install "deja-browser[stealth,keyring]"
deja-cdp launch # start the agent's browser
deja-cdp navigate '{"url": "https://example.com"}' --session demo
deja-cdp snapshot '{"max_chars": 2000}' --session demo # what the agent reads
deja-cdp close_session '{}' --session demo # closes only this session's tabs
Each command prints one line of JSON; the snapshot line holds the page text, cut to 2000 characters.
Or let your agent do the setup. Tell it: "Read
https://github.com/drpwchen/deja-browser/blob/main/AGENTS.md and set this up with me." It asks you
the few choices that matter, has you log in to your sites by hand, and runs a smoke test.
> 🧋 Saved you some time? Buy me a drink.
## Your first recipe
Save this as draft.json (a minimal recipe for the site in the GIF, using its public JSON API):
json
"name": "search",
"description": "Hacker News full-text search (example)",
"entry_url": "https://hn.algolia.com/",
"params": [{"name": "q", "required": true}],
"request": {"method": "GET", "url": "https://hn.algolia.com/api/v1/search?query={q}"},
"pick": {"path": "hits", "fields": ["title", "url"], "limit": 20},
"writes": false
sh
deja-browser verify draft.json '{"q": "rust"}' # try every tier, print shape + preview
deja-browser save draft.json # only after a passing verify of this draft
deja-browser run hn.algolia.com/search '{"q": "rust"}' # replay: titles + URLs, no page read
deja-browser list
No recipes ship with the package — you (or your agent) build them per site, usually from a
network_capture of the first visit. Recipes live in / / .json and are
addressed as / . deja-browser --help documents the full format.
## Compared with browser-extension bridges
| | Extension bridge | deja-browser |
| Where the agent acts | an extension with full debugger access, inside the browser where you are logged in to everything | its own profile, logged in only to the sites you chose |