把常规编码工作交给免费的本地LLM，保留你的付费云模型用于规划和艰难决策。

TokenFrugal 是一个 MCP 服务器。你的云代理（Claude Code、Codex、Cursor 或任何 MCP 客户端）调用一个工具，dispatch_task(agent, task)。本地模型完成工作并返回 150-300 个令牌摘要，所以你的云配额支付的是思考，而不是模板。

为什么要节俭

• 降低令牌消耗。 测试、文档字符串、lint 修复、文件编辑和日志读取都会送到本地模型。云代理只看到简短的摘要。
• 默认为私有。 本地模型运行在您的机器上。只有摘要和 task_id 返回到云代理。
• 无意外账单。 失败任务会返回短小错误，你可以继续执行task_id。没有任何内容会无声地返回云端。
• 保持进度的小模型。 每个角色会有一个包含4-6个工具的工具允许列表，每次运行一个模型。
• 可视化且可审计。 实时仪表盘显示每一次工具调用，任务日志存储在本地。

使用场景

1. 有限订阅时间。 你的座位有严格限制。

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 6 tools recommended, 12 at most, 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: