Cheap Ag MCP Server

<h1 align="center">Cheap Agent</h1> <p align="center"> <em>Your frontier model is a principal engineer. Stop paying it to type.</em> </p> <p align="center"> <img src="https://img.shields.io/npm/v/cheap-agent?style=flat-square&color=111111&label=npm" alt="npm"> <img src="https://img.shields.io/badge/for-Claude%20Code%20%7C%20Codex-111111?style=flat-square" alt="For Claude Code and Codex"> <img src="https://img.shields.io/badge/cheap%20model-%C2%BD%C2%A2%20a%20task-111111?style=flat-square" alt="Cheap model: half a cent a task"> <img src="https://img.shields.io/badge/tested%20on-SWE--bench%20Verified-111111?style=flat-square" alt="Tested on SWE-bench Verified"> <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT License"> </p> <p align="center"> <img src="assets/demo.gif" width="880" alt="Two real Claude Code sessions side by side, same prompt: Claude Code alone climbs to 233k Opus tokens, Claude Code with Cheap Agent stops at 132k, and the cheap model costs $0.007."> </p> <p align="center"> <img src="assets/hero.svg" width="880" alt="Same feature, same prompt: Claude Code alone used 154k Opus tokens in 5 turns; with Cheap Agent 57k Opus tokens in 2 turns, 63% fewer, and the cheap model cost half a cent. Both versions pass all their tests."> </p> <p align="center"> <strong>Same feature. Same prompt. 63% fewer Opus tokens.</strong><br> <strong>Your Claude or ChatGPT plan lasts longer. Your code still ships with tests.</strong> </p> <p align="center"> ⭐ Star it, and click <strong>Watch → Custom → Releases</strong> to hear when new versions ship. <br>💬 Questions, ideas and setups: <a href="https://www.reddit.com/r/CheapAgent/">r/CheapAgent</a> </p>

Install

Works in Claude Code and Codex. One login covers both.

Let agent install

Copy this into Claude Code or Codex and let the agent take it from there. It asks what you want, sets things up, and gives you one command to run yourself, where you type your API key.

Set up Cheap Agent (npm: cheap-agent) for me.
1. Ask me which provider (OpenRouter recommended, DeepSeek, OpenCode Go, Command Code, OpenCode Zen,
   or Custom endpoint for a local model or any OpenAI-compatible API) and which models
   (balanced is the default; cheapest, strongest, or my own provider/model).
2. Check that node is 20+, and whether I use Claude Code (claude CLI), Codex (codex CLI) or both.
3. If I picked my own model, save {"models":{"implement":"<model>"}} in
   ~/.config/cheapag/config.json, keeping what else is there.
4. Give me the command to run in my terminal: npx cheap-agent login --preset <my choice, or custom>,
   and which provider to pick with the arrow keys or its number (1 OpenCode Go, 2 OpenRouter,
   3 DeepSeek, 4 Command Code, 5 OpenCode Zen, 6 Custom endpoint). If I don't use Claude Code, tell me
   to say no when it offers to add itself there. I run it and type my API key there. Never ask for my key.
5. When I say done: for Claude Code, check `claude mcp list` shows cheapag. For Codex, run
   `codex plugin marketplace add muaaz9329/cheap-ag` and `codex plugin add cheapag@cheap-agent`.
6. Tell me to open a new session in my project and run /cheapag:allow in Claude Code, or
   $cheapag:allow in Codex (trusting the 3 cheapag hooks when it asks).

Claude Code

npx cheap-agent

Pick a provider (OpenRouter if unsure), press Enter for the recommended models, paste your API key. It checks the key works, then adds itself to Claude Code for every project.

Then, in each project, once:

/cheapag:allow

That's it. Ask Claude for changes like you always do.

Codex

