Record a browser task once. Replay it deterministically, without the model. Repair it when the page changes.
Browser agents re-derive the same work on every run. Ask one to pull a report out of a dashboard, and it re-reads the DOM, re-plans, and re-infers every click — burning tokens and wall-clock to rediscover a path it already found yesterday, with a fresh chance of getting it wrong.
Paragent takes the model out of the second run. It records a developer's successful trajectory through a web UI, compiles it into a deterministic replayable script with a post-condition assertion on every step, and replays it with no model in the loop. When an assertion fails — a button moved, a label changed — the model is called back in to repair just that step, and the repaired script is what runs next time.
Real run against the bundled fixture, driven by an illustrative script rather than the
documented npm run commands. The record and replay beats are what
the repo ships — record today means a developer typing the trajectory by hand
(src/recorder/cli.ts), not an agent proposing it; that on-ramp is scoped but
not yet built (#127). The
repair beat is not: Paragent ships StubRepairModelClient, which proposes
nothing, so repair needs a model client that is
not yet wired (#27).
| Stage | What happens | Model involved? |
|---|---|---|
| Record | A developer completes the task once, by hand. Every action and its post-condition is captured as a trajectory. | No |
| Compile | The trajectory becomes a bundle of cache rows — one per step, each with its assertion. Typed values become parameter slots. | No |
| Replay | Steps execute in order. Each asserts its post-condition before the next runs. | No |
| Repair | On assertion failure, the model is called to fix that step; the updated script is written back. | Only on failure |
The assertion-per-step design is the load-bearing part: a replay that drifts fails loudly at the step that broke, instead of silently completing the wrong task.
No clone, no credentials, no live site — a browser fixture ships inside the package.
npx playwright install chromium # one-time: the browser binary Playwright drives
# 1. Record a login → dashboard-list trajectory against the bundled fixture
# (the recorder serves it over loopback for the length of the recording)
npx paragent record --fixture --out trajectory.json
# 2. Compile it into a replayable bundle, one cache row per step
npx paragent compile --in trajectory.json --out bundle.jsonnpx playwright install chromium is a separate step on purpose: it downloads a
browser, and a package that pulls ~150 MB during npm install without asking is
a bad guest. Everything else works offline.
Replaying that bundle needs host and port bound to a server for the fixture
pages — the same holes a recording against a real site carries.
Point the recorder at a real site instead:
npx paragent record --base-url http://127.0.0.1:3000 --headedRecorded values become parameter slots, so one recording covers a family of runs:
npx paragent record --fixture --dashboard-title "Q3 Latency" --series-count 5From a clone, if you want to contribute
git clone https://github.com/DevToolie/Paragent.git
cd Paragent
npm install
npm run recorder -- --fixture --out trajectory.json
npm run compile -- --in trajectory.json --out bundle.jsonThe npm scripts run the same code through tsx; the published package ships
compiled JavaScript and does not need it.
Credentials are read from PARAGENT_USERNAME / PARAGENT_USER_SECRET and are never
persisted to disk. Full command list: docs/DEVELOPMENT.md.
Most browser-agent frameworks optimise the first run — better planning, better DOM grounding, better recovery. Paragent is meant to compose with them rather than replace them: record whatever agent you already trust, then replay its output. That's the target, not what ships today — the recorder captures a developer's hand-typed actions, not an arbitrary agent's, until #127 lands.
It's aimed at work that is repeated, in a browser, where no clean API exists — the cases where you'd write a script if the UI would just hold still.
Paragent is pre-seed, two weeks old, and its central thesis is not yet proven. We publish the failures alongside the code:
| Track | Question | Status |
|---|---|---|
| Track 1 | Do compiled trajectories survive site churn? | Harness in progress — no gate number yet |
| Track 2 | Is there a vertical where the counterparty hypothesis holds? | FAIL — no vertical locked |
| Track 3 | Narrative / pitch | Wave-1 draft; all performance claims [PENDING TRACK-1] |
Two consecutive vertical FAILs mean the project now rests on the Track-1 mechanism number, which does not exist yet. There are no performance benchmarks in this README because there are none to report. Any number you see here later will be traceable to a gate run.
The full internal picture — research, decision records, both FAIL memos, the pitch pack, and the contributor rules — is preserved verbatim and kept current in docs/README-internal.md. Start there if you are an agent, a contributor, a candidate, or an investor. Nothing is softened there and nothing is hidden.
| docs/README-internal.md | Full project status, tracks, and FAIL memos |
| docs/architecture.md | System design |
| docs/DEVELOPMENT.md | Commands, pre-PR checklist |
| docs/ROADMAP.md | What's next |
| docs/decisions/ | ADRs |
| docs/research/ | Census and vertical research, including failures |
npm run ci must be green before any PR — secret-scan, contract validation, lint,
typecheck, unit tests, then integration tests. The privacy canary
(npm run test:canary) is a separate merge-blocking job.
This repo is public by design (ADR-0005).
Never commit credentials, cookies, session state, .env files, tokens, customer or
design-partner names, or third-party portal content. Secret scanning with push
protection is enabled and those checks may not be weakened.
Read CONTRIBUTING.md first — rule 4 is that findings are never softened, and it applies to everyone.