---

Why this exists

An agent that cannot see cannot check its own work, so it tells you what it believes it did. Watch Skill gives it two things it did not have: perception — video, audio and screen activity turned into frames, transcripts and OCR text, every one carrying an absolute timestamp — and verification, a frozen contract run by a separate process whose verdict does not come from a language model.

Both halves are useful on their own, and the split is deliberate.

Watch Skill is what sees and proves. DeepWatch is where the work happens.

---

What it actually looks like

An ordinary request — create totals.json and tell me the sum. Nobody mentioned Watch.

Every row is a receipt, every path is workspace-relative, and the total was read back from the file rather than remembered. Then the part that matters:

watch_verify ran a frozen contract and Watch Core answered. The agent did not grade itself: a check either passed or it did not, the contract's SHA-256 is on screen, and the same contract run from a different directory fails.

Every image on this page is a photograph of a running build. The screenshot page names the build each one came from.

---

Start here

Three entry paths. Pick the row that describes you.

1. Add Watch Skill to an agent you already use

pip install 'watch-skill[standard]'   # frames, retrieval and the MCP server
watch-skill doctor                    # checks, and repairs what it can
watch-skill watch <video-url-or-file>
watch-skill ask <id> "what changed at 3:12?"

Take the extra seriously. A bare pip install watch-skill gives you the CLI, the verifier and the Bridge, and it cannot extract a frame: watch stops at perceive.missing_dependency on the first video. [standard] is frames, retrieval and MCP; add [ocr] to read on-screen text, [whisper] for local transcription when a source has no captions, [loop] for the browser, or take [all]. watch-skill doctor names the exact command for whatever is missing.

Wire it into any MCP client — [standard] includes the server:

watch-skill serve              # stdio MCP server, 39 tools

Or install the skills into 25+ agents at once:

npx skills add oxbshw/watch-skill -g

2. The whole workspace

Not on npm yet. Nothing exists under the @deepwatch scope until the deepwatch-v0.1.0 release publishes it, so the command below resolves nothing today. Getting started has the path that works from a checkout.

npm install -g @deepwatch/cli
deepwatch setup                 # builds the runtime and composes the profile
deepwatch web --workspace ./my-project

@deepwatch/cli is the package; npm, npx and pnpm dlx are three ways to reach it, not three products. deepwatch doctor reports what is installed and what is missing; deepwatch setup is the only thing that builds, and it asks before downloading anything.

3. Into a DeepSeek Harness you already run

Not on npm yet, the same as above — the bundle is published by deepwatch-v0.1.0. Until then, compose it from a checkout: getting started.

dsh plugin --profile web add @deepwatch/dsh-bundle

That is the whole installation. The package declares dsh.bundle.patch, so DSH reconciles it into the profile's layer stack and applies the patch after its own. Four narrower variants — media, browser, memory, document — are declared alongside it for a profile that wants one capability rather than all of them.

Add the engine with pip install watch-skill; the Bridge finds it on PATH. Full guide: @deepwatch/dsh-bundle.

Requirements. Node ≥ 22.19 and Python 3.11, 3.12 or 3.13 — the versions CI runs and the classifiers declare. Windows, macOS and Linux.

---

THE LOOP: observe, act, verify

Perception is only half of it. THE LOOP is what an agent does with perception when it is trying to fix something.

pip install 'watch-skill[standard,loop]' && playwright install chromium

watch-skill loop start http://localhost:3000/checkout \
  "the total updates when quantity changes, and no NaN appears"

1. Observe — a real browser records the page to video; frames are extracted and OCR'd, each with an absolute timestamp.
2. Critique — a vision model is asked whether the capture meets the criteria you wrote. It reports issues with the timestamp each was seen at.
3. Fix — you change the code.
4. Verify — watch-skill loop iterate re-captures and diffs against the previous run, so "fixed" means the thing that was wrong is gone.

The critique step needs a vision-capable model. Without one, capture, frames, OCR and verification still work, and the critique says it cannot judge rather than guessing. See THE LOOP.

Corrections become lessons

When an answer is wrong, you correct it. Watch Skill classifies the correction, stores it as a lesson in the local store, re-asks the question with the lesson applied where the error class is mechanical, and counts what that saved.

Lessons persist between runs and stay on your machine. Nothing learns on its own — the correction is yours to give — and nothing is uploaded. Lessons and savings.

---

