PennyRouterAI PROXY

Docs

Install it once.Then carry on.

Setup is one command. After that you use Claude Code and Codex exactly the way you already do — PennyRouter works on the request in transit. The extras, when you want them, all start with @penny.

Install

Pick whichever route suits you — they all end in the same place. The installer opens your browser once to authorize the machine, writes your harness configs, and keeps a backup of everything it touched.

Download for macOSUniversal

Already have an account and just want a key on this machine? Run npx pennyrouter install --existing-account. Prefer to hand the job to your agent? Tell it please install the proxy from pennyrouter.com/install — that page is written for agents to follow.

Using it

There is no PennyRouter workflow to learn. This is the whole thing.

Restart your coding agent

The installer changes config your harness reads at startup, so Claude Code or Codex needs a fresh launch to pick it up. It prints this reminder when it finishes.

Work exactly as you did yesterday

Run claude or codex, open the same repos, use the same prompts, skills, and MCP servers. Requests now travel through the gateway on their way to the model and come back the same. Nothing about how you drive the tool changes.

Check on it whenever you're curious

Ask @penny status in any chat for balance and savings to date, or @penny savings for what the session in front of you cost versus what it would have cost natively.

@penny savings

The warm timer

If you installed the statusline, you get a small readout at the bottom of your terminal. It is the most useful number PennyRouter shows you.

·warm4:31

Your provider keeps a cached copy of the conversation so far. While that cache is live, each new turn only pays to read it. Once it expires, the next turn has to write the whole conversation again — and writing costs substantially more than reading.

The timer counts down to that expiry. It is not a deadline, and nothing breaks when it runs out. It just means: if you're planning to keep going in this session, picking it back up while it still says warm is cheaper than picking it up cold. PennyRouter brings the cold case down too — it simply can't make it free.

Long break coming? @penny save checkpoints the session first, so it resumes cheaply later instead of paying the full cold write.

@penny commands

Optional, but handy. Start any message with @penny and PennyRouter answers instead of your model — no tokens spent, no integration, works in Claude Code, Codex, and anything else that talks to the gateway.

Save & resume

@penny save

Park a session and come back cheap

Switch models

@penny prep handoff

Change model without a cold re-read

Move harness

@penny send session to

Hand this session to Claude or Codex

Bring one in

@penny import session

Pull in a shared AI conversation

Get a second opinion

@penny consult

One round from a stronger model

Ask a human

@penny ask @name

A teammate answers, you keep working

Remember

@penny set project

Carry context across tools

See the money

@penny savings

This session vs the baseline model

The everyday commands

This is the same list @penny help prints in your chat, in the same order.

@penny help

Print this list inside whatever chat you're in.

@penny import session <share-link>

Bring a shared Claude, ChatGPT, Gemini, or Perplexity conversation in as a fresh thread — or as a resumable native session when you're already mid-conversation.

@penny import session https://claude.ai/share/a1b2c3

@penny send session to <claude|codex>

Hand this session to the other harness. Penny rewrites it into that tool's native format so you can pick up where you left off.

@penny send session to codex

@penny save

Checkpoint the session so it comes back instantly and cheaply later. Generation runs in the background — you can walk away the moment you send it.

Penny repliesSaving your session in the background — you're free to go. When you return, this session will resume instantly and at low cost.

@penny prep handoff

Prepare the session before you change models. The next model starts from a compact briefing instead of re-reading the whole conversation cold.

Penny repliesHandoff ready — you can switch models now.

Unlike save, this one makes you wait a few seconds. That's the point: the briefing has to exist before you switch.

@penny set project <name>

Attach this session to a named project. Sessions you tag with the same name share what was decided, across every harness you use.

@penny set project penny-router

@penny consult <question>

Escalate one question to a stronger model without leaving your session. Penny briefs it on the conversation, you get one strong answer, and you're back on your normal model.

@penny consult is this migration safe to run twice?

@penny ask @name <question>

Ask a teammate instead of a model. They get a link and answer from their own tool — no account needed — and the reply lands back in your session. You keep working meanwhile.

@penny ask @jon should this ship before the deploy?

@penny team

Your teams and the handles you can ask.

@penny login

Get a one-time link to attach an email or sign in, so your account and credit survive a new machine.

@penny savings

What this session cost through PennyRouter against what it would have cost natively — context size, per-turn cost, and the difference.

Account & spend

@penny status

Bundle, profile, balance, and lifetime savings in one line.

Penny repliesBundle: Anthropic · Profile: standard · Balance: $4.25 · Saved so far: $12.43

@penny usage

Today's spend and savings, last hour's burn rate, your top models, and roughly how long your credit lasts at the current pace.

@penny whoami

Whether you're signed in or still on an anonymous trial account.

@penny buy

A link to top up your credit.

Bundles & routing

Which models Penny is allowed to route you through, and how aggressively.

@penny list bundles

Every bundle available and what's in it.

@penny switch to <bundle>

Route future requests through a different provider bundle.

@penny switch to anthropic

@penny profile <standard|high|premium>

How readily Penny escalates. Standard keeps you on the cheapest capable model; premium leans on frontier models at roughly 3x the per-token cost.

@penny profile premium

Advanced

Mostly for debugging and comparing against a native baseline.

@penny bypass on

Relay this session to Anthropic byte-for-byte — no compaction, no rewrites, no injected notices, no savings.

Flipping bypass changes the cached prefix, so the next turn is a full-price cold cache write in either direction. For a clean baseline, flip it and then start a fresh session.

@penny bypass off

Back to the managed pipeline.

@penny bypass status

Which mode this session is in.

@penny tips on / off

Turn the occasional in-band PennyRouter tip at the top of a reply on or off.

You can also just ask

Anything that isn't a command above goes to a constrained Q&A that answers from PennyRouter's own knowledge base and your account facts.

@penny how does PennyRouter save me money?@penny what is prompt caching?@penny can I use my Claude Pro subscription?

Uninstall

One command, and it reverses only what it added.

See what's configured

Lists every harness PennyRouter currently owns config for, so you can decide what to remove.

npx pennyrouter status

Remove it

The installer wrote a manifest recording every file it touched and the state to restore. Uninstall replays that manifest, so your other providers and settings are left exactly as they were. Add --all to remove every harness, or --harness claude-code,codex to pick.

npx pennyrouter uninstall

Restart your coding agent

Same reason as install — the config is read at startup. Claude Code and Codex go back to talking to their providers directly, with no trace left behind.

Your account and any remaining credit stay put — uninstalling the local proxy doesn't close anything. Your agent can handle this too: point it at pennyrouter.com/uninstall.