# 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.

Canonical URL: https://ohrouter.com/docs

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