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.
| Binary | Crate | Responsibility |
|---|---|---|
oh-router | crates/oh-cli | Command-line client for humans and coding agents. Supports --json across every subcommand and auto-starts ohd on demand. |
ohd | crates/ohd | Background 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-holder | crates/oh-holder | Detached 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.
| Crate | Role |
|---|---|
oh-protocol | Canonical snake_case snapshots, JSON-RPC 2.0 envelopes, TokenScope rules, and automatic secret redaction. |
oh-vt | 2D ECMA-48 / VT100 cell grid, SGR attribute parser, screen_epoch counter, and TUI dialog recognizer. |
oh-router-core | Zero-I/O routing state machine across Opus, Sol, Fable, and Astra, effort selector, and VT send guard. |
oh-providers | Workspace profile directories, flock lane leases, statusLine and rate-limit parsers, and ProcessPolicyPlugin. |
oh-board | Native @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-vtparses SGR cells, tracksscreen_epoch, and blocks spending dialogs. - Vercel Board Worker: connect
@vercel/board, manage tasks and threads, and runoh-router worker. - Cloudflare Tunnels: pair remote machines over HTTPS with
stream_steerBearer tokens and SSHProxyCommand. - PolicyAdvisor Plugins: write deterministic stdio JSONL plugins with SHA-256 digest verification.
- CLI & JSON-RPC Reference: every
oh-routersubcommand, flag, andohd.sockRPC method.