Cheap Agent
Your frontier model is a principal engineer. Stop paying it to type.
Same feature. Same prompt. 63% fewer Opus tokens.
Your Claude or ChatGPT plan lasts longer. Your code still ships with tests.
⭐ Star it, and click Watch → Custom → Releases to hear when new versions ship.
💬 Questions, ideas and setups: r/CheapAgent
## 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.
```text
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":""}} 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 ,
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
```bash
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):
```bash
npx cheap-agent
```
Add the plugin:
```bash
codex plugin marketplace add muaaz9329/cheap-ag
```
```bash
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](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex)
- [Node.js](https://nodejs.org) 20+
- An API key with a few dollars on it from one of the [supported providers](#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](https://git-scm.com/downloads/win) (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](https://opencode.ai) | Set Regions to Global in its console for the DeepSeek models. |
| 2 | OpenRouter | [openrouter.ai/keys](https://openrouter.ai/keys) | Pick this if unsure. |
| 3 | DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) | |
| 4 | Command Code | [commandcode.ai](https://commandcode.ai) | Needs a plan with API access. |
| 5 | OpenCode Zen | [opencode.ai/zen](https://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](#local-model-or-your-own-endpoint) |
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](https://muaazkhan.me/blog/cheap-agent)**
## The numbers
Tested on [SWE-bench Verified](https://www.swebench.com): 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](./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](./CONTRIBUTING.md). For ideas and questions, come say hi on [r/CheapAgent](https://www.reddit.com/r/CheapAgent/).
## Update or remove
New versions are announced on the [Releases page](https://github.com/muaaz9329/cheap-ag/releases). 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:**
```bash
npx cheap-agent@latest
```
In Codex, also:
```bash
codex plugin marketplace upgrade
```
**Remove** (two commands):
```bash
claude plugin uninstall cheapag@cheapag
```
```bash
claude mcp remove -s user cheapag
```
In Codex:
```bash
codex plugin remove cheapag@cheap-agent
```