Documentation · Start here

Documentation

oh-router is a three-binary Rust workspace (oh-router, ohd, oh-holder) that supervises Claude Code and Codex sessions locally and across paired machines.

Three binaries, clear process boundaries

Every release archive and Homebrew bottle installs three compiled Rust binaries into the same directory (~/.local/bin or /opt/homebrew/bin). When oh-router or ohd is invoked through a symlink, sibling discovery checks both current_exe() and canonicalize() so bundled app helpers and package-manager symlinks resolve cleanly.

BinaryCrateResponsibility
oh-routercrates/oh-cliCommand-line client for humans and coding agents. Supports --json across every subcommand and auto-starts ohd on demand.
ohdcrates/ohdBackground supervisor listening on ~/.local/state/oh/ohd/ohd.sock (0600), reconciling holders, evaluating routing policy, and serving the opt-in 127.0.0.1 HTTP bridge.
oh-holdercrates/oh-holderDetached per-session PTY process (setsid) running portable-pty, VtScreen, and a private 0600 holder socket so live sessions survive ohd restarts.

Workspace architecture

The Rust workspace separates protocol types, terminal emulation, pure routing logic, provider integrations, and board coordination into focused libraries.

CrateRole
oh-protocolCanonical snake_case snapshots, JSON-RPC 2.0 envelopes, TokenScope rules, and automatic secret redaction.
oh-vt2D ECMA-48 / VT100 cell grid, SGR attribute parser, screen_epoch counter, and TUI dialog recognizer.
oh-router-coreZero-I/O routing state machine across Opus, Sol, Fable, and Astra, effort selector, and VT send guard.
oh-providersWorkspace profile directories, flock lane leases, statusLine and rate-limit parsers, and ProcessPolicyPlugin.
oh-boardNative @vercel/board@0.53.0 HTTP client (VbClient) and embedded local server (EmbeddedVbServer).

Guides and references

  • Quickstart: install the binaries, start ohd, configure Claude Code hooks, and spawn or steer sessions.
  • 2D VT Screen Guard: how oh-vt parses SGR cells, tracks screen_epoch, and blocks spending dialogs.
  • Vercel Board Worker: connect @vercel/board, manage tasks and threads, and run oh-router worker.
  • Cloudflare Tunnels: pair remote machines over HTTPS with stream_steer Bearer tokens and SSH ProxyCommand.
  • PolicyAdvisor Plugins: write deterministic stdio JSONL plugins with SHA-256 digest verification.
  • CLI & JSON-RPC Reference: every oh-router subcommand, flag, and ohd.sock RPC method.