Hypervisor

Local macOS control surface for Claude Code, Codex, OpenCode, and Cursor sessions. Read-only adapters watch harness transcripts; owned sessions run in an isolated tmux -L hypervisor socket. Hypervisor is not an editor.

Prerequisites

• macOS
• tmux
• Rust toolchain (rustup)
• Node.js + npm (scripts use npm; do not rely on bun lockfiles)
• Harness CLIs resolvable from a zsh login shell: claude, codex, opencode (as needed)
• claude /login refreshed if you need live Claude Code control

Run

cp .env.example .env   # once — staging PostHog key for local builds
npm install
npm run tauri dev

src-tauri/build.rs loads the repo-root .env at compile time and bakes POSTHOG_PROJECT_KEY / POSTHOG_HOST into the binary (option_env!). Process env / CI secrets override .env. No key → telemetry is fully inert.

Analytics (PostHog)

Content-free feature counts only — schema in tasks/POSTHOG.md. Gated by Settings → analytics (default on, disclosed once at first launch).

Build	Project	Key source
tauri dev / local	hypervisor-staging	repo-root .env (gitignored)
Release DMG + hypervisor.sh	hypervisor	GitHub Actions secrets POSTHOG_PROJECT_KEY + POSTHOG_HOST

Site pageviews (cookie-less, persistence: 'memory', respects DNT):

cd site && npm install
POSTHOG_PROJECT_KEY=… POSTHOG_HOST=https://us.i.posthog.com npm run build

Headless checks

cargo run --bin hvscan          # one-shot session scan
cargo run --bin hvscan -- --watch

Tests

Safe by default (no adopt / live prompt / harness spawn):

cargo test --lib

Live-fire tests (adopt real sessions, prompt opencode, spawn harness CLIs):

HV_LIVE=1 cargo test --lib -- --ignored

Adapter parity tripwire:

python3 spike/compare.py

Typecheck the frontend:

bunx tsc --noEmit
# or: npx tsc --noEmit