Capture (agent screenshots and screen recordings, by id)

What it is

Capture is the agent-facing half of Omniscio's screen capture: a script, a job or an agent asks the app to grab the screen or record it, then reads the result back by id. It has no screen of its own — a family of routes on the local control server rather than a panel.

It is separate from the human Screen Recorder (the recorder, editor and library a person uses directly), but the two meet in one place: a capture an agent takes lands in the same library as one the user made by hand. Every capture — a snip (a still screenshot) or a recording (a screen video with a duration, transcript and marked moments) — is addressed by an id, the handle every read-back, share, caption and AI route takes.

Where to find it

For a person, there is no screen. Capture is the local control server every Omniscio install runs at 127.0.0.1:19519, reached by a script or an agent.

Because it grabs the user's screen it is privacy-sensitive and ships OFF, behind the Settings → Optional Features → "Agent Screen Capture" switch; until it is on, the capture-creating and AI routes refuse with 403 { disabled: true }. Captures appear in the Screen Recorder library beside your own, and for an agent the surface is documented in the bundled omniscio-control skill's capture file.

How it behaves

Every route is bearer-authenticated and answers JSON.

Taking a capture. POST /capture/screenshot grabs the whole desktop (or a region) and answers 201 with the new capture's safe metadata. POST /capture/recording/start begins a recording and /capture/recording/stop stops the live one; it transcodes asynchronously, so a stop reports processing — poll the capture by id until ready. GET /capture/state and /capture/recordings report live state and list the library.

Reading a capture back. GET /capture/:id returns one capture's safe, path-scoped metadata by id: type, status, transcript, AI title / TL;DR / chapters, duration and share token. It never takes a caller path; the paths it returns are validated to live under the recordings folder (so a tampered row cannot coax out an arbitrary file), and video bytes are never streamed. Unknown or deleted id → 404.

Editing and captions. PATCH /capture/recordings/:id renames and/or moves a recording between folders. PUT /capture/:id/transcript saves edited caption segments; POST /capture/:id/captions starts a local Whisper job — neither spends paid AI, and captions answer processing at once (poll the capture). POST /capture/:id/crop and /capture/:id/frame cut a still from a finished recording and mint it into the calling conversation as a ready-to-paste image, so an agent can show the exact instant it means.

Sharing. POST /capture/:id/share publishes a live share link (default expiry seven days); /capture/:id/revoke-share stops sharing — neither spends AI money. A fresh recording's share may wait up to ~90 seconds for captions rather than refusing, so a record-then-share call still returns a link.

Paid AI — approval-gated. POST /capture/:id/suggest-title (auto-title a snip) and /capture/:id/summarize (AI title, TL;DR, chapters from the transcript) cost money: each enqueues an approval row quoting the rough cost, and the paid call fires only after approval. Auto-title refuses a video (409).

The box-select overlay. POST /capture/box-overlay opens the on-screen rubber-band drawing overlay; /capture/box-overlay/commit records the rectangle the person drew — the one pair needing a human at the machine. Committing with no overlay open is a 409.

Library housekeeping. Folders are created and soft-deleted (reversibly); deleting a recording or running the bulk /capture/retention/cleanup is approval-gated because it erases on-disk media, irreversibly (/capture/retention/preview shows what a cleanup would remove). Most routes need the Screen Recorder feature on; Screen Capture Projects — in-development — add /capture/projects….

Two limits: captures ride their own dedicated rate bucket (over it → 429); and a window on the sensitive-window deny-list refuses a capture with 409 { sensitiveWindowOpen: true } rather than grabbing it, failing closed if the deny-list is set but the windows cannot be read.

For agents

• Turn it on first. The kill-switch (agentScreenCaptureEnabled, Settings → Optional Features → "Agent Screen Capture") defaults off; the capture-creating and AI routes answer 403 { disabled: true } until it is on. Reading by id is the deliberate exception — GET /capture/:id works with capture off, so a user can review their library.
• The bundled omniscio-control skill is your map — its capture file carries the exact bodies and codes. Some routes are global-token only: acting on a capture or folder by id (rename, revoke-share, save-transcript, restore) needs the global CLI token, since the library has no per-session owner.
• Never open a review conversation on your own initiative. POST /capture/:id/send-to-agent with a projectId spawns a real, paid Claude session; use sessionId to deliver into a running session. Pass exactly one.
• The paid-AI calls need approval. suggest-title and summarize enqueue an approval row by default (the "Screen-capture AI" family); the paid call runs only after approval, and a client request id keeps a retry idempotent.

Related

• Screen Recorder — the human recorder and editor.
• Screen Recorder, part 2 — more on-screen behaviour.
• Screenshot Snip Tool — the person's own snip tool.
• Record for Agent — spoken recordings sent to an agent.
• Omniscio Control — the skill that drives this surface.
• CLI Control — the control server itself.
• Agent Tools — the rest an agent session can reach.