overcast

Video OSINT agent: senses + OSINT reach for any agent.

overcast gives an agent senses and recon and targeting reach, organized around an investigation case: a working directory with a local .overcast/ store where every result is kept. Point it at a corpus, 10 clips or 1,000, and it turns footage into cited evidence: speech and audio with listen, full video understanding with watch, on-screen text and objects with see, faces and cross-corpus person search with face, and named entities with index entities. Results persist as evidence-only case memory, so intelligence accumulates across sessions instead of vanishing between runs, and ask answers cite the exact record and timestamp.

Every subcommand is modular: each verb is a standalone CLI command that emits a portable JSON record, so you can run the whole pipeline as one agent or drop a single step into another recon/security workflow. overcast ships as a pi package, a standalone bun binary, and agent skills that drive the CLI from any harness. The brain LLM is BYO; the default perception backend is the Tinycloud Video Agent CLI. Every verb runs over one provider contract, so you can rebind any sense to another backend or your own script with no code changes.

📣 News

overcast is at DEF CON 34 Demo Labs — "Overcast: Video OSINT Agent. Point It at 100 Videos, Ask Anything", presented by Kevin Dela Rosa. Two sessions, both in LVCC L1, Exhibit Hall West 3 – 902 (Demo Labs Track 6):

Come see it run live, or read the abstract.

⚠️ Responsible use & security model

overcast is a dual-use tool. Its OSINT sources can reach personal information about real people (reverse-face and reverse-image search, skip-trace / people-search, phone, property, and license-plate lookups). Use it only for lawful purposes against targets you are authorized to investigate. The high-sensitivity sources are opt-in and never enabled by default, and each carries legal constraints (DPPA, not-an-FCRA-report, biometric-privacy law, third-party ToS). Read RESPONSIBLE_USE.md before you point it at anyone.

By design, overcast runs an agent with no sandbox or permission system (inherited from pi) over untrusted media and scraped web content, which are prompt-injection vectors. Run investigations in an environment you're willing to expose to the material you collect. See SECURITY.md for the full trust model and how to report a vulnerability.

Quickstart

npm i -g @kdrrr/overcast && overcast doctor     # install + preflight

# 1 — point a case at a target, sweep public sources, ask with citations
overcast case setup --name dock-incident \
  --target "white van at pier 9" --source web:"pier 9 dock incident" --yes
overcast scan --pull                            # enumerate sources → capture → sense each hit
overcast ask "every white van, with timestamps" # answer cites record.id + timestamp
overcast brief --export brief.html              # story-first analyst report

# 2 — or analyze a clip directly
overcast watch ./clip.mp4                        # full video understanding → a cited record
overcast listen ./clip.mp4                       # speech + audio-scene transcript
overcast face ./clip.mp4 --match ./suspect.jpg   # find this person across the clip, ranked

A case is just a directory with a .overcast/ store — switch cases with cd or --case <dir>. pi's per-directory sessions are the case history.

→ Full worked examples — person search, OSINT pulls, continuous monitoring, visual / audio / voice DBs, the control-room wall, detection crops, and more — live in the Field Manual (docs/field-manual.md).

Install

npm i -g @kdrrr/overcast          # the CLI + pi package  →  `overcast`
overcast doctor                 # preflight: pi, ffmpeg/ffprobe, Cloudglue, providers

npx @kdrrr/overcast doctor runs any verb without a global install; npm i -g @kdrrr/overcast@latest updates one. Or grab a standalone binary (no Node required) for your platform from the latest release — overcast-<os>-<arch>.tar.gz (ships its theme/ + examples/ sidecars) — or build it with npm run build:bun → dist/bin/overcast.

Prerequisites

• Node.js ≥ 22 (with npm) — to install and run overcast. The compiled bun binary bundles its own runtime, but npm i -g needs Node 22+.
• FFmpeg — ffmpeg + ffprobe on your PATH (the internal media toolkit for enhance, frame extraction, detection crops, and view). brew install ffmpeg · apt install ffmpeg (or point OVERCAST_FFMPEG / OVERCAST_FFPROBE at specific binaries).
• tinycloud CLI + CLOUDGLUE_API_KEY — the default watch / listen / face / index backend (Cloudglue). Needs ≥ 0.3.12 (single-call verbatim transcripts); face + index need ≥ 0.3.4, the opt-in image see provider ≥ 0.3.7. npm i -g @cloudglue/[email protected] or tinycloud update.

