cheap-agent
v1.4.3
Published
Make your Claude Code or Codex plan last longer: your frontier model plans, a cheap model writes the code. One command to install.
Maintainers
Readme
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 (OpenCode Go, OpenRouter recommended for a hosted one, DeepSeek,
Ollama for a local model with no key, Command Code, OpenCode Zen, or Custom endpoint for 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 Ollama, 5 Command Code, 6 OpenCode Zen, 7 Custom endpoint). If I picked Ollama Cloud, tell me to
export OLLAMA_API_KEY before running it. 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-agentPick 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:allowThat'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-agentAdd the plugin:
codex plugin marketplace add muaaz9329/cheap-agcodex plugin add cheapag@cheap-agentStart codex in your project and trust the 3 cheapag hooks when it asks. Then, in each project, once:
$cheapag:allowThat'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 Ollama, local or cloud, 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.exein 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 | Ollama | None for this machine; ollama.com for cloud | Local or cloud. Used by default when set up. How | | 5 | Command Code | commandcode.ai | Needs a plan with API access. | | 6 | OpenCode Zen | opencode.ai/zen | Pay-as-you-go. | | 7 | Custom endpoint | Your own, if it needs one | 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.
Ollama
Run npx cheap-agent login, pick Ollama, then one of its two endpoints:
- This machine: your own Ollama at
http://127.0.0.1:11434(it asks for the URL if yours differs). No key. It lists the models you have pulled and asks which one to use. Nothing leaves the machine, so/cheapag:allowtreats it as zero retention. - Ollama Cloud:
https://ollama.com/v1. ExportOLLAMA_API_KEYwhere Claude Code (or Codex) starts, then log in: it checks the key, lists the cloud model ids, and saves a preset (cheapest, balanced or strongest). Jobs fall back to the next cloud model when one hits a limit, and escalate to the strongest. The key stays in your environment and OpenCode reads it; Cheap Agent never sees or stores it.
Once set up, Ollama is used by default, even if you logged in to another provider earlier. To use another one, pick it with /cheapag:provider or set "provider" in ~/.config/cheapag/config.json.
On this machine's endpoint one model implements and researches. If models in a project's cheapag.json names a model from another provider, it is ignored, and ping, status and delegate say which model actually runs.
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, LM Studio, vLLM, LiteLLM, Azure, or a vendor's API. For Ollama, pick Ollama instead; it does the URL, model and context questions for you. The custom endpoint asks for:
- URL, e.g.
http://127.0.0.1:8080/v1for llama.cpp. Plainhttponly 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.
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
- 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@latestIn Codex, also:
codex plugin marketplace upgradeRemove (two commands):
claude plugin uninstall cheapag@cheapagclaude mcp remove -s user cheapagIn Codex:
codex plugin remove cheapag@cheap-agent