What Witness is, how your agent installs and drives it for you, and exactly what lands in the evidence package.
Witness records a human using a web product and turns it into causal evidence an AI coding agent can act on. You talk and point; it keeps the books. One continuous take can hold many issues — segmentation is optional.
Stopping produces a local evidence package under .witness/sessions/<timestamp>/ — nothing leaves your machine unless you hand it to an agent.
The intended flow: you give the instruction, the agent types the commands. Witness is a CLI (wit) that drives your system Edge/Chrome — no browser download, no cloud account, no keys.
Install witness: `npm i -g github:wookat/witness`, verify with `wit --version`. Requires Node 18+.
wit CLI — recorder, session renderer, transcriber, MCP server in one binary. Config at ~/.witness/config.json, ASR creds at ~/.witness/doubao-creds.json. Evidence always lands in the current project's .witness/sessions/.skills/witness/SKILL.md — a ready-made skill file. Drop it into CLAUDE.md / .cursor/rules/ / AGENTS.md and phrases like "帮我录一段" trigger the whole workflow. View it ↗# for transparency — under the hood your agent does:
npm i -g github:wookat/witness
wit --version wit config asr persists to ~/.witness/config.json; --asr / WIT_ASR override per run. Agents can flip it live via the set_asr MCP tool.auto doubao-web → doubao-ime → sr doubao-web best punctuation (default pick) doubao-ime per-sentence timestamps, ITN digits sr browser SpeechRecognition (offline) off no live subtitles (final transcript only)
OPENAI_API_KEY whisper-1 word timestamps
ZHIPU_API_KEY GLM-4 say-correction + associate
WIT_ASR engine override for one run
WIT_NO_BODIES=1 skip response-body capture
WIT_CDP=<port> expose CDP so an agent can drive
the recorded browser as the testeryou → "record http://localhost:5173 for me" agent → runs `wit start`, managed browser opens you → use the product, talk out loud, mark problems you → press ■ (or tell the agent "stop") you → "fix the issues from that recording" agent → reads session.md, fixes from the evidence
speak every observation → timestamped SAY Ctrl+Click mark an element (selector + shot + DOM) M inspect mode — hover-pick or drag a region N new issue boundary (optional) P pause/resume — freezes evidence AND mic ■ / Alt+Shift+R stop
wit start <url> record (agent launches it) wit list / open browse sessions wit transcribe <dir> re-run transcription wit correct <dir> LLM polish (verbatim kept) wit associate <dir> LLM picks evidence per SAY wit recover <dir> rebuild after a crash wit mcp [dir] serve evidence over MCP wit config asr … engine: auto|doubao-web|ime|sr|off
For you: a visual replay. For your agent: a structured handoff it can fix from.
├─ review.html → FOR HUMANS — timeline replay: audio + shots + events, click anything to seek ├─ PROMPT.md → FOR AGENTS — handoff doc: how to read this evidence ├─ session.md → FOR AGENTS — the timeline: every SAY + its causal burst ├─ events.jsonl → raw event stream (1189 events in a real run) ├─ transcript.json → final speech transcript, segment timestamps ├─ audio.webm → the recording, seekable ├─ shots/ → screenshots — marks get red boxes, regions are crops ├─ bodies/ → request/response payloads ├─ dom/ → DOM snapshots at key moments ├─ rrweb.jsonl → full replay stream └─ session.json → meta: url, duration, asr engine, counts
SAY block carries your verbatim words plus what the page did at that second.session_overview · list_says · session_md · events_around · get_errors · get_shot · get_dom_state · get_body · get_asr · set_asr."I recorded a session — evidence is in .witness/sessions/<ts>. Read session.md and fix the issues."
{ "mcpServers": { "witness": {
"command": "wit", "args": ["mcp"]
} } }Agent pulls evidence on demand — and can flip the ASR engine itself.And to make an agent record: "use witness to record http://localhost:5173 — I'll talk through the issues". With WIT_CDP set, an agent can even be the tester inside the recorded browser.
A tiny broken product ships with the site — it has a dead button, a console error and a bad API response waiting to be caught:
wit start https://witness.zalize.com/demo-app.html --duration 60
# click the Pay button, say "点了没反应", stop → open review.html