Model or dataset
oxbshw/watch-skill avatar
oxbshw/watch-skill

watch-skill splits perception from verification, and the split is the product

Give AI agents eyes, ears, and verifiable results. Watch Skill turns video, audio and screen activity into searchable, timestamped evidence and proves work with deterministic contracts, not model opinion. DeepWatch is the agent workspace built on DeepSeek Harness. Python + npm, MCP, CLI, REST, Web.

584 stars83 forksPythonMIT

At a glance

What is it?
watch-skill has two capabilities that work apart. Perception turns video, audio, and screen activity into timestamped evidence an agent can query over MCP. Verification evaluates a frozen contract in a separate process and returns one of four verdicts, none of which comes from a language model. The documentation is unusually honest about the failure mode of a default install.
Who is it for?
watch-skill fits a team whose agents act on video or screen recordings and then have to prove what happened, since the timestamped citations and the separate verifier are the two things a transcript summary cannot give you. It does not fit anyone who wants a turnkey install, because the default package deliberately omits the ability to extract a frame and the browser tier is not in the container image.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 20 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • oxbshw/watch-skill584 ★ · +215
Star history
Repository2026-09-112026-11-15
oxbshw/watch-skill369584

215 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A bare pip install gives you a CLI that cannot extract a frame

The install instruction carries a warning that most projects would phrase more gently, and it is the first thing to know:

bash
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?"

A bare `pip install watch-skill` gives you the CLI, the verifier, and the Bridge, and it cannot extract a frame. The documented symptom is precise: `watch` stops at `perceive.missing_dependency` on the first video. Not a warning, not degraded output. A stop.

The extras map to capabilities. `[standard]` is frames, retrieval, and the MCP server. `[ocr]` reads on-screen text. `[whisper]` does local transcription when a source has no captions of its own. `[loop]` adds the browser, and `[all]` takes everything. The instruction to take the extra seriously is not a suggestion, and `watch-skill doctor` names the exact command for whatever is missing.

A tool that fails loudly on an incomplete install is better than one that quietly returns nothing, and this is the project being explicit about a choice it made. The default is small on purpose, and the failure tells you which extra to add.

Four verdicts, because failed is not the same as unverified

The verification side evaluates a frozen contract in a separate process. A contract is one of: file digests, JSON values, SQL results, HTTP responses, or DOM state. The verdict that comes back is one of four values, and the project gives the reason for the count in a short clause: three of them are not the same as no.

The four are VERIFIED, FAILED, UNVERIFIED, and INCONCLUSIVE. That is the design decision worth sitting with. A boolean gives you two states and forces everything uncertain into the failure bucket, which makes a tool that reports failures unusable for automation: you cannot distinguish a check that ran and disagreed from a check that never ran at all. A contract that could not be evaluated should not read as a contract that failed.

The other half of the design is that the verdict does not come from a language model. That is the whole argument of the project in one clause. An agent asked whether its own work succeeded will produce a confident sentence, and the confidence carries no information about whether the underlying thing was true. Evaluating the contract in a separate process means the thing being checked and the thing doing the checking are not the same actor.

The capabilities are described as useful apart as well as together, and the split is deliberate. Perception gives an agent eyes; verification gives someone else the authority to say the eyes saw correctly.

Index once, then ask questions for as long as you keep the file

The perception path is described in a sentence that contains the whole value proposition: index a source once and query it for as long as you keep it, and every answer cites a moment you can open.

Video, audio, and screen activity become frames, transcripts, and OCR text, each carrying an absolute timestamp. The query interface is a natural language question about a specific moment, as in the example above asking what changed at 3:12. What makes that different from a transcript summary is the citation. An answer that says a change happened at 3:12 can be checked by opening 3:12.

The examples directory is numbered and shows the shape of the intended use. There are twenty of them, from watching and asking, through a focused moment, cross-video search, a UI loop, multilingual Arabic, agent integration, lessons and stats, loop types, and framework adapters, through to structured extraction, batch mode, library memory, self-improvement, browser verification, a private offline workflow, a shareable viewer, freshness and offline behaviour, live watch, a live browser, and an observer loop.

