Quickstart

V1 Honesty: OffRouter routes delegated work. It does not replace your harness's primary model call.

Prerequisites

Node.js 22 or later
npm (shipped with Node)
One or more supported coding harnesses (Claude Code, Codex CLI, Gemini CLI, Grok Build)

Install

npm install -g offrouter-cli

Or build from source:

git clone https://github.com/pooriaarab/offrouter
cd offrouter
npm install
npm run build
npm link

After installation, offrouter and offrouter-mcp are on your PATH.

Initialize

offrouter init

Detects installed harnesses, checks readiness, and writes a commented starter config to ~/.offrouter/config.toml if none exists. It never overwrites an existing config. Use --dry-run to see the target path without writing, and --json for machine-readable output.

Configure Providers

Create ~/.offrouter/config.toml:

allowlisted_profiles = ["claude-personal"]
denied_profile_patterns = ["*-work"]

[policy]
subscription_first = true
allow_api_key_fallback = false

See the providers page for detailed configuration.

Install into a Profile

Dry-run first:

offrouter install claude --profile claude-personal --dry-run
offrouter doctor --profile claude-personal

Then install:

offrouter install claude --profile claude-personal

Same flow for Codex, Gemini, or Grok:

offrouter install codex --profile codex-personal
offrouter install gemini --profile gemini-personal
offrouter install grok --profile grok-personal

Start the MCP Server

offrouter mcp serve

Harnesses that have OffRouter installed start the MCP server automatically as part of their plugin or MCP configuration.

Explain a Route

offrouter route explain "explain this repo" --profile claude-personal

Runs local policy checks only. No provider is called.

Uninstall

offrouter uninstall claude --profile claude-personal --dry-run
offrouter uninstall claude --profile claude-personal