What people use it for

Each is a directory you can run, with its prerequisites and expected output written next to it.

All 20 examples, by what they teach

Learn the core	01 Watch and ask · 02 Focused moment · 03 Cross-video search
Build with agents	06 MCP and REST · 09 Framework adapters · 15 Private offline workflow
Understand and organise	05 Multilingual Arabic · 10 Structured extraction · 11 Batch mode · 12 Library memory · 16 Shareable viewer
Verify and improve	04 UI loop · 07 Lessons and stats · 08 Loop types · 13 Self-improvement · 14 Browser verification · 17 Freshness and offline · 20 Observer loop
Watch live	18 Live watch · 19 Live browser

That is all 20 examples; the index is examples/.

---

How it fits together

flowchart LR
  subgraph W["DeepWatch workspace"]
    H["DeepSeek Harness<br/>agent, tools, UI"]
    P["Watch plugins<br/>tools · library · live · memory"]
    H <--> P
  end
  P <-->|"Bridge (stdio)"| C["Watch Core<br/>Python engine"]
  C --> E[("Evidence store<br/>frames · transcripts · index")]
  C --> V["Verifier<br/>isolated subprocess"]
  V --> R[("Verification records<br/>contract · checks · verdict")]
  P --> J[("Receipt journal<br/>one per tool call")]
  A["Any other agent<br/>MCP · CLI · REST"] <--> C

Watch Core is the only thing that issues a verdict. The Host may notice, correlate, freeze a contract and ask — it may not decide the answer. That is ADR-002, and a build gate fails if anything under packages/ starts producing verdicts.

A receipt records what a tool call did; a verdict records what Core checked. They are written by different processes and the Library shows them as different columns, because an agent that ran a command successfully and an agent that did the right thing are not the same claim.

More: architecture · verification · the 39 tools.

---

What works, and what it needs

DeepWatch starts, and stays useful, with no provider configured: verification, containment, the Library and local perception are all local. What needs a provider is the agent — chat, tool use, and the critique step of THE LOOP.

Three ways a capability arrives, and they are not interchangeable. A local dependency (ffmpeg, yt-dlp, a JS runtime) runs on your machine and watch-skill doctor will fetch and repair it. A downloaded model (OCR weights, whisper) also runs on your machine, is a large one-time download, and nothing about your files leaves it. A hosted provider — the agent's model, and any vision model you bind — is somebody else's service, with their latency, price and terms, and it sees what you send it. An OpenAI-compatible server you run yourself (Ollama, vLLM, LM Studio, llama.cpp) is the hosted route pointed at your own hardware: the data stays local, and whether a given model supports tool calls or images is a property of that model, which DeepWatch reports rather than works around.

Nothing reaches a provider until you add one, and holding a provider credential is not permission to upload a frame or a transcript — that is a separate consent.

What repairs itself. watch-skill doctor repairs dependencies: it downloads yt-dlp and keeps it current, bootstraps a JS runtime, installs OCR language data, and fetches ffmpeg where it can, reporting every repair. That is the only thing here that acts without being asked. There is no automatic task resumption, no autonomous learning, and no encryption at rest in this release. Known limitations is the full list.

---

Measured, not asserted

Against a leading video-understanding API, same files, same scorer:

Method and fixtures: benchmarks/video_backends/. Trade-offs against the alternatives: comparison.

---

Documentation

DeepWatch: workspace README · setup · the twenty packages · releasing · platform support

Three tool counts, because they answer different questions: 39 MCP tools from watch-skill serve, 22 watch_* tools added to an agent inside DeepWatch, 47 tools that agent is offered in total.

---

Community

Written by other people, about using this:

• Watch Skill 使用教程：让 Codex 看懂视频和录屏 — step-by-step tutorial for wiring Watch Skill into Codex (Chinese)
• Watch Skill: AI video analysis and video correction — setup and operation guide with its own use cases and troubleshooting (English)
• Video walkthrough · second part — Bilibili (Chinese)
• Skills.sh · SkillsMP — install directly from a skills directory

The full collection, separated into tutorials, video, integrations and directory listings: docs/ecosystem.md.

---

Contributing

Issues and pull requests welcome. CONTRIBUTING.md has the twenty-minute path: what to install, which gate to run, and how the commit messages are shaped. Security policy: SECURITY.md. Design decisions and their reasons: DECISIONS.md and ROADMAP.md.