A few of those names answer questions the README does not. Private offline workflow and freshness-and-offline suggest that the project expects people to work on material that cannot go to a network, and self-improvement suggests the lessons recorded from one run feed the next. Cross-video search is the one that changes the shape of a task: the unit of retrieval stops being a file and becomes a moment.

MCP server, CLI, and REST, plus a skills installer for 25-plus agents

Access is deliberately broad. Any agent can reach the engine through MCP, a CLI, or a REST API, and the standard extra includes the server:

bash
watch-skill serve              # stdio MCP server, 39 tools

Thirty-nine tools on a stdio server is a lot of surface for a client to advertise, and it is the reason the per-client support document exists. The repository links a separate page for Claude Code, Cursor, the Codex CLI, the GitHub Copilot CLI, the Gemini CLI, Cline, Zed, Windsurf, OpenCode, and VS Code, and then a table describing how far each of them is verified. That table is a more honest signal than a compatibility badge.

There is also a bulk installer for the skills themselves:

bash
npx skills add oxbshw/watch-skill -g

The MCP surface is stdio rather than HTTP, which matters for anyone running it in a container. The Dockerfile explains why: stdio MCP needs a clean stdout, so the entrypoint is the CLI itself and the default command is the thing most people want. The container also skips the Playwright browser deliberately, because Chromium plus its system libraries roughly doubles the image size. Everything except the browser loop works as-is in the image, and `doctor` says so rather than letting you find out at runtime.

To add the browser in the container, the image comment shows the two lines to extend it with. That is the kind of instruction that saves an afternoon.

Two numbers, because installed and proved are different facts

The workspace is a separate product called DeepWatch, built on the DeepSeek Harness with Watch Skill already composed in, and installed by one command. There is also a bundle for people who already run a DeepSeek Harness and want to keep their setup.

The setup sequence is three steps:

bash
# 1. the engine that sees and proves (optional, but it is the point)
pip install 'watch-skill[standard,ocr]'

# 2. the workspace
npm install -g @deepwatch/cli
deepwatch doctor                     # what is present, what is missing, how to fix it
deepwatch setup                      # builds the runtime; shows the download and asks first

# 3. a workspace directory to work in
mkdir my-project
deepwatch web --workspace ./my-project

The engine step is labelled optional, and the parenthetical is the argument: without it, DeepWatch starts and reports every Watch capability as unavailable.

What the first screen shows is the part worth reading twice. There are two numbers rather than one fraction, and the reason given is that installed and proved are different facts. Ready now counts what has passed a runtime gate. Needs setup counts what has not been configured or not been tested. The stated rule is that saved is never presented as tested.

That is an unusual thing for a setup screen to promise, and it is the same discipline as the four verdicts. A status display that conflates present with working is how people end up trusting a component that has never run. The workspace also runs in a browser, opens without a configured model provider, and has a Compare view that puts two runs of the same contract side by side and shows where their verdicts diverged.

Every tool call leaves a receipt, and every path is checked against one boundary

Inside the DeepWatch workspace, two properties are described that the engine alone does not give you.

The first is that every tool call leaves a receipt naming what it touched. That is a different artefact from a log line. A log says a call happened; a receipt says which file, which frame, which transcript, which contract. Combined with the verdict attached to results, it means a claim can be walked back to the specific artefact that backs it.

The second is a workspace boundary. Every path a tool declares is checked against one boundary, so a tool cannot quietly write outside it. This matters more here than in most tools because the toolset includes a shell and filesystem access, and an agent that can run shell commands in a directory it was not given will find its way there. Checking declared paths is not a sandbox, and the project does not claim it is, but it does close the quiet case where a tool writes somewhere nobody reviewed.

