npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

pusula

v1.0.0

Published

Pusula: unified AI gateway with 375 providers, RTK+Caveman compression, auto fallback, MCP/A2A, desktop, PWA, and OpenAI-compatible APIs.

Readme

Live demo

The redesigned landing page, live at pusula.fyajan.com/landing. Its counters are computed from the source when the page loads; the routing you see is a simulation.

🧭 Pusula — The Free AI Gateway

💰 ~1.62B Free Tokens / Month

Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. Pusula catalogs 467 free-tier entries across 34 recurring pool keys and computes the token headline from the 17 pools with a published positive monthly budget plus five per-model Groq caps, deduplicated by shared pool. Quotas that only open after a regional identity check (today: ModelScope) are shown apart, +~6M behind regional identity verification, and never summed into the headline. The result stays visible on the dashboard (/dashboard/free-tiers).

Animated summary of the live /dashboard/free-tiers page. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.

These figures come straight from the free-tier catalog (last curated 2026-10-19) and move both ways — a provider ends a free tier and the number drops; a new one lands and it climbs. We publish what the catalog actually computes, never a rounded-up best case.

⭐ Star the repo if PUSULA helped you save money and make your work easier.

Stars

💬 Questions & support

GitHub Issues

Bugs, feature requests & questions → open an issue · What's planned → ROADMAP.md

🧩 Available

npm version NPM Monthly GHCR Live demo License: MIT

🆕 What's new

