Observe and capture with Voidscape

This playbook composes a browser-capable harness, optional capture tooling, and Voidscape without turning Voidscape into a browser controller or ambient recorder.

Status: shipped documentation and observe CLI

Canonical sources: harness support, browser/CLI matrix, and authenticated sources

Responsibility boundary#

user-approved harness -> browse, click, screenshot, or save a recording
optional capture tool -> produce a chosen local image or clip
Voidscape -> inspect -> preview -> read -> manifest + citable evidence

The harness owns live interaction. The operating system owns screen-recording permission. An optional companion owns capture history. Voidscape starts with a URL or local file and keeps its normal per-job cloud and model-download gates.

Voidscape never reads browser credentials, cookies, storage, or secrets. It never exports browser state. Browser site approval does not authorize CLI authentication, cloud spend, or model downloads.

One-time setup#

Codex or ChatGPT#

1. Follow the official Codex Chrome extension setup and grant only the sites needed for the task.
2. Use the harness's current permission UI to retain site access only where appropriate. Permission persistence and scope are controlled by the harness/browser, not Voidscape.
3. For mobile continuation, follow Codex remote connections. The paired host must remain available and must be able to reach the local files and CLI.

Claude#

1. Follow Claude Code with Chrome and grant the required site access in Claude/Chrome.
2. Follow Claude Code Remote Control when continuing the running local session from another device.
3. Treat the complete Claude-to-Voidscape composition as unverified until reproduced on the target host; vendor documentation establishes the harness features, not this integration.

Host capture folder and permissions#

1. Choose a dedicated local folder for task captures and keep private material out of the repo.
2. Grant OS screen-recording permission only to the harness or capture tool that needs it.
3. Test one harmless screenshot before a real task.
4. Use a new empty Voidscape evidence workdir for each read.

Pre-approving a narrow domain list can reduce repeated harness prompts. It does not promise zero prompts: new sites, sensitive actions, OS recording, cloud transfer, and model downloads remain separate decisions.

Recipe 1 — browser task to screenshot or short clip#

1. In a permitted tab, ask the harness to complete the browsing task.
2. Ask the harness to expose the permitted state, then use the installed observe companion (or a separately approved capture tool) to save an explicit screenshot or short silent clip. The observe companion captures the selected desktop/display; it does not navigate or select a tab.
3. For a screenshot:

   python skill/scripts/observe.py screenshot --out "C:\path\capture.png"
   voidscape inspect "C:\path\capture.png"
   voidscape preview "C:\path\capture.png"
   voidscape read "C:\path\capture.png" --workdir "C:\path\evidence-image"

1. For a clip:

   python skill/scripts/observe.py clip --seconds 15 --out "C:\path\capture.mp4"
   voidscape inspect "C:\path\capture.mp4"
   voidscape preview "C:\path\capture.mp4" --tier both
   voidscape read "C:\path\capture.mp4" --tier both --workdir "C:\path\evidence-clip"

1. Stop for any previewed approval. Read the resulting bundle with [image N] or [MM:SS] citations.

Run python skill/scripts/observe.py doctor for capture readiness and python skill/scripts/observe.py status --json for optional screenpipe health. Capture never calls read, forwards approval flags, records audio, overwrites an existing path, or starts a service.

Recipe 2 — public video URL without browser cookies#

Copy the public URL from a permitted page and pass it directly to the guided CLI:

voidscape inspect "https://example.com/public-video"
voidscape preview "https://example.com/public-video" --tier both
voidscape read "https://example.com/public-video" --tier both --workdir evidence-public

Start anonymously. A page being visible in Chrome does not prove the media endpoint is public. If the CLI returns an authentication/platform error, surface it rather than trying to extract browser state.

Recipe 3 — account-scoped media with an explicit cookie file#

Use this only for media the user is permitted to access.

1. The user separately creates a site-scoped Netscape cookies.txt outside the repository.
2. The user sets READ_VIDEO_YTDLP_COOKIES to that file path on the host.
3. Run inspect again and follow the normal preview and approval gates.
4. Delete or rotate the exported file according to the user's security practice.

The harness never exports the file, reads its contents, or copies it into Voidscape. Voidscape does not discover browser profiles or storage; it passes only the user-configured file path to the media tool. Never print the file or include it in evidence.

Optional screenpipe companion#

screenpipe is a separately installed, source-available desktop-memory product. It is not a Voidscape dependency and is not started or configured by the Voidscape installer.

The upstream README quickstart currently uses:

npx screenpipe record
npx screenpipe setup
claude mcp add screenpipe -- npx -y screenpipe-mcp@latest

The current upstream CLI skill also documents a screenpipe service install workflow through its CLI launcher. These are screenpipe-owned installation and service-management paths, not Voidscape commands. Follow the current screenpipe documentation and pin a release when reproducibility matters; upstream warns that main moves quickly.

screenpipe currently documents a localhost REST API (default port 3030), MCP access, local screen history, and a video-export pipe. A user or harness may query recent permitted frames and export a chosen clip, then pass that local file to Voidscape. The observe companion queries only normalized health from a loopback endpoint (or screenpipe status --json); it never queries capture history, MCP, raw SQL, or a screenpipe database.

Keep the service bound locally, apply screenpipe's current authentication and permission guidance, and never treat localhost as a sufficient trust boundary. Ambient retention, excluded apps, audio capture, cloud features, and deletion remain screenpipe/user responsibilities.

Permission boundary#

Failure handling#

• Host unavailable: reconnect the paired host; do not reroute silently to cloud execution.
• Capture path missing: confirm the actual local file before inspect.
• OS recording denied: report the missing permission; do not loop or install tools automatically.
• URL works in browser but not CLI: treat browser and CLI authentication as separate.
• screenpipe API/MCP unavailable: continue with a manual/harness capture or skip; screenpipe is optional.
• Preview requires approval: stop and present that specific decision.

Pattern sources#

• screenpipe: optional local capture/history, freshness, API, and export patterns.
• automated_browser devel: structured action and session-replay patterns only.

Voidscape does not adopt always-on recording as its core, an autonomous LLM browser loop, raw page uploads to a model, cookie scraping, or unattended action replay.