TokenFrugal

Hand routine coding work to a free local LLM, and keep your paid cloud model for planning and hard decisions.

TokenFrugal is an MCP server. Your cloud agent (Claude Code, Codex, Cursor or any MCP client) calls one tool, dispatch_task(agent, task). A local model does the work and returns a summary of up to 5000 tokens, so your cloud quota pays for thinking, not for boilerplate.

Why TokenFrugal

• Lower token spend. Tests, docstrings, lint fixes, file edits and log reading go to a local model. The cloud agent only sees a short summary.
• Private by default. Local models run on your machine. Only summaries and a task_id return to the cloud agent.
• No surprise bills. A failed task returns a short error and a task_id you can resume. Nothing falls back silently to the cloud.
• Small models that stay on track. Each role gets a tool allowlist of 4-6 tools, and runs one model at a time.
• Visible and auditable. A live dashboard shows every tool call, and the task log is stored locally.

Use cases

1. Stretching a limited subscription. Your seat has tight limits. Send unit tests, docstrings and boilerplate to builder, and keep the cloud model for design and review.
2. Triaging logs and test output. Ask the analyzer or debugger role to read a long log or failing test run and return the root cause in a few lines.
3. Reviewing and scanning code before a merge. The reviewer role checks a diff, and the security role runs SonarQube rules, all on local models.
4. Working on confidential code. For client or internal code that must not leave the machine, the source stays local and only summaries reach the cloud agent.
5. Documentation, design and browser checks. Route docs to docs, UI mock-ups to designer, and page audits to browser, each with its own persona and tools.

Install (Windows, macOS, Linux)

You need Python 3.11+, git, Docker, and Ollama (or any OpenAI-compatible LLM API). Pick your agent below: each has the steps, then a prompt you can paste into the agent to do the install for you.

Install the router

git clone https://github.com/maxh8086/tokenfrugal.git
cd tokenfrugal
python -m venv .venv

Activate the environment:

• Windows (PowerShell): .venv\Scripts\Activate.ps1
• macOS / Linux: source .venv/bin/activate

Then install and check:

pip install -r requirements.txt
cp .env.example .env          # Windows: copy .env.example .env, then set TOKENFRUGAL_LLM_URL
python scripts/doctor.py      # checks everything and prints the fix commands

Note the full path to the venv’s Python for the next step: .venv\Scripts\python.exe on Windows, .venv/bin/python on macOS and Linux.

Connect Claude Code

Run from inside the tokenfrugal folder, replacing the placeholder with your venv Python path: