badgr-auto

Open-source local proxy that safely removes exact repeated structured context, optionally routes requests across models, and provides visibility into token savings—without changing your existing AI workflow.

Works with Cline, Continue, Aider, OpenClaw, Open WebUI, and any OpenAI-compatible tool.

Docs · GitHub · VS Code Extension · AI Badgr

Install

npm install -g badgr-auto
badgr-auto start

One-time setup

Point any OpenAI-compatible tool at the local proxy:

Base URL: http://localhost:51999/v1
API Key:  <YOUR_BADGR_API_KEY>
Model:    badgr-auto

The setup wizard runs automatically on first start. Run badgr-auto start --setup to re-run it.

What it does

| Feature | Default | Flag | |---------|---------|------| | Token optimization | on | --no-optimize | | Smart routing | off | --no-route to keep off | | Local models (Ollama / LM Studio) | off | enable in setup | | Memory (per-repo/per-task track record) | on | memoryEnabled: false in config | | Savings tracking | on | always on | | Anonymous daily analytics (opt-out) | on | badgr-auto analytics off, --no-analytics, or DO_NOT_TRACK=1 |

Token optimization deduplicates exact repeated blocks—code, diffs, logs, retrieved docs—and summarizes older messages above 12 K tokens. System messages, tool calls, function schemas, and git working-tree output are never touched.

Smart routing routes requests to the cheapest suitable model tier (local → OSS cloud → premium) based on task complexity and token count. Requires an AI Badgr account.

Memory keeps a local, read-only track record of what worked and what failed, per repo and per task type, and injects a short summary system message back into matching requests — zero setup, nothing raw ever stored. Lives entirely under ~/.badgr/memory, never inside your repo. See Memory below.

Context health warns at 60% ("compact soon") and 75% ("compact now") of the model's context window. Visible in badgr-auto monitor and per-request receipts.

Passthrough mode (both off): requests forward unchanged to your upstream. Zero transformation, zero overhead.

Verified integrations

End-to-end tested and confirmed working:

• Cline
• Continue
• Aider
• OpenClaw
• Open WebUI
• OpenAI SDK — set base_url and api_key, any model name

Full setup instructions: docs/setup-guides.md

Commands

# Proxy lifecycle
badgr-auto start              # start the proxy (setup wizard on first run)
badgr-auto start --setup      # re-run the setup wizard
badgr-auto stop               # stop the proxy
badgr-auto restart            # restart with current config
badgr-auto status             # proxy status and routing config

# Observability
badgr-auto stats              # token savings summary + "top waste" (all time)
badgr-auto stats today        # calendar day (local midnight to now)
badgr-auto stats 7d           # last 7 days
badgr-auto stats --rolling    # rolling 24 hours (also: 1d, --period 24h)
badgr-auto monitor            # live request monitor
badgr-auto receipts           # per-request receipt list
badgr-auto receipts --failed  # errors only
badgr-auto receipts --fallback  # fallback requests only
badgr-auto receipt <id>       # routing diagnosis for one request
badgr-auto receipt <id> --export  # plain-text support bundle
badgr-auto events             # local event log (request/memory/optimization)
badgr-auto events --type memory_injected --limit 20
badgr-auto analytics          # anonymous usage analytics on/off/status
badgr-auto dashboard          # open the AI Badgr cloud dashboard

# Memory (read-only, nothing to maintain)
badgr-auto memory             # global rollup + current repo's track record
badgr-auto memory global      # cross-project rollup only
badgr-auto memory repo        # current repo's track record + branch
badgr-auto memory task        # current branch + last-active time
badgr-auto memory clear       # wipe all local memory (--global or --repo to scope)

# Auth
badgr-auto login              # interactive — paste API key from aibadgr.com
badgr-auto login --api-key <key>  # non-interactive
badgr-auto login --ci         # read BADGR_API_KEY from env (for CI/scripts)

# Models & routing
badgr-auto models             # list detected local models
badgr-auto select             # switch model tier interactively

# Eval (shadow mode)
badgr-auto eval               # list stored eval payloads
badgr-auto eval <id>          # replay original vs optimized, show safety verdict

# Context handoff
badgr-auto new-task           # interactive wizard — saves task-handoff-*.md
badgr-auto new-task --template  # print blank handoff template

Memory

On by default (memoryEnabled: true). A side effect of the proxy already routing and scoring every request — no setup, nothing to curate, nothing raw (no prompts, no model output) ever written. Storage lives entirely under ~/.badgr/memory (never inside a repo, so git status stays clean):

~/.badgr/memory/global.json            rollup across all projects
~/.badgr/memory/repos/<repo-hash>.json per-repo track record
~/.badgr/memory/tasks/<repo-hash>.json current branch, last-active time

Before token optimization, the proxy classifies the task type (same classifier the router already uses), looks up that key in repo + global memory, and — only if there's something to say — prepends a short system message (capped at memoryMaxTokens, default 800) to /v1/chat/completions and /v1/messages requests.

badgr-auto memory          # global rollup + repo track record
badgr-auto memory global   # cross-project rollup only
badgr-auto memory repo     # current repo's track record + branch
badgr-auto memory clear    # wipe all local memory (--global or --repo to scope)

Disable entirely with memoryEnabled: false in your config — existing files under ~/.badgr/memory are left in place. Full details, including known limitations (repo scoping fallback, keyword-based task classification): docs/badgr-auto-launch.md.

Local event log & privacy

badgr-auto start prints the Memory, Receipts, Events, and Config file paths on every start. Every request appends structured, privacy-safe events to ~/.badgr/events/events.jsonl — request_started, request_completed, request_failed, model_used, fallback_used, context_optimized, memory_injected/memory_used/memory_created, stats_viewed, memory_viewed. Never a prompt, a response, or source code.

badgr-auto events                              # last 30 events, newest first
badgr-auto events --type=memory_injected       # filter by event type
badgr-auto events --limit=50 7d                # last 7 days, up to 50 events

Once every 24 hours (and only when analytics is on), an anonymous daily_summary — task-type counts, tool/model mix, a tokens-saved bucket, top repeated context, and error categories, tagged with a pseudonymous device ID — is sent to AI Badgr. Raw prompts, responses, source code, and repo names are never included; skipped entirely when there's no activity.

badgr-auto analytics           # show current status + how it's disabled, if it is
badgr-auto analytics off       # disable PostHog events and the daily summary
badgr-auto analytics on        # re-enable

The community-standard DO_NOT_TRACK=1 env var also disables analytics, and badgr-auto start --no-analytics disables it for that run.

Shadow eval mode

Sample a fraction of requests to validate optimization safety. On each sampled request, both the original and optimized messages are replayed against your model. badgr-auto eval <id> shows a safe/unsafe verdict with per-check breakdown (tool calls, missing-context complaints, output similarity).

badgr-auto start --eval-sample 0.05   # sample 5% of requests
badgr-auto eval                        # list stored payloads
badgr-auto eval 42                     # show verdict for request #42

CI / non-interactive login

# Save key directly
badgr-auto login --api-key sk-...

# Read from env (CI pipelines)
BADGR_API_KEY=sk-... badgr-auto login --ci

Requirements

• Node.js 20.10.0 or newer
• Optional: npm install -g tiktoken for more accurate token counts

Links

• Docs: aibadgr.com/docs/badgr-auto
• Source: github.com/michaelmanly/badgr-auto
• Issues: github.com/michaelmanly/badgr-auto/issues

License

MIT