Documentation · Reference

CLI & JSON-RPC Reference

Every oh-router subcommand supports --json for structured output and communicates with ohd over ~/.local/state/oh/ohd/ohd.sock using newline-delimited JSON-RPC.

Global flags and environment variables

Flag / VariableDefaultDescription
--jsonfalseEmit pretty-printed JSON on stdout (errors emit {"ok":false,"error":...}).
--state-dir <DIR> / OH_STATE_DIR~/.local/state/oh/ohdDirectory holding ohd.sock, events.sock, bridge.token, and holders/.
--socket <PATH> / OH_CONTROL_SOCKET<state-dir>/ohd.sockControl Unix domain socket (0600).
--event-socket <PATH> / OH_EVENT_SOCKET<state-dir>/events.sockHook and statusLine event Unix domain socket (0600).
--config-dir <DIR> / OH_ROUTER_CONFIG_DIR~/.config/oh-routerConfiguration directory containing config.json and plugins/.

oh-router subcommands

CommandKey Flags & ArgumentsSummary
oh-router version--json, -V, --versionPrint CLI and daemon protocol version.
oh-router daemon <subcmd>start [--http-port <PORT>], stop, status, setup-hooks [--claude-dir <DIR>] [--passthrough <CMD>] [--write]Start, stop, or inspect ohd and configure Claude Code hooks.
oh-router spawn [PROMPT...]--kind <claude|codex|shell>, --tier <opus|sol|fable|astra>, --class <standard|frontier>, --effort <low|medium|high|max>, --plugin-builder, --headless, --review, --require <CAP>, --profile <ID>, --device <ID>, --project <NAME>, --workspace <NAME>, --cwd <DIR>, --title <TEXT>, --request-key <KEY>Spawn a routed coding-agent or shell session.
oh-router claude [PROMPT...]Same routing flags as spawn with kind fixed to claudeSpawn a Claude Code session (Opus or Fable).
oh-router codex [PROMPT...]Same routing flags as spawn with kind fixed to codexSpawn a Codex session (Sol or Astra).
oh-router ps--project <NAME>, --jsonList active and recent local plus paired remote sessions.
oh-router inspect <ID>--jsonInspect session state, turn history, dialog details, and VT screen lines.
oh-router steer <ID> <PROMPT...>--mode <auto|now|queue|interrupt>Send or queue a prompt through the 2D VT screen guard.
oh-router switch <ID>--tier <opus|sol|fable|astra>, --class <standard|frontier>, --effort <low|medium|high|max>, --profile <ID>, --prompt <NOTE>Stage recent context and continue the session on another tier or provider.
oh-router action <ID> <ACT>approve, deny, trust_folder, ctrl_c, stopApply a dialog action or stop a session.
oh-router queue <subcmd> <ID>list, add <PROMPT...>, remove <PROMPT_ID>, move <PROMPT_ID> <INDEX>, clear, flushManage per-session queued prompts.
oh-router profiles <subcmd>list, add --provider <claude|codex> --id <ID> [--label <LBL>], login [--no-open], probe, redeem-resetManage workspace directories and isolated Chrome OAuth sign-in.
oh-router policy <subcmd>get, set [--interactive-provider <P>] [--headless-provider <P>] [--cross-family-review <BOOL>] [--model-fallback <BOOL>] [--cross-provider-fallback <BOOL>] [--auto-folder-trust <BOOL>] [--codex-earned-resets <BOOL>] [--pin <proj=tier>], plugin-specInspect or update routing policy and view plugin spec.
oh-router devices <subcmd>list, pair-command, recipe [--name <N>] [--role <R>] [--quick] [--tunnel <T>] [--hostname <H>], ssh-config --host <A> --hostname <H> --user <U> [--write], add-remote --name <N> --tunnel-url <URL> --bearer-token <TOK>, toggle-stream <ID> <BOOL>, tunnel-start [--scope <stream_steer|admin>] [--rotate-token] [--port <P>] [--quick] [--tunnel <T>] [--hostname <H>] [--publish], tunnel-stopManage Cloudflare Tunnel pairing, loopback HTTP bridge, and SSH config.
oh-router board <subcmd>status, connect [--mode <local|vercel>] [--url <URL>] [--token <TOK>] [--channel <CH>], sync, subscribe <CH> [--auto-claim], tasks [--channel <CH>] [--state <S>], create-task [--channel <CH>] [--label k=v] [--need <ID>] <TEXT...>, claim [<ID_OR_CH>] [--ready], block <ID> <REASON...>, complete <ID> [--result <TEXT>], thread <ID>, reply <ID> <TEXT...>Coordinate @vercel/board channels, tasks, claims, and threads.
oh-router worker--once or --loop, --channel <CH>, --project <NAME>, --interval-ms <MS>Claim ready board tasks, spawn routed sessions, and renew leases.
oh-router hook [<Event>]--session <ID> (reads hook JSON from stdin)Forward Claude Code or Codex hook events to events.sock.
oh-router statusline-bridge--passthrough <CMD>, --session <ID>, --profile <ID>Parse Claude Code 2.1.327+ statusLine limits and forward to ohd.

ohd.sock & /v1/rpc JSON-RPC methods

Each request is a JSON object {"id":"req-1","method":"<name>","params":{...}} terminated by \n on ohd.sock or sent via POST /v1/rpc with Authorization: Bearer <token>. Responses return {"id":"req-1","ok":true,"result":{...}} or {"id":"req-1","ok":false,"error":{"code":"...","message":"..."}}.

Method GroupMethodsstream_steer Allowed
Daemon & Statedaemon.ping, state.snapshotYes (daemon.shutdown requires admin).
Sessionssession.list, session.inspect, session.spawn, session.steer, session.action, session.switch, session.input, session.resize, session.stop, session.pair_handoff, session.meta.updateYes for claude and codex sessions (kind: "shell" and custom argv require admin).
Prompt Queuequeue.list, queue.add, queue.remove, queue.move, queue.clear, queue.flushYes (non-shell sessions).
Profiles & Policyrouter.profiles.list, router.profiles.add, router.profiles.login, router.profiles.probe, router.profiles.redeem_reset, router.policy.get, router.policy.update, router.policy.plugin_specRead-only router.policy.get and router.policy.plugin_spec; mutations require admin.
Devices & Tunnelsdevices.list, devices.pair_command, devices.recipe, devices.ssh_config, devices.add_remote, devices.toggle_stream, devices.tunnel_start, devices.tunnel_stopdevices.list allowed; pairing and tunnel mutations require admin.
Board & Workerboard.status, board.connect, board.sync_now, board.channels.subscribe, board.tasks.list, board.tasks.create, board.tasks.claim_and_route, board.tasks.block, board.tasks.complete, board.threads.read, board.threads.reply, board.worker.tickRead/task coordination methods per scope policy; board.connect requires admin.