claudeers.
// Developer Tools

Pygg

Run your coding agents on cheaper models without losing the answers. A local gateway for Claude Code, Codex and OpenCode that routes each request to a model…

// Developer Tools[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-gateway#anthropic#claude-code#codex#cost-tracking#developer-tools#llm-gateway#devtools◷ MIT$open-sourceupdated 1 day ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up Pygg (claude-plugin project) into my current project.
Found on https://claudeers.com/pygg
Repo: https://github.com/nambean/Pygg
Homepage/docs: http://inviv.vn
Detected install method: claude-plugin → /plugin install pygg@nambean/Pygg
Category: devtools. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)

⚠ Unverified / not recently updated — review before pasting a run-this config.

/plugin marketplace add nambean/Pygg
/plugin install pygg@nambean/Pygg
// or clone
git clone https://github.com/nambean/Pygg

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageRust

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Pygg — One Flow. Many Agents.

Run your coding agents on cheaper models without losing the answers.

Pygg is a local gateway that routes each request to a model you connected, and measures what it saved.
Our own first runs: 88% less per solved task on 12 small coding tasks, about 40% on a real repository.
A small sample: help benchmark it on your work.

https://github.com/user-attachments/assets/85708783-8be3-4292-955c-783cc066bbd1

A terminal installs the pygg command line from npm, checks that Pygg's gateway answers on 127.0.0.1:8741, sets up Claude Code and starts it through Pygg with the model auto; the gateway routes each request to free and cheap models, your plans, local models or opt-in web sessions

Pygg runs on your computer. Connect your providers once (API keys, coding plans, a local Ollama, even an AI website without an API), point Claude Code, Codex, OpenCode, an editor or an SDK at 127.0.0.1:8741, and choose the model auto. Each request goes to an eligible model you connected, free and cheap ones first where they qualify, within the limits you set; when a provider says no, the next one answers. Every attempt lands in a ledger with what it cost and where that figure came from.

Since the router sees every model you connected and what each one did on your own work, it can also be the brain: name the model pygg/brain and type a requirement, and Pygg has a planner split it into cards with a role each (plan, code, test, review), picks a model per card by rule from public benchmark facts and your own kept results, and shows the proposal in the app, where you approve it into a Kanban board run one card at a time under limits you set.

[!NOTE] Developer preview (2026-11-19). The gateway and the Windows desktop app are built and verified live, from first launch to "my coding tool uses auto". The Windows installer is the prerelease v0.1.0-dev.2 of 2026-11-19, not code-signed, so Windows SmartScreen warns before it runs. The pygg command line is on npm for Windows, macOS and Linux. Spending limits rest on prices and token estimates, and clean-machine installs and long-running behaviour still need validation, so Pygg is not yet for unattended or financially critical use. What is built and how each part was verified: Implementation Status.

Why Pygg

  • auto that you can read. Rules over the models you connected, not a classifier: the lowest eligible tier at or above your key's minimum, at most five models in a route and at most two from one connection, so one empty account cannot end a request. Every response says why it chose what it chose, and How auto chooses simulates a route before you send anything.
  • Cost you can trace. Each attempt is recorded with its cost and that cost's source: actual (the provider said), estimated (a price you or a catalog set) or unknown, never shown as $0. Estimated savings compare the same tokens at a model you choose, and say what they left out.
  • Fallback that does not double-bill. A 429, 402 or rejected key moves on to the next key or target, only before the agent got its first byte. A timeout stops instead, since the provider may already have billed it. Each attempt is written to disk before it is sent.
  • The provider's cache keeps working. Anthropic requests from Claude Code pass through unchanged; for OpenAI-format agents such as Codex, Pygg turns on Anthropic's prompt cache. Measured: 30% less in all, 68% less on input (below).
  • Limits that stop a session, not only a month. Each Pygg API key can have a monthly limit and, per routing session and per UTC day, a limit that refuses the next request with 402 once reached. A request already running is never cut, and concurrent requests cannot pass a strict limit together.
  • A receipt for every launch. When a tool started by pygg run exits, Pygg prints what that launch cost, how much came from the cache, which models answered, and what changed in the Git repository it ran in. pygg launches --by-repo sums it per repository and week. For Claude Code, cost is split by kind of request (main, subagent, compaction…).
  • Several accounts, used in turn. A key ring holds API keys of separate accounts on one connection (in order, round robin, least used or quota aware); a pool groups connections of one provider. Each key cools down on its own.
  • AI websites as providers, carefully. Web sessions (Muse, ChatGPT, Perplexity, DeepSeek, Grok, Gemini) are opt-in and unofficial, signed in by you in Pygg's own window, and held behind a per-site guard: one request at a time, rests between them, a daily cap, longer rests after the site's own warnings. Pictures, videos and files a site makes come back with the reply.
  • Local, with your own accounts. The gateway listens on 127.0.0.1 only and needs a Pygg API key; provider keys stay in the OS credential store. Each tool's setup is backed up first, and Remove puts it back.
  • The router as the brain, with a board. A requirement typed into your own coding agent becomes a proposal: cards with a role, a done criterion and dependencies, each on the model that measured best for that role (Terminal-Bench, SWE-bench Verified, the Arena dataset, in a weekly signed feed) and, from ten of your own runs on, on the model your kept results favour. You pick, change or drop, then approve; the board pulls cards into Running under a WIP limit, holds a finished run while Checking is full, blocks a card that waits for your approval or an answer, and measures cycle time and money per kept result. No step that costs money starts without your click (BRAIN.md, ADR-040 to ADR-042).

A look at the app

Home: the gateway running on 127.0.0.1:8741, estimated savings against a chosen model, where the answers came from, and the last 24 hours of requests

ProvidersUsageCLI Tools
Providers: each connection with its health over 24 hours, its billing and how many models auto may useUsage: estimated savings, known cost by its source, and cost per dayCLI Tools: one-click set-up for Claude Code, OpenCode and Codex

The browser preview with demo data (pnpm dev).

The boardIts measuresBrain Storming
The board of a workspace: Discovery, Ready, Running with its limit, Checking, Blocked, Review and Done; the first card of an approved brainstorm in Review after its fallback model ranThe same board at five done cards, with cycle time median, cards done today, time blocked today and money per kept result by roleBrain Storming: models by role, the code role ranking a model first on the user's own ten kept runs above the benchmark feed, and the defaults for a new brainstorm

The desktop app on a copy of the maintainer's store, as it ran on 2026-11-19 (about $0.5 of real requests in all).

How a request flows

One request through Pygg: agent, gateway, route, policy and budget, journal; the key ring's key 1 answers 429 and key 2 answers 402, both cool down; the route's next target, Ollama, answers 200; the answer streams back and each attempt is settled in the ledger

  1. Gateway. The agent calls 127.0.0.1:8741 with its own Pygg API key, in OpenAI Chat Completions, OpenAI Responses (Codex) or Anthropic Messages, streamed, with tool calls.
  2. Route. The model name is auto or auto/cheap, a role alias (auto/plan, auto/code, auto/test, auto/review, ranked by your own kept results, then public benchmark facts, then the tier table), a combo (a name for an ordered list, or cheapest first per request), a pool, <connection>/<model>, or pygg/brain, which answers with a proposal instead of running the request.
  3. Policy and budget. The key's allowed connections, health and cooldowns, quota-group holds; a key with a monthly limit holds the attempt's estimated cost first, so concurrent requests cannot pass the limit together.
  4. Journal. The attempt is written to disk before it is sent, and settled with its ledger entry in one transaction.
  5. Send and fall back. Same format passes through untouched; other pairs are translated and say what they dropped. A 429 or 402 cools that key or model down for as long as the provider says, a rejected key (401) waits until you replace it, and the next key or target is tried.

The diagrams are generated by scripts/readme-diagrams.mjs and checked against apps/desktop/src-tauri/src/gateway/. More in Architecture.

Install