Results carry a Core verdict that you can open, and the Library keeps them after a restart. Persistence is what makes the Compare view possible: putting two runs of the same contract side by side and showing where their verdicts diverged requires that the earlier run still exist, which means a workspace that forgets its history cannot answer the only question Compare is designed for.

Taken with the four-verdict scheme, the shape is consistent. The engine produces evidence, the workspace records what was touched, and a separate process decides whether the claim holds.

Python 3.11 to 3.13, beta status, and about 600 MB of wheels in a container

The packaging metadata is precise about what is supported. Python 3.11, 3.12, and 3.13, with 3.11 as the floor, and those are the versions CI runs and the classifiers list. Node is declared as `^22.19 || >=24` in the CLI's engines field. Development status is beta.

The keyword list in the project metadata is worth a second look because it documents a decision. The file comment says the entries are what somebody would type looking for this rather than a summary of the readme, and notes that the previous seven named the ingredients, ffmpeg and yt-dlp, rather than the job. Someone has thought about how the package is found.

The container image is where the real cost shows. The base is a slim Python image with ffmpeg and certificates installed, because ffmpeg is the one dependency the doctor cannot bootstrap inside a slim image without a package manager. Dependencies resolve from the lockfile in their own layer, which means editing the source does not invalidate a large install. The stated size is around 600 MB of wheels, and the image comment says the point is to avoid putting that on your own machine.

The volume argument is the important line. The persistent index is the product, and without a mounted volume every run re-downloads and re-transcribes. That is the whole architecture in one sentence: an index you keep is worth keeping, and a container that forgets it every start is a container that costs you the same work twice.

Releases are tagged separately for the two products, with core and workspace tags cut on the same day in September 2026, and the last push to the repository was on 2026-09-14.

Editorial conclusion

watch-skill fits a team whose agents act on video or screen recordings and then have to prove what happened, since the timestamped citations and the separate verifier are the two things a transcript summary cannot give you. It does not fit anyone who wants a turnkey install, because the default package deliberately omits the ability to extract a frame and the browser tier is not in the container image. Before you install, run `watch-skill doctor` and read what it reports rather than assuming a green install works, then check the per-client support document for your agent, since the project publishes how far each of the 25-plus supported clients is actually verified.

Frequently asked questions

What does a skill do?

In this project a skill is a capability an agent calls rather than a prompt it reads. Watch Skill is packaged for MCP, a CLI, and a REST API, and its skills can be installed into 25-plus agent clients at once with `npx skills add oxbshw/watch-skill -g`.

What is the Claude Code skill for watching videos?

It is Watch Skill, which indexes a video or audio source into frames, transcripts, and OCR text with absolute timestamps, then answers questions about it while citing the moment you can open. Claude Code is one of the supported MCP clients, and the repository publishes a per-client document describing how far each is verified.

Why does watch-skill stop with perceive.missing_dependency?

A bare `pip install watch-skill` gives you the CLI, the verifier, and the Bridge, but it cannot extract a frame. Install the `standard` extra, and `watch-skill doctor` names the exact command for whatever is missing.

How does watch-skill verify that work actually succeeded?

It evaluates a frozen contract in a separate process and returns one of four verdicts: VERIFIED, FAILED, UNVERIFIED, or INCONCLUSIVE. Contracts cover file digests, JSON values, SQL results, HTTP responses, and DOM state, and the verdict does not come from a language model.

Does the watch-skill Docker image include the browser loop?

No. The Playwright package is installed but its browser is not, because Chromium plus system libraries roughly doubles the image. Everything except the browser loop works as-is, and `doctor` reports it. The image comment shows how to extend the image to add Chromium.

Official sources

  1. License: MIT
  2. oxbshw/watch-skill on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/oxbshw-watch-skill.svg)](https://hysenlabs.com/projects/oxbshw-watch-skill)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/oxbshw-watch-skill.svg)](https://hysenlabs.com/projects/oxbshw-watch-skill)

Was this useful?