Optional, feature-gated backends — each reports cleanly (needs_credentials) when absent, so the rest of overcast is unaffected:

• yt-dlp on PATH — the youtube / dl sources and post-page fetches on tiktok / x / instagram / telegram.
• qmd — optional local semantic case search (npm install -g @tobilu/qmd); plain ask does not need it.
• ExifTool / c2patool — the exif (metadata + GPS) and verify (C2PA / Content Credentials) forensic senses. brew install exiftool c2patool.
• Playwright — browser capture for the screenshot verb and browser source. npm install --include=optional then npx playwright install chromium.
• uv-managed Python — local face / CLIP / CLAP / audio / voice DBs and the split enhance ops (scripts/visual-db-uv.sh).

overcast doctor verifies core prerequisites and reports optional backends when installed or configured. Full version nuances and env knobs → docs/configuration.md.

Use it from your agent

overcast drives any harness three ways — pick whichever fits:

Agent skills (Claude Code, Cursor, Codex, …) — install the bundled skills with the CLI, or pull them straight from this repo with the harness-agnostic skills installer:

overcast skills install --dest ~/.codex/skills # recommended for Codex/Cursor/other agents
overcast skills install                        # Claude Code default: copies into ~/.claude/skills
overcast skills install --harness claude-code  # explicit Claude Code target
npx skills add kdr/overcast                    # vercel-labs/skills; pulls skills from this repo

Shipped skills — overcast (the broad driver + reference/verbs.md man pages), overcast-init (one-time setup), overcast-skill-creator (author your own), and focused workflows:

Each is generated from src/skill-gen.ts (one source of truth). The CSI/crime-trope skills (lineup…crime-board) are exercised end-to-end against real media in test/e2e/live/cases/80–90; the visual-CoT localization skills (pinpoint…presence-window) in test/e2e/live/cases/18_grid.

Claude Code plugin (slash commands + skills as one package):

/plugin marketplace add kdr/overcast
/plugin install overcast@overcast

Interactive/headless overcast agent — both overcast and overcast -p "<task>" load the same system prompt and tool surface. The prompt steers the agent to start with zero-config ask, rebuild qmd before semantic queries, use ask --deep for configured semantic memory, and bind remote indexes with index attach instead of note bookkeeping. Case memory is evidence-only: setup/doctor/index/target/source/prebrief/read bookkeeping is excluded from ask and brief. See the Field Manual for the agent's memory model in depth.

VS Code extension

Overcast for VS Code (vscode/, extension id kdrrr.overcast) puts the situation room in your editor as a thin client of this CLI: right-click any media file for the senses (watch / listen / see / faces / EXIF / …), an activity-bar view with a command deck laid out along the intelligence cycle plus Investigation / Sources / Records / Runs trees, evidence artifacts (map, graph, wall, brief, situation) as editor tabs, and @overcast chat + #overcast* language-model tools when a chat provider is installed. Every action spawns overcast … --json; records land in the case and the sidebar follows the .overcast/ store live.

Install it from the VS Code Marketplace (search "Overcast", or ext install kdrrr.overcast), or install the overcast-<version>.vsix attached to the latest release (code --install-extension overcast-<version>.vsix, or "Install from VSIX…" in the Extensions view), or build it from source:

cd vscode && npm install && npm run build && npm run package
code --install-extension ../.dev/overcast-*.vsix

Live control room

overcast runs as a live operation, not just a batch tool:

• Man in the chair — remote-drive the running TUI session from your phone (/chair on tailnet, or launch with overcast --chair): a live assistant stream, steer / follow-up / ABORT prompts (typed or spoken via the browser's speech recognition), and a read-only case glance, over a token-authed localhost/tailnet HTTP+SSE bridge (pair with Tailscale or an SSH tunnel).
• Situation room — situation serves a self-updating monitoring page (wall tiles + reverse-chron scan/monitor feed + live GPS map + refreshing webcam/browser stills), auto-picked from the case's sources; /situation on runs the same page in-process, bound to the session.
• Reports — brief answers "what does the evidence say?" (story-first, short by default), case status is the mission board ("where is this case?"), and case records is the append-only audit log ("what exactly happened?"). The /debrief prompt drives the analyst loop over them.

Full setup, secure-origin voice, fallbacks, and the report anatomy → Field Manual.

Verbs

overcast is ~35 verbs across four groups; each is a standalone CLI command that emits a portable JSON record:

• Senses (media → records) — watch listen see face image audio voice cluster similar exif verify screenshot enhance reconstruct chronolocate
• Inspect (look at the evidence) — view crop grid wall situation map devices graph
• OSINT (search / capture / monitor) — scan capture monitor index archive target source note finding prebrief
• Read (synthesize the case) — ask brief case

Plus pi's base verbs (read write edit bash grep find ls).

Full per-verb reference + every built-in source ref → docs/verbs.md. The authoritative registry is overcast commands --json; overcast <verb> --help is a man page for any verb, and overcast --help shows the full surface + env vars.

Providers & configuration

Every verb runs over one provider contract, so you can rebind any sense to another backend — or your own script — with no code changes:

overcast provider setup apply --verb see --choice fal --yes     # e.g. fal.ai for `see`
overcast provider create myfeed --kind source                    # scaffold your own source
overcast provider install ./myfeed --yes                         # register it — no fork

Shipped providers carry a provider.json manifest and are scanned at runtime; bindings reference scripts as location-independent shipped: refs, so profiles survive the install moving. A source package makes a new scan/monitor type; a sense package a new --choice.

• Bind backends, profiles, findings tuning, local visual/audio/voice DBs, and the full environment-variable surface → docs/configuration.md
• Author your own provider (manifest schema, provider install) → docs/providers.md

Documentation

Authoritative, always-current: overcast commands --json (the verb registry), overcast <verb> --help (a man page), overcast doctor (what's installed).

Distribution

Three surfaces from one source of truth (src/registry/verbs.ts):

• pi package (@kdrrr/overcast) — tsup bundles dist/{bin,index,extension}.js; pi + ffmpeg/ffprobe stay external (pinned / runtime-resolved). A postinstall brands the pinned pi host as "overcast" without moving ~/.pi.
• standalone binary — bun build --compile → a single executable (+ a sidecar package.json for branding).
• agent skills + Claude Code plugin — skills generate renders skills/overcast/{SKILL.md, reference/verbs.md} from the registry; skills install --dest <dir> copies them into any agent skills directory, while bare skills install targets Claude Code.

Development

npm run build       # tsup (dev/library build)
npm run typecheck   # tsc --noEmit
npm test            # unit tests (offline; fixtures)
npm run test:e2e    # offline e2e (fixture providers, no creds)
npm run test:e2e:live  # live real-data e2e (builds the bun binary, sources .env)
E2E_VERBOSE=1 npm run test:e2e  # include exact commands + output snippets in report.md
npm run build:bun   # bun build --compile → dist/bin/overcast
npm run pack:check  # verify synced versions + fresh dist/bin/overcast.js before npm pack
overcast commands --json   # the authoritative verb registry
overcast doctor            # preflight

npm pack runs npm run pack:check first. Build with npm run build before packing; if the ignored dist/ tree is missing or stale, the pack fails with a message showing the version or command-registry drift.

Contributing & community

• CONTRIBUTING.md — dev setup, the architecture invariants, how to add a provider, and the PR checklist.
• RESPONSIBLE_USE.md — the dual-use / acceptable-use policy and per-source legal notes. Read this before using the OSINT sources.
• SECURITY.md — the trust model and how to report a vulnerability (privately, via GitHub Security Advisories).
• CODE_OF_CONDUCT.md — how we treat each other.
• SUPPORT.md — where to get help.
• Questions and ideas → Discussions; bugs and features → Issues.

License

Licensed under the Apache License 2.0. Built on top of pi. You are responsible for how you use this tool and for complying with all applicable laws and the terms of any third-party services you configure — see RESPONSIBLE_USE.md.

Credits

Created by Kevin Dela Rosa — co-founder & CTO of Cloudglue and creator of Tinycloud, the default perception backend here.