Log in (say no when it offers to add itself to Claude Code, if you don't use Claude):

npx cheap-agent

Add the plugin:

codex plugin marketplace add muaaz9329/cheap-ag

codex plugin add cheapag@cheap-agent

Start codex in your project and trust the 3 cheapag hooks when it asks. Then, in each project, once:

$cheapag:allow

That's it. Ask Codex for changes like you always do.

You need

• Claude Code or Codex
• Node.js 20+
• An API key with a few dollars on it from one of the supported providers, or a local model with no key at all. A few dollars lasts hundreds of tasks.

It runs on macOS, Linux and Windows.

Windows: you also need Git for Windows (Git Bash). Known so far:

• The very first job can take about 2 minutes while the cheap model's engine (OpenCode) sets itself up. Later jobs start in seconds.
• If that engine crashes mid-session, Cheap Agent starts a new one, but the crashed copy can stay running (opencode.exe in Task Manager) until you end it or restart.
• The cheap model can't read your dependency folders (like node_modules) inside its copy of the project. Your tests still run normally.

Supported providers

#	Provider	Get a key	Good to know
1	OpenCode Go	opencode.ai	Set Regions to Global in its console for the DeepSeek models.
2	OpenRouter	openrouter.ai/keys	Pick this if unsure.
3	DeepSeek	platform.deepseek.com
4	Command Code	commandcode.ai	Needs a plan with API access.
5	OpenCode Zen	opencode.ai/zen	Pay-as-you-go.
6	Custom endpoint	Your own, if it needs one	A local model or any OpenAI-compatible API. How

The number is what you press at login. Log in to more than one and switch any time with /cheapag:provider.

Commands

Claude Code	Codex	What it does
/cheapag:allow	$cheapag:allow	Your OK to send this project's code to the cheap model. Once per project.
/cheapag:status	$cheapag:status	Recent jobs, and what the cheap model has cost you.
/cheapag:hook on	$cheapag:hook on	No more "I'll just do it myself": your frontier model must hand code changes to the cheap model.
/cheapag:clean	$cheapag:clean	Tidy up old job folders.
/cheapag:model	$cheapag:model	Pick the worker's main and fallback models, each with an effort.
/cheapag:provider	$cheapag:provider	Switch to another provider you've already logged in to, with no key prompt. This project's consent moves with it, and you see what it now covers. If the new provider fails its check, nothing changes. Add a new provider with npx cheap-agent login.

While a job runs, Claude Code shows the worker's latest step under the tool call, and Codex shows it each time it checks in (about every 15 seconds). To follow every step in a second terminal, run npx cheap-agent watch.

Settings

Optional. Put a cheapag.json in a project:

Setting	Default	What it does
takeover	"ask"	What happens when the cheap model couldn't finish a step. "ask": Claude asks you first, so nothing is spent without your choice. "sonnet": a Sonnet helper takes over automatically, often several hundred thousand Claude tokens on a hard task. "self": Claude does it, capped at 15 tool calls (limits.takeover_calls). Claude Code only; Codex asks in chat ("ask") or finishes it itself.
limits.max_turns	25	The most turns the cheap model gets per step.
limits.repro_by_turns	30	A bug-fix step that has edited nothing by this turn is stopped early (×2 medium, ×3 hard). The default lands past the 25-turn cap, so by default the worker runs to its cap; set it lower to stop sooner.
models	from setup	Which cheap models to use. Switch with npx cheap-agent login --preset strongest.
retention	{ "unlanded_worktree_days": 2, "job_log_days": 7 }	Days cleanup keeps an unlanded worktree and a job's log folder. It runs at server start and every hour.

Local model or your own endpoint

Not in the list of providers? Run npx cheap-agent login and pick Custom endpoint. It works with anything that speaks the OpenAI API: llama.cpp, Ollama, LM Studio, vLLM, LiteLLM, Azure, or a vendor's API. It asks for:

• URL, e.g. http://127.0.0.1:11434/v1 for Ollama. Plain http only works on this machine or your own network.
• API key, only if the endpoint needs one: the name of an environment variable, or a file, that holds it. Cheap Agent never reads the key itself.
• Model, picked from the endpoint's list.
• Context window and prices, both optional. Without prices, cost shows $0.

The model has to be good at tool calls; small local models often aren't. If jobs time out on a slow machine, raise limits.max_minutes (default 20).

Orchestrators and git worktrees

Cheap Agent works in the repository your session started in. If one session runs several tasks, each in its own git worktree (an orchestrator handing tickets to subagents, say), pass root with the worktree's absolute path on delegate, research, jobs, land and reply. Jobs then run, land and keep their records in that worktree, and the session's own checkout is untouched. Each worktree needs its own consent (/cheapag:allow there, or a copied .cheapag/consent.json). Without root, nothing changes.

---

You know the principal engineer. Twenty years in. Sees the whole system at once. Costs a fortune per hour.

You would never pay them to type out a CSV exporter.

But that's exactly what happens every time your frontier model (Claude Opus, GPT-6 Astra or Sol) writes your code: the most expensive model you have, reading files, typing boilerplate, re-running tests, burning through your plan.

Cheap Agent fixes the org chart. Your frontier model plans and decides. A model that costs half a cent per task does the typing, in its own copy of your project, and has to prove its work with a test before anything reaches you.

Why I built this

The idea: get $200-plan usage out of the $100 Claude plan, and $50–70 worth out of the $20 plan, with a few dollars of DeepSeek doing the typing.

I've met a lot of students, mostly in developing countries, who really want Opus for the hard problems and simply can't afford $100 a month. I wanted to find something that helps them.

This is a small effort from my side. It won't make Opus ten times cheaper. But stretching the plan you already pay for is something, and something is better than nothing.

📖 The full story (why I built it, how it works step by step, and the SWE-bench numbers): Cheap Agent: how I made my Claude plan last 2.2–2.7x longer

The numbers

Tested on SWE-bench Verified: real bugs from real open-source projects, graded by the official harness. Same prompts in Claude Code with Opus 5.5, with and without Cheap Agent.

<p align="center"> <img src="assets/chart.svg" width="880" alt="Opus tokens, Claude Code alone versus with Cheap Agent. Adding a feature: 154k vs 57k, 63% less, both pass all tests. 7 everyday bug fixes: 1.6M vs 655k, 59% less, 7 of 7 solved by both. 9 of the hardest bugs: 3.0M vs 1.3M, 55% less, 6 of 9 solved vs 7 of 9, with a Sonnet helper doing the leftovers."> </p>

What I won't hide:

• On the very hardest bugs it solved 6 of 9 where plain Opus solved 7 (on a single run plain Opus averages about 6 too).
• On tiny jobs (a few lines, or a whole small app from nothing), Opus is already quick, so there's nothing to save.

Cheap Agent shines on the work in between: real features and real fixes in real code. That's most of your day.

Before / after

The ask: "Add monthly budgets to the expense tracker, plus a CSV export. Tests for everything."

	Claude Code alone	Claude Code + Cheap Agent
Opus tokens	154k	57k
Opus turns	5	2
Who wrote the code	Opus	a cheap model, for $0.005
Tests	33 passing	38 passing

Opus wrote one task. The cheap model did the rest, tests included.

How it works

<p align="center"> <img src="assets/flow.svg" width="880" alt="How it works: Opus writes a short task; a cheap model works in its own copy of your project, writes a test that fails, fixes the code and makes the test pass; Cheap Agent runs the tests itself and only work that passes its checks lands, and a reproduction the server could not verify lands with a risk note, uncommitted; Opus reads a ten-line result and tells you. If the cheap model can't finish, a Sonnet helper finishes the step instead of Opus."> </p>

• Every change is proven. The cheap model must write a test that fails before its fix and passes after. Cheap Agent runs the tests itself; it doesn't take the model's word for it.
• Your project stays clean. Work happens in a private copy (a git worktree). Only work that passes its checks lands; a reproduction the server could not verify lands with a risk note. It lands uncommitted, so you review the diff like any other.
• Your frontier model stays in charge, but it's held to it: Cheap Agent's hooks stop it from quietly redoing work that already passed, or (in Claude Code) doing a failed step itself when Sonnet can.

FAQ

Is a half-cent model actually any good? On its own, no. With a written task from your frontier model, a test it has to pass, and a referee that runs that test, yes, most of the time. When it isn't, it says so and a stronger model takes over.

Does my frontier model check the work? The tests check the work, and Cheap Agent runs them. Opus checking every passing change cost three times the tokens and caught nothing in my runs, so it trusts a pass. You still review the diff before you commit.

Where does my code go? To the provider you picked, only after you run /cheapag:allow ($cheapag:allow in Codex) in that project, which also shows exactly which models will see it. Your API key stays on your machine, in a hidden prompt and a local credential store, never in chat.

Will it commit or push anything? Never. Changes land uncommitted. Your git, your call.

Why not just use Sonnet for everything? Sonnet still costs real usage on every line it types. The cheap model types for half a cent. Sonnet only gets called when the cheap model is stuck.

Can I use it at work, or build on it? Yes. It's MIT licensed: use it, change it, share it, at any company, for free (MIT License).

Why "Cheap Agent"? Because your plan isn't.

Contributing

PRs are welcome, and I'm more than happy to merge them. Setup, where things live, and how to add a provider are in CONTRIBUTING.md. For ideas and questions, come say hi on r/CheapAgent.

Update or remove

New versions are announced on the Releases page. Cheap Agent also tells you when a session starts if a new minor or major version is out; set CHEAPAG_NO_UPDATE_CHECK=1 to turn that off.

Update:

npx cheap-agent@latest

In Codex, also:

codex plugin marketplace upgrade

Remove (two commands):

claude plugin uninstall cheapag@cheapag

claude mcp remove -s user cheapag

In Codex:

codex plugin remove cheapag@cheap-agent