Landed on main after the 1.0.0 release (2026-10-20), newest first. Full notes → CHANGELOG.md

  • 🛰️ Self-hosting that updates itself (#45) — scripts/ops/vps-auto-update/ installs a systemd timer that pulls ghcr.io/ferhat-yasinoglu/pusula:main about every 15 minutes. Each update backs up the data directory first, has to pass a health gate, and is rolled back automatically if the new container fails. Nothing ever connects to your server.
  • 🌍 Live public instance — pusula.fyajan.com runs the :main image and keeps itself current with that updater.
  • ⬆️ Synced with upstream OmniRoute v3.8.52 (#39) — the provider catalog grows from 358 to 375 providers and 23 new database migrations land (186 → 209 SQL files), with Pusula's design, brand and four locales unchanged.
  • 🪶 Headless mode (from the sync) — pusula serve --headless or PUSULA_HEADLESS=1 keeps the OpenAI-compatible API under /v1/* and switches the dashboard off. → Headless Mode
  • 🚫 Keyless "OpenCode Free" removed (from the sync) — the opencode provider (oc/…) is gone, honoring the OpenCode operator's removal request; opencode-zen, opencode-go and the OpenCode client integrations stay. auto now routes across the providers you connect. → Removed providers
  • 🐛 Fixes — POST /api/keys/groups no longer fails with 405, so key groups can be created over the API (#37); CLI detection no longer reports Continue as installed because of the project's own node_modules/.bin (#35); the unused mermaid dependency is gone (#38); plus CI fixes for the main-only repo (#36, #43) and three flaky tests made deterministic (#44).
  • 🧭 Redesigned landing page (#33) — a compass-and-needle hero and seven more stations (network map, provider catalog, routing, resilience, tools, engine room, launch), all driven by one simulated gateway. → Live demo · Screenshots

🆓 Install, connect a provider, route

# After connecting at least one provider (Dashboard → Providers), `auto` routes across it:
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

Prefer a specific backend? Call it directly as <alias>/<model> (aliases are listed in docs/reference/PROVIDER_REFERENCE.md). Then graduate to auto and let Pusula pick.

📦 Copy-paste quickstart scripts for Python, Node.js, PHP, and cURL → examples/quickstart/

💥 The Promise

🤔 Why Pusula?

🎯 Combos — The Flagship

A combo is a chain of models Pusula routes across automatically. If quota runs out, a provider fails, or costs spike, the combo can move to the next eligible healthy model. 🛡️

⚡ Zero-config — just use auto

No combo to create. Set your model to auto (or a variant) and Pusula builds a virtual combo from your connected providers, scored live:

🔀 Or build your own — 20 routing strategies

All 20 strategies — mix & match per combo step:

The Auto-Combo engine scores every candidate on 16 factors (health, quota, cost, latency, task fit, quality, session availability…) — see docs/routing/AUTO-COMBO.md.

🧱 Resilience is built in (3 independent layers)

📖 Auto-Combo Engine · Resilience Guide

🏆 What Sets Pusula Apart

📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → docs/comparison/PUSULA_VS_ALTERNATIVES.md

📸 Screenshots

The dashboard on http://localhost:20128 — fresh install, before any provider is connected.

🤖 Compatible CLIs & Coding Agents

One config — http://localhost:20128/v1 — and every AI IDE or CLI runs on free & low-cost models.

📖 Per-tool setup for all 37 tools (27 CLI Code's + 10 CLI Agents) → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @pusula/opencode-plugin (bundled; pusula setup opencode)

Launch any supported CLI through Pusula in one command — no config files written, credentials injected per process, Qwen/Gemini get a throwaway isolated home:

pusula run claude   --model openai/gpt-5.4          # Claude Code
pusula run codex    --model glm/glm-5.2             # OpenAI Codex CLI
pusula run aider    --model glm/glm-5.2 -- --message "reply OK"
pusula run goose    --model glm/glm-5.2
pusula run opencode --model glm/glm-5.2 -- run "reply OK"
pusula run qwen     --model glm/glm-5.2 -- -p "reply OK"
pusula run gemini   --model glm/glm-5.2 -- --skip-trust -p "reply OK"

# Or pick provider+model interactively and write the tool's own config:
pusula configure codex          # also: claude opencode qwen aider goose gemini cline continue kilo

Every command honors the active remote context (pusula connect <host>), --dry-run previews the exact env/args without executing, and --api-key-env NAME keeps secrets out of your shell history. → CLI Integrations

🌐 375 AI Providers — 153 Catalog-Marked Free

375 registered providers across the canonical chat, media, search, local, cloud-agent and system collections, including 153 carrying hasFree: true discovery metadata. The chat model registry covers 239 providers with static models / 3,059 distinct provider-model pairs / 1,476 distinct model IDs; the separate free-budget catalog has 467 per-model rows, 34 recurring pools and 51 recurring/keyless free-forever providers. These are different denominators by design; definitions and pool-deduped calculations live in the Provider Reference and Free Tiers.

🏢 Every major lab — through one endpoint

…and 350+ more — every icon resolves live from the dashboard's provider catalog. 📖 Provider Reference

🆓 Free Forever — $0, no card

📖 Full machine-readable catalog → docs/reference/PROVIDER_REFERENCE.md

🖥️ Where Pusula Runs — Anywhere

Same app, your machine, your rules. From a global npm install to your phone via Termux.

📖 Docker Guide · Desktop · Termux · PWA · OpenCode

🔒 Private & Local-First

📖 Authorization · Guardrails · Compliance

🔌 Full CLI + A2A & MCP

Beyond the server, Pusula is a full command-line cockpit with 80+ commands, plus open agent protocols so an AI agent can drive it on its own.

⌨️ A real CLI (not just start)

pusula               # serve gateway + dashboard (port 20128)
pusula repl          # interactive TUI chat (slash: /model /combo /skill /memory)
pusula setup         # guided first-run wizard
pusula doctor        # diagnose config, DB, ports, Node runtime, native deps

🛰️ Remote mode — run the CLI here, Pusula on a VPS

Pusula on a server? Drive it from your laptop with the same CLI. Log in once with a scoped access token; every command then targets the remote.

pusula connect 192.168.0.15            # password → scoped token, saved as a context
pusula models                         # ← runs against the REMOTE server
pusula configure codex                 # ← picks a remote model, writes a local Codex profile
pusula tokens create --name ci --scope read   # mint narrower tokens for other machines
pusula contexts use default            # ← switch back to the local server

Tokens are scoped read / write / admin; process-spawning routes stay loopback-only. 📖 Remote Mode

🤝 Connect an agent — and it controls Pusula itself

Expose Pusula over MCP, A2A, a REST API, webhooks or a remote CLI — any capable agent (or your own code) gets the keys to the whole gateway: routing, providers, combos, cache, compression, memory — autonomously. HTTP endpoints below are served under http://localhost:20128.

# Give Claude Code the full Pusula toolset over MCP:
pusula mcp enable --transport streamable-http
claude mcp add --transport http pusula http://localhost:20128/api/mcp/stream --header "Authorization: Bearer <api-key-with-management-access>"

📖 MCP Server · A2A Server · Agent Protocols

🗜️ Save 15–95% Tokens — Automatically

📖 How it works — pipeline, architecture & savings math

Default stacked combo runs RTK → Caveman. When both act on the same tool/context payload, savings compound:

combined = 1 − (1 − RTK) × (1 − Caveman_input)
average  = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range    = 78.4 – 94.6%

Code blocks, URLs, JSON and structured data are always protected by the preservation engine.

Why use many tokens when few tokens do the trick? Every request passes through Pusula's compression pipeline transparently — no client changes. It's now a stack of 12 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman, LLMLingua-2, and Troglodita (PT-BR).

🧱 The 12-engine stack

Engines run in pipeline order; each is independently toggleable and configurable per combo:

Code blocks, URLs and structured data are always preserved byte-perfect. One-click presets combine the engines:

Real example — Standard mode:

Before (69 tokens): "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."

After (19 tokens): "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Same answer. 72% fewer tokens. Zero accuracy loss. ✅

PT-BR example — Troglodita mode:

Antes (42 tokens): "O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."

Depois (12 tokens): "Re-render: ref nova cada ciclo (objeto inline recriado). Usar useMemo."

Mesma resposta. ~70% menos tokens. Precisão técnica intacta. ✅

🎚️ Beyond the engines — output styles, the adaptive dial & per-request control

The 12 engines above shrink what goes in. Three more layers shape how, when, and what comes out:

  • 🪄 Output Styles (output-axis steering) — inject deterministic, cache-safe response-shaping instructions; combinable, each at lite / full / ultra intensity. Adding a style is a one-line registry entry:
    • Terse prose — drop filler / articles / hedging; keep technical substance exact.
    • Less code — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
    • Ponytail (lazy senior dev) — climb the YAGNI ladder, fix the root cause, smallest working diff.
    • I have ADHD (action-first) — next action leads, steps numbered, one concrete next step, no preamble.
    • Terse CJK (文言) — classical-Chinese ultra-terse style (locale-gated to zh).
  • 🎯 Adaptive context-budget (the dial) — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to fit the model's context window. Policy: reserve-output (default, model-aware) · percentage · absolute. Mode: floor (guarantee fit) · replace-autotrigger (your explicit choice wins) · off (legacy threshold).
  • 🎛️ Where compression is decided (precedence, high → low) — per-request x-pusula-compression header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the X-Pusula-Compression: <mode>; source=<source> response header.

Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline eval harness (npm run eval:compression) scores fidelity vs. savings on a pinned corpus before you promote a change.

📖 COMPRESSION_GUIDE.md · RTK_COMPRESSION.md · COMPRESSION_ENGINES.md

⚡ Quick Start

1) Install & run

npm install -g pusula
pusula

💡 See npm warn ERESOLVE or peer-dep warnings? They're harmless. Using Gemini Web or another web-cookie provider? The npm package includes Playwright but not its Chromium binary. See the Playwright Chromium setup note before making the first web-provider request.

Dashboard at http://localhost:20128 · API at http://localhost:20128/v1.

2) Connect a FREE provider (no signup)

Dashboard → Providers → connect a keyless provider such as UncloseAI or AI Horde (no API key, no signup) → done.

3) Point your coding tool

Base URL: http://localhost:20128/v1
API Key:  [copy from Dashboard → Endpoints]
Model:    auto            (zero-config smart routing — or any provider/model)

4) Verify it's working

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

You should see your connected models listed. 🎉 That's it — start coding, and Pusula auto-routes & falls back for you.

If your client cannot send custom headers, Pusula also exposes tokenized compatibility aliases:

OpenAI catalog:   http://localhost:20128/api/v1/vscode/YOUR_KEY/
OpenAI models:    http://localhost:20128/api/v1/vscode/YOUR_KEY/models
OpenAI chat:      http://localhost:20128/api/v1/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/api/v1/vscode/YOUR_KEY/responses
Ollama chat:      http://localhost:20128/api/v1/vscode/YOUR_KEY/api/chat
Ollama tags:      http://localhost:20128/api/v1/vscode/YOUR_KEY/api/tags

Use these only for clients that cannot attach Authorization: Bearer .... Header auth remains the preferred mode.

📦 More install methods — Docker, Bun, source, pnpm, Nix, Podman

🐳 Docker

docker run -d --name pusula --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 -v pusula-data:/app/data ghcr.io/ferhat-yasinoglu/pusula:main

:main is rebuilt on every push to main. There is no tagged release yet, so :latest and :X.Y.Z do not exist; once releases are published, :latest follows the highest stable SemVer and :X.Y.Z pins one for GitOps. See Docker Release Channels. The image pins PUSULA_MEMORY_MB=1024. That is enough for the dashboard and a light chat. Coding agents (POST /v1/responses from Claude Code, Codex, Grok, …) need a much larger V8 heap or the process FATAL ERRORs at ~12 GiB under two overlapping long contexts. Size the container above the heap (native buffers sit outside V8):

| Workload | Heap (-e PUSULA_MEMORY_MB) | Container (--memory) | | ----------------------------------- | ---------------------------- | ---------------------- | | Dashboard / light chat | 1024 (image default) | ≥2 g | | One coding agent | 8192 | ≥10 g | | Two concurrent long /v1/responses | 10240–12288 | ≥12–16 g |

docker run -d --name pusula --restart unless-stopped --stop-timeout 40 \
  -e PUSULA_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v pusula-data:/app/data ghcr.io/ferhat-yasinoglu/pusula:main

Full table: Docker Guide — runtime RAM.

Development channel: ghcr.io/ferhat-yasinoglu/pusula:main (plus :main-web with Chromium and :main-bun) is rebuilt on every push to main. It is what https://pusula.fyajan.com runs, kept current by the pull-based updater in scripts/ops/vps-auto-update/. These tags are mutable and are not a pinned production channel.

🥟 Bun

Bun is a best-effort compatibility path, not a supported runtime: bun install and bun install -g pusula start via Bun runtime detection:

  • Built-in bun:sqlite: Pusula uses Bun's built-in bun:sqlite driver when running under Bun, falling back to better-sqlite3 on Node.js or sql.js.
  • Automatic Webpack bundler selection in dev: Development under the Bun runtime (bun --bun run dev) automatically detects Bun and disables Turbopack in favor of Webpack to prevent native V8 binding incompatibilities. Production builds (bun run build) follow PUSULA_USE_TURBOPACK exactly as on Node: Turbopack by default, PUSULA_USE_TURBOPACK=0 to build with Webpack (Dockerfile.bun exposes it as a --build-arg).
  • Dedicated Bun Dockerfile: Multi-stage Dockerfile.bun for native Bun production deployments (docker build -f Dockerfile.bun -t pusula:bun .).
# Install and run with Bun
bun install
bun --bun run dev

🛠️ From source

cp .env.example .env && npm install
PORT=20128 npm run dev

📦 pnpm

pnpm add -g pusula@latest --allow-build=better-sqlite3 --allow-build=@swc/core && pusula

🔧 Nix (Flake)

# Using Nix flakes
nix develop
npm run dev

📖 Docker Guide — Compose profiles, Caddy HTTPS, Cloudflare tunnels.

🦭 Podman

# 1. Prepare the bind-mounted data directory
mkdir -p data

# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data

# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build

On macOS or Windows, Podman uses a remote Podman Machine: skip podman unshare and follow the topology-specific data directory guidance.

📖 Podman Guide — Compose builds, Podman Machine, and Linux/systemd Quadlet setup.

⚡ Faster / leaner install (skip the native build)

The native SQLite engine (better-sqlite3) is an optional dependency, so a global install never blocks on compiling from source: it uses a prebuilt binary when one matches your platform/Node, and otherwise falls back transparently to a pure-JS engine (node:sqlite on Node 22+, else the bundled sql.js WASM) — no build tools required.

To skip the post-install native warm-up entirely (CI, headless, or slow machines). Note: this only skips the native SQLite warm-up step (scripts/postinstall.mjs); the binary-copy/repair hook (scripts/build/postinstall.mjs) still runs normally:

PUSULA_SKIP_POSTINSTALL=1 npm install -g pusula   # CI=1 also skips it

For the fastest installs prefer pnpm (content-addressed store + hard links — see above). For a dashboard-free, headless runtime run pusula serve --headless (or set PUSULA_HEADLESS=1, also inside Docker) — see Headless Mode. The CLI and the web dashboard are served by the same process on one port, so there is no separate CLI-only package today.

📧 Community & Help

Everything happens on GitHub — open an issue or send a pull request.

| Channel | Where / how | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | 🐛 Report a bug | open an issue — attach pusula doctor output (or npm run system-info from a source checkout) | | 💡 Request a feature | open an issue using the feature-request template | | 💬 Questions & help | open an issue — setup help, provider tips, roadmap ideas | | 🔒 Security report | private security advisory — see SECURITY.md | | 📦 Source code | github.com/Ferhat-Yasinoglu/pusula | | 🤝 Contribute | CONTRIBUTING.md · open issues |


🛠️ Tech Stack

📖 Documentation

📘 Getting Started

🔧 Operations & Deployment