Desktop app (Windows 10/11 x64). It runs the gateway, holds your connections and shows usage. Download Pygg_0.1.0_x64-setup.exe (or the MSI) and SHA256SUMS.txt from the v0.1.0-dev.2 prerelease, then check the download before running it:

Get-FileHash .\Pygg_0.1.0_x64-setup.exe -Algorithm SHA256   # compare with the line in SHA256SUMS.txt

The installer is not code-signed, so SmartScreen says "Windows protected your PC": choose More info → Run anyway. It installs for the current user, with pygg-cli.exe next to the app. To build it yourself instead, see Development.

Command line (pygg), from npm (@pygg/cli):

npm install -g @pygg/cli@dev

Published under the tag dev (the npm badge above shows the version) for Windows x64, macOS (Apple silicon and Intel) and Linux x64 (glibc). On Windows the CLI uses the desktop app's store and gateway; on macOS and Linux, where there is no app yet, pygg gateway serve runs the gateway in a terminal of its own.

Quick start

Open Pygg, then Providers → Connect Provider and paste a key (Gemini, OpenRouter and Groq have free tiers; Ollama is local). Without the app, pygg gateway add-connection --preset gemini --key-env GEMINI_API_KEY reads the key from an environment variable. Then point your tool at Pygg:

Claude Code keeps your Claude sign-in; Pygg starts it through the gateway one launch at a time.

pygg setup claude          # a Pygg key of its own, kept in the credential store; no file changes
pygg run claude            # this launch through Pygg, model auto; a receipt when it exits
pygg run --statusline claude   # the same, with the launch's cost in Claude Code's status line

Codex CLI gets a pygg provider and profile, after a backup; its default model is not changed.

pygg setup codex
pygg run codex             # or: codex --profile pygg -m auto/cheap

OpenCode gets a Pygg provider listing the auto aliases and your enabled models, kept current.

pygg setup opencode
pygg run opencode          # then /models → Pygg → auto

Chat in the terminal with any connected model, through the same router, fallbacks and ledger:

pygg chat --model muse/muse                 # a conversation; /model, /new, /cost, /exit; nothing is kept
pygg ask --model auto/cheap "Explain git worktree in two sentences"

Editors and SDKs (Cline, Continue, Roo Code, the OpenAI or Anthropic SDKs): base URL http://127.0.0.1:8741/v1, a key from Endpoint → API Keys, model auto.

Keep spending in bounds and see where it went:

pygg gateway client --name "Claude Code (launcher)" --session-usd 5 --day-usd 20   # or Endpoint → API Keys → Limits…
pygg launches --by-repo    # cost, commits and cost per commit, per repository and week
pygg usage --days 7        # requests, known and unknown cost, by client, model and kind of request

Each setup takes --dry-run to show what would change and --remove to undo it. The same set-up is one click in CLI Tools. Step by step, with troubleshooting: Getting started.

Measured, not claimed

Every run below is the maintainer's own check: real agents, real models, checks the agent cannot edit, about $16.7 of a $20 budget in all. Each report gives its method, raw results and what it does not show; read it before quoting a number. Summary: BENCHMARKS.md.

What was measuredResultReport
OpenCode on 12 small Node tasks × 3 (3 bug fixes, 8 features, 1 three-file refactor; 20 to 211 lines each), through Pygg to Claude Haiku 5.5 instead of Sonnet 5.588% less per solved task (95% CI 87–90%); one attempt per run, no retry: 36/36 passed against 34/36N2
Claude Code on the same tasks, Haiku 5.5 instead of Sonnet 5.579% less per solved task (95% CI 74–84%); auto/cheap with OpenCode: 34/36 at $0.0129 per solved taskP0
Claude Code on six tasks from a real production repository (Express + Prisma API, features across API, reports and Excel export, 124-check end-to-end suite)Haiku 5.5: 6/6 for $1.50, one attempt each; Sonnet 5.5: 4/5 for $1.19; on the 4 both solved, Haiku cost about 40% less, in 2 to 3 times the requests. OpenCode with auto/cheap: 2/6 for $0.35CCHT
Codex on Claude Haiku 5.5, Pygg's prompt caching off vs on16/16 either way; 30% less in all, 68% less on inputPrompt cache
An OpenAI-format agent on Claude Haiku 5.5 through OpenRouter, with Pygg's cache markerAfter each session's first turn, 99.7% of every prompt read from cache; $0.0066 in allOpenRouter cache
The gateway's own overhead, against a local fake providerAbout 4 ms per short request, 5 ms per 400 kB prompt; about 230 requests/s with 16 clientsOverhead
Web sessions on five sites, 48 short tasks47/48 correct, about 18 s each, $0Web sessions

Not claimed: a quality ranking of models (a handful of tasks each), a provider's bill (costs are the ledger at list prices), "60–95% fewer tokens", or savings on large refactors, database migrations or other languages, which no run has measured yet. The 88% is the whole session pinned to a cheaper model on small tasks; on the real repository the saving narrowed to about 40%, and a cost-first auto/cheap over free models solved 2 of 6. A longer web-session run on coding tasks got the owner's DeepSeek account suspended for three days (report); the guard has been stricter since.

Next to LiteLLM, measured with the same fake provider and requests (LiteLLM 1.106.2, defaults plus fallbacks; other projects compared from their docs in BENCHMARKS.md):

When the primary provider…PyggLiteLLM proxy
is rate-limited, out of credit or unreachable100% served, 1.04 provider requests each, ~70 ms100% served, 4 provider requests each, ~4.6 s (88 s with Retry-After: 30)
fails with 500 or drops the connection96% / 0% served: never re-sent unless you allow it (100% for a 500 with one retry allowed)100% served, after 3 attempts at the failing provider each
is Claude, reached by an OpenAI-format agent89.5% of the prompt read from cache, automatically0% by default; 89.5% (Chat Completions) or 39.7% (Codex's Responses API) with injection points configured
sits behind a key ring of several accountssessions stay on one key: 60 / 600 / 60 by default, 60 / 60 with affinity on

Where Pygg is worse: about 230 requests/s on one PC (LiteLLM publishes 1,170 on four instances), no timeout fallback for a hung provider, and a 5xx or dropped connection reaches your agent as an error by default. Reports: resilience, tokens and cost, web guard.

Benchmark it on your work

One person's runs on a few dozen tasks are a start, not proof. The benchmark needs the community: run the harness on the cases here or on your own repositories (they can stay private; only the result lines are published, as in CCHT), add cases the runs above lack, such as large refactors, database migrations and other languages, and open a pull request with the report and its raw results (how). A run where the cheaper model loses is as welcome as one where it wins.

What's inside

Coding agents ──HTTP──► Gateway 127.0.0.1:8741 (axum) ──► OpenAI- and Anthropic-compatible APIs, coding plans,
  Claude Code, Codex,     auth · route · policy · journal       local runtimes (Ollama …), web sessions (WebView2
  OpenCode, SDKs          translate · fall back · settle         windows behind the guard)
                                   │
       React UI ◄── Tauri ──► Rust core ──► SQLite store (ledger, journal, connections) · OS credential store
       pygg CLI ──────────────┘
  • One Rust crate (Tauri 2): the gateway (axum), the SQLite store, the OS credential store, web-session windows, and the headless programs (pygg-cli, gateway, pygg-mcp) built from the same library.
  • Interface: React 19, Vite and TypeScript, with a layout check over every screen in CI (pnpm ui-check).
  • Skills & Prompts: one library of skills in the Agent Skills format, installed into Claude Code's, Codex's and OpenCode's own skills folders, and a count of what each agent sends with every request from its global files (ADR-039).
  • @pygg/cli on npm: a Node launcher with one optional package per platform (ADR-037).
  • Smart tasks (experimental): IDE agents hand subtasks to Pygg over MCP, or send a requirement to pygg/brain; agent CLIs run the tasks in Git worktrees against the repository's approved checks, paid steps wait for your approval, and the board (ADR-042) runs an approved brainstorm's cards under WIP limits with the Brain Storming screen holding the picks and defaults for every project (AGENTS.md, BRAIN.md). The model facts feed behind the role ranks is built weekly by scripts/model-facts.py from sources with open licences, signed, and verified by the app before use (ADR-040). Each part has run live once on the maintainer's store, not under the benchmark harness.

Is Pygg a fork of 9router?

No. Pygg is the same kind of tool as 9router: a local router that points your coding agents at the providers you already have. 9router was one of the inspirations for building the gateway first (ADR-016). Pygg's code is written from scratch in Rust; the one part that follows 9router is the Muse web-session recipe, credited under MIT in THIRD_PARTY_NOTICES.

Where they differ, read from 9router's documentation and source (not run here):

  • Re-sending. 9router moves to the next model on a 5xx or a timeout; Pygg does not re-send a request the provider may already have run, unless you allow one retry.
  • Retry-After. 9router uses fixed cooldowns; Pygg waits as long as the provider says.
  • Prompt cache. Pygg keeps each session on one key by default (9router with its smart strategy) and adds Anthropic's cache marker for OpenAI-format agents such as Codex.
  • Cost. 9router's cost is "for tracking only"; Pygg records every attempt, fallbacks included, with where its cost came from.
  • Web sessions. Both drive AI websites; Pygg holds each site behind a guard (one request at a time, rests, a daily cap) that cannot be switched off.

The full table, with LiteLLM, OpenRouter, OmniRoute and claude-code-router: BENCHMARKS.md.

Documentation

UseGetting started · Providers · Benchmarks · Security
UnderstandArchitecture · Decisions (ADR-001 to ADR-042) · The brain, the facts feed and the board · Schema · Screens · Command line
TrackImplementation status · Roadmap · Benchmark reports
ContributeContributing · Code of conduct · Every document, indexed

Only the app's data folder (app.smarttaskrouter.desktop) and its credential service name keep the engineering name SmartTaskRouter, so existing data stays readable. Brand assets are in branding.

Development

Requirements: Node.js LTS with pnpm 9 (corepack enable), stable Rust through rustup, and on Windows the Visual Studio C++ Build Tools and WebView2 (built into Windows 11).

pnpm install
pnpm dev                                              # the interface at http://127.0.0.1:1431 with demo data (?empty for a first run)
pnpm --filter @pygg/desktop tauri:dev     # the desktop app with the real gateway
pnpm typecheck
pnpm --filter @pygg/desktop tauri:build   # the installers, under apps/desktop/src-tauri/target/release/bundle
pnpm ui-check                                         # every screen at several window sizes, nothing overflowing
cd apps/desktop/src-tauri; cargo test --lib --tests   # core, gateway, web-session and task engine tests
node scripts/readme-diagrams.mjs                      # regenerate the README's animated diagrams
python scripts/model-facts.py selftest                # the model facts builder on its fixtures (build, sign, verify: see the script)

PYGG_DATA_DIR points the app at another store, for trying it without touching your own; that app runs beside the installed one, with its own window profile, and needs a gateway port of its own (Endpoint → Configure…).

Licence

MIT, see LICENSE. Third-party code and data are listed in THIRD_PARTY_NOTICES.md.

// faq

What is Pygg?

Run your coding agents on cheaper models without losing the answers. A local gateway for Claude Code, Codex and OpenCode that routes each request to a model you connected and measures what it saved.. It is open-source on GitHub.

Is Pygg free to use?

Pygg is open-source under the MIT license, so it is free to use.

What category does Pygg belong to?

Pygg is listed under devtools in the Claudeers registry of Claude-compatible tools.

0 views
★ 11 stars
unclaimed
updated 1 day ago

// embed badge

Pygg on Claudeers
[![Claudeers](https://claudeers.com/api/badge/pygg.svg)](https://claudeers.com/pygg)

// retro hit counter

Pygg hit counter
[![Hits](https://claudeers.com/api/counter/pygg.svg)](https://claudeers.com/pygg)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how Pygg connects across the ecosystem