PennyRouter CLI

Official local installer for PennyRouter coding-agent integrations.

PennyRouter is a model gateway for coding tools. This CLI handles the local setup work that agents should not do by hand: browser authorization, API-key handoff, config edits, backups, status checks, and uninstall metadata.

Usage

npx pennyrouter install
npx pennyrouter install --make-default
npx pennyrouter update
npx pennyrouter auth anthropic
npx pennyrouter install --harness claude-code,cline,opencode,codex,windsurf,zed,codegpt,aider
npx pennyrouter disable
npx pennyrouter enable
npx pennyrouter uninstall
npx pennyrouter status

Installation opens a browser and requires login to the PennyRouter account that should own the new machine key. CLI installs no longer create anonymous ghost accounts.

With no --harness flag, the interactive installer shows Claude Code and Codex. Detected tools start checked. The additional legacy integrations remain available through an explicit --harness <id> selection or --all.

When Claude Code is selected, the installer offers Claude subscription authorization. If it is declined or unavailable, installation requires an Anthropic API key or OpenRouter key. Codex uses an existing ChatGPT login; without one, installation requires an OpenAI API key or OpenRouter key. PennyRouter-funded provider keys are never an installed-harness fallback.

Explicit Penny Commands

On macOS and Linux, a normal install adds a small penny launcher under ~/.local/bin. On Windows it installs penny.cmd under %LOCALAPPDATA%\\PennyRouter\\bin and adds that directory to the user PATH:

penny claude
penny codex

Arguments are passed through to the native harness, so commands such as penny claude --resume and penny codex resume --last work normally. By default, bare claude and codex remain completely native; their normal configuration files are not redirected. Choose the installer's "make PennyRouter the default" option, or pass --make-default, to retain the original global routing behavior.

Existing PennyRouter installs preserve their current bare-command behavior during upgrade unless the user explicitly changes it. Close running Claude Code or Codex sessions only when adding or removing global bare-command routing. A Penny-only install does not require closing native sessions.

The launcher uses a private config, a Claude settings overlay, and a secret-free Codex profile. The installer adds one marked PATH block to zsh or bash startup files on macOS/Linux, or a single user-PATH entry on Windows, when needed; --no-path-update skips that edit. Open a new terminal after a PATH update.

In Claude Code sessions launched with penny claude, /penny help is an alias for the existing @penny help syntax. Both forms remain supported. Codex continues to use @penny because Codex does not currently expose equivalent project-independent custom slash commands.

When Codex is already signed in with ChatGPT, the installer preserves that Codex-managed login and configures PennyRouter as an OpenAI-authenticated Responses proxy. Codex continues to own and refresh the OpenAI credentials; PennyRouter stores only its existing pr- account key in the managed provider block. API-key Codex installs use the user's encrypted OpenAI or OpenRouter key.

To point Codex directly at a PennyRouter gateway running on localhost port 8400:

npx pennyrouter@latest install --harness codex --local

Restart Codex after installation. Without --local, browser authorization supplies the normal hosted gateway URL.

Before configuring Claude Code, the installer sends a small compatibility request exercising the modern beta/context-management request shape. If that check fails, Claude routing is not enabled; the gateway must be redeployed or fixed before retrying. This check is about PennyRouter's gateway compatibility, not a demand that the user upgrade a Claude Code version that already emits a supported request shape.

Updating

To pick up a new CLI version without repeating the install interview:

npx pennyrouter update
npx pennyrouter update --dry-run
npx pennyrouter update --harness claude-code

update refreshes only the files generated from the CLI's own constants: the managed penny runtime and launcher, the /penny Claude skill, the Claude settings overlay and statusline, the Codex provider profile, and the model labels and context-window settings in managed tool configs. Older installs are migrated forward, so retired model labels are replaced with the current ones.

It never touches credentials and never re-runs browser authorization. Upstream provider tokens (Claude subscription, Anthropic, OpenAI, OpenRouter) are held encrypted at the gateway, and the existing pr- account key and gateway URL are read back from the local config, so the command is non-interactive and prompts for nothing.

Per-tool choices are preserved rather than re-asked. Bare-command routing is read from the uninstall manifest, so a Penny-only install keeps bare claude and codex fully native and an install that opted into global routing keeps it. Subscription auth mode is likewise carried forward. Use install instead when the intent is to change those choices.

Because the managed tool config is rewritten only for tools whose bare command already routes through PennyRouter, a Penny-only install leaves files such as ~/.claude/settings.json untouched and needs no session shutdown. Updating a tool that owns global routing requires closing its running sessions, or passing --allow-running-harnesses. Unrelated keys and user settings inside managed config files are preserved, and re-running update is idempotent.

Restart Claude Code or Codex afterwards to pick up the refreshed configuration.

Supported Tools

• Claude Code
• Cline (manual setup instructions; no VS Code settings mutation)
• Codex
• opencode
• Windsurf
• Zed
• JetBrains CodeGPT (manual setup instructions; no XML mutation)
• Aider

Penny Models

Tools that expose a model picker (e.g. Claude Code /model) get four curated choices. The three named-model choices PIN the trunk to that exact model — you pick the model, PennyRouter still cuts the bill via its side machinery (cache/compaction/swallowed background calls) without switching the model you chose. "Penny Custom" is the dynamic option: PennyRouter cost-routes each turn.

• Opus 5 (PennyRouter): pins anthropic/claude-opus-5
• Sonnet 5 (PennyRouter): pins anthropic/claude-sonnet-5
• Haiku 4.5 (PennyRouter): pins anthropic/claude-haiku-4-5-20251001
• Fable 5 (PennyRouter): pins anthropic/claude-fable-5
• Penny Custom: pennyrouter/auto — dynamic routing on the bundle/profile saved in the user's account

Claude Subscription Auth

When installing PennyRouter for Claude Code, the interactive installer offers to route Anthropic-native Claude turns through the user's own Claude subscription token. To force this in non-interactive installs:

npx pennyrouter install --harness claude-code --anthropic-auth --token <token>
npx pennyrouter install --harness claude-code --anthropic-api-key <key>
npx pennyrouter install --harness codex --openai-api-key <key>
npx pennyrouter install --openrouter-api-key <key>

If Claude Code is already logged in to a Claude subscription, use Claude Code's token setup flow:

claude setup-token
ANTHROPIC_AUTH_TOKEN=<token> npx pennyrouter auth anthropic

Other token sources are supported:

npx pennyrouter auth anthropic --token <token>
npx pennyrouter auth anthropic --token-command '<command that prints the token>'

If the separate Anthropic ant CLI is installed and logged in, PennyRouter can use it as a convenience fallback:

ant auth login
npx pennyrouter auth anthropic

The command stores the Anthropic token encrypted at the gateway. Claude Code keeps only the PennyRouter pr- bearer in its settings; the gateway retrieves and forwards the stored token with the required OAuth beta header and does not deduct PennyRouter credit for successfully served Anthropic-subscription calls.

On a transient subscription 429/529, the gateway retries the same subscription once. If it still fails, it can fall back only to credentials owned by that user: Anthropic API then OpenRouter for Claude, or OpenAI API then OpenRouter for Codex. If no such credential is configured, the provider error is returned; PennyRouter never changes the payer to itself.

PennyRouter also sets disableClaudeAiConnectors: true while its custom gateway is installed. Claude Code cannot load claude.ai organization connectors when gateway authentication takes precedence, and otherwise displays a persistent warning about that state. Making the disablement explicit suppresses the warning; locally configured MCP servers are unaffected. Reinstall keeps the original user value, and disable or uninstall restores it unless the user changed it later.

If the stored token expires during a long-running session, refresh the token source and rerun npx pennyrouter auth anthropic.

Agent Flow

Users can ask a coding agent to follow:

https://pennyrouter.com/install

That machine-readable page tells the agent to invoke this CLI instead of editing config files directly.

What It Changes

The CLI installs its managed launcher under ~/.local, writes only selected local tool configuration or per-command overlay files, saves backups under the local PennyRouter state directory, and records an uninstall manifest.

disable temporarily removes PennyRouter from selected tools while retaining a local PennyRouter-managed snapshot for enable.

update rewrites those same managed files for the installed version without re-authorizing, and without changing bare-command routing or stored credentials.

It does not delete PennyRouter accounts, credits, or remote API keys.

License

MIT