Skip to content
Back to search

cheap-agent

MarketplaceWorks with Claude CodeGitHub

Cheap Agent: your frontier model plans and reviews while a cheaper model implements, over MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/muaaz9329/cheap-ag with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/muaaz9329/cheap-ag'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/muaaz9329--cheap-ag/badge.svg)](/listings/muaaz9329--cheap-ag)

HTML

<a href="/listings/muaaz9329--cheap-ag"><img src="/api/listings/muaaz9329--cheap-ag/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Claude Code

**Easiest:** paste this into Claude Code. It asks what you want, then gives you one command to run.

Set up Cheap Agent (npm: cheap-agent) for me.
1. Ask me: which provider (OpenRouter recommended, DeepSeek, OpenCode Go or Command Code), and which
   models (balanced is the default; cheapest, strongest, or my own provider/model).
2. Check that node is 20+ and the claude CLI is installed.
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 number to pick for my provider (1 OpenCode Go, 2 OpenRouter,
   3 DeepSeek, 4 Command Code). I run it and type my API key there. Never ask for my key.
5. When I say done, check `claude mcp list` shows cheapag, then tell me to run
   /cheapag:allow in a new Claude Code session in my project.

**Or do it yourself:**

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](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 [OpenRouter](https://openrouter.ai/keys), [DeepSeek](https://platform.deepseek.com), [OpenCode Go](https://opencode.ai) or [Command Code](https://commandcode.ai) (Command Code needs a plan with API access; OpenCode Go needs Regions set to Global in its console for the DeepSeek models)

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.

---

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "cheap-agent",
  3. "description": "Cheap Agent: your frontier model plans and reviews while a cheaper model implements, over MCP.",
  4. "owner": { "name": "muaaz9329" },
  5. "plugins": [
  6. {
  7. "name": "cheapag",
  8. "source": "./plugin",
  9. "description": "Cheap Agent's MCP server, plan-writing skill, and /cheapag:status, /cheapag:allow, /cheapag:clean, and the opt-in edit guard (/cheapag:hook)."
  10. }
  11. ]
  12. }
README.md · README · 294 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">Cheap Agent</h1>
  2. <p align="center">
  3. <em>Your frontier model is a principal engineer. Stop paying it to type.</em>
  4. </p>
  5. <p align="center">
  6. <img src="https://img.shields.io/npm/v/cheap-agent?style=flat-square&color=111111&label=npm" alt="npm">
  7. <img src="https://img.shields.io/badge/for-Claude%20Code%20%7C%20Codex-111111?style=flat-square" alt="For Claude Code and Codex">
  8. <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">
  9. <img src="https://img.shields.io/badge/tested%20on-SWE--bench%20Verified-111111?style=flat-square" alt="Tested on SWE-bench Verified">
  10. <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT License">
  11. </p>
  12. <p align="center">
  13. <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.">
  14. </p>
  15. <p align="center">
  16. <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.">
  17. </p>
  18. <p align="center">
  19. <strong>Same feature. Same prompt. 63% fewer Opus tokens.</strong><br>
  20. <strong>Your Claude or ChatGPT plan lasts longer. Your code still ships with tests.</strong>
  21. </p>
  22. <p align="center">
  23. ⭐ Star it, and click <strong>Watch → Custom → Releases</strong> to hear when new versions ship.
  24. <br>💬 Questions, ideas and setups: <a href="https://www.reddit.com/r/CheapAgent/">r/CheapAgent</a>
  25. </p>
  26. ## Install
  27. Works in Claude Code and Codex. One login covers both.
  28. ### Let agent install
  29. 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.
  30. ```text
  31. Set up Cheap Agent (npm: cheap-agent) for me.
  32. 1. Ask me which provider (OpenCode Go, OpenRouter recommended for a hosted one, DeepSeek,
  33. Ollama for a local model with no key, Command Code, OpenCode Zen, or Custom endpoint for any OpenAI-compatible API)
  34. and which models (balanced is the default; cheapest, strongest, or my own provider/model).
  35. 2. Check that node is 20+, and whether I use Claude Code (claude CLI), Codex (codex CLI) or both.
  36. 3. If I picked my own model, save {"models":{"implement":"<model>"}} in
  37. ~/.config/cheapag/config.json, keeping what else is there.
  38. 4. Give me the command to run in my terminal: npx cheap-agent login --preset <my choice, or custom>,
  39. and which provider to pick with the arrow keys or its number (1 OpenCode Go, 2 OpenRouter,
  40. 3 DeepSeek, 4 Ollama, 5 Command Code, 6 OpenCode Zen, 7 Custom endpoint). If I picked Ollama Cloud, tell me to
  41. export OLLAMA_API_KEY before running it. If I don't use Claude Code, tell me
  42. to say no when it offers to add itself there. I run it and type my API key there. Never ask for my key.
  43. 5. When I say done: for Claude Code, check `claude mcp list` shows cheapag. For Codex, run
  44. `codex plugin marketplace add muaaz9329/cheap-ag` and `codex plugin add cheapag@cheap-agent`.
  45. 6. Tell me to open a new session in my project and run /cheapag:allow in Claude Code, or
  46. $cheapag:allow in Codex (trusting the 3 cheapag hooks when it asks).
  47. ```
  48. ### Claude Code
  49. ```bash
  50. npx cheap-agent
  51. ```
  52. 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.
  53. Then, in each project, once:
  54. ```
  55. /cheapag:allow
  56. ```
  57. **That's it.** Ask Claude for changes like you always do.
  58. ### Codex
  59. Log in (say no when it offers to add itself to Claude Code, if you don't use Claude):
  60. ```bash
  61. npx cheap-agent
  62. ```
  63. Add the plugin:
  64. ```bash
  65. codex plugin marketplace add muaaz9329/cheap-ag
  66. ```
  67. ```bash
  68. codex plugin add cheapag@cheap-agent
  69. ```
  70. Start `codex` in your project and trust the 3 cheapag hooks when it asks. Then, in each project, once:
  71. ```
  72. $cheapag:allow
  73. ```
  74. **That's it.** Ask Codex for changes like you always do.
  75. ### You need
  76. - [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex)
  77. - [Node.js](https://nodejs.org) 20+
  78. - An API key with a few dollars on it from one of the [supported providers](#supported-providers), or [Ollama](#ollama), local or cloud, or a local model with no key at all. A few dollars lasts hundreds of tasks.
  79. It runs on macOS, Linux and Windows.
  80. **Windows:** you also need [Git for Windows](https://git-scm.com/downloads/win) (Git Bash). Known so far:
  81. - The very first job can take about 2 minutes while the cheap model's engine (OpenCode) sets itself up. Later jobs start in seconds.
  82. - 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.
  83. - The cheap model can't read your dependency folders (like `node_modules`) inside its copy of the project. Your tests still run normally.
  84. ## Supported providers
  85. | # | Provider | Get a key | Good to know |
  86. |---|---|---|---|
  87. | 1 | OpenCode Go | [opencode.ai](https://opencode.ai) | Set Regions to Global in its console for the DeepSeek models. |
  88. | 2 | OpenRouter | [openrouter.ai/keys](https://openrouter.ai/keys) | Pick this if unsure. |
  89. | 3 | DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) | |
  90. | 4 | Ollama | None for this machine; [ollama.com](https://ollama.com) for cloud | Local or cloud. Used by default when set up. [How](#ollama) |
  91. | 5 | Command Code | [commandcode.ai](https://commandcode.ai) | Needs a plan with API access. |
  92. | 6 | OpenCode Zen | [opencode.ai/zen](https://opencode.ai/zen) | Pay-as-you-go. |
  93. | 7 | Custom endpoint | Your own, if it needs one | Any OpenAI-compatible API. [How](#local-model-or-your-own-endpoint) |
  94. The number is what you press at login. Log in to more than one and switch any time with `/cheapag:provider`.
  95. ## Ollama
  96. Run `npx cheap-agent login`, pick **Ollama**, then one of its two endpoints:
  97. - **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:allow` treats it as zero retention.
  98. - **Ollama Cloud**: `https://ollama.com/v1`. Export `OLLAMA_API_KEY` where 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.
  99. 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`.
  100. 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.
  101. ## Commands
  102. | Claude Code | Codex | What it does |
  103. |---|---|---|
  104. | `/cheapag:allow` | `$cheapag:allow` | Your OK to send this project's code to the cheap model. Once per project. |
  105. | `/cheapag:status` | `$cheapag:status` | Recent jobs, and what the cheap model has cost you. |
  106. | `/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. |
  107. | `/cheapag:clean` | `$cheapag:clean` | Tidy up old job folders. |
  108. | `/cheapag:model` | `$cheapag:model` | Pick the worker's main and fallback models, each with an effort. |
  109. | `/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`. |
  110. 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`.
  111. ## Settings
  112. Optional. Put a `cheapag.json` in a project:
  113. | Setting | Default | What it does |
  114. |---|---|---|
  115. | `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. |
  116. | `limits.max_turns` | `25` | The most turns the cheap model gets per step. |
  117. | `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. |
  118. | `models` | from setup | Which cheap models to use. Switch with `npx cheap-agent login --preset strongest`. |
  119. | `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. |
  120. ## Local model or your own endpoint
  121. 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:
  122. - **URL**, e.g. `http://127.0.0.1:8080/v1` for llama.cpp. Plain `http` only works on this machine or your own network.
  123. - **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.
  124. - **Model**, picked from the endpoint's list.
  125. - **Context window and prices**, both optional. Without prices, cost shows $0.
  126. 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).
  127. ## Orchestrators and git worktrees
  128. 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.
  129. ---
  130. You know the principal engineer. Twenty years in. Sees the whole system at once. Costs a fortune per hour.
  131. You would never pay them to type out a CSV exporter.
  132. 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.
  133. **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.
  134. ## Why I built this
  135. 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.
  136. 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.
  137. 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.
  138. 📖 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)**
  139. ## The numbers
  140. 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.
  141. <p align="center">
  142. <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.">
  143. </p>
  144. **What I won't hide:**
  145. - 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).
  146. - On tiny jobs (a few lines, or a whole small app from nothing), Opus is already quick, so there's nothing to save.
  147. Cheap Agent shines on the work in between: real features and real fixes in real code. That's most of your day.
  148. ## Before / after
  149. **The ask:** *"Add monthly budgets to the expense tracker, plus a CSV export. Tests for everything."*
  150. | | Claude Code alone | Claude Code + Cheap Agent |
  151. |---|---|---|
  152. | Opus tokens | 154k | **57k** |
  153. | Opus turns | 5 | **2** |
  154. | Who wrote the code | Opus | a cheap model, for **$0.005** |
  155. | Tests | 33 passing | **38 passing** |
  156. Opus wrote one task. The cheap model did the rest, tests included.
  157. ## How it works
  158. <p align="center">
  159. <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.">
  160. </p>
  161. - **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.
  162. - **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.
  163. - **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.
  164. ## FAQ
  165. **Is a half-cent model actually any good?**
  166. 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.
  167. **Does my frontier model check the work?**
  168. 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.
  169. **Where does my code go?**
  170. 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.
  171. **Will it commit or push anything?**
  172. Never. Changes land uncommitted. Your git, your call.
  173. **Why not just use Sonnet for everything?**
  174. 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.
  175. **Can I use it at work, or build on it?**
  176. Yes. It's MIT licensed: use it, change it, share it, at any company, for free ([MIT License](./LICENSE)).
  177. **Why "Cheap Agent"?**
  178. Because your plan isn't.
  179. ## Contributing
  180. 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/).
  181. ## Update or remove
  182. 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.
  183. **Update:**
  184. ```bash
  185. npx cheap-agent@latest
  186. ```
  187. In Codex, also:
  188. ```bash
  189. codex plugin marketplace upgrade
  190. ```
  191. **Remove** (two commands):
  192. ```bash
  193. claude plugin uninstall cheapag@cheapag
  194. ```
  195. ```bash
  196. claude mcp remove -s user cheapag
  197. ```
  198. In Codex:
  199. ```bash
  200. codex plugin remove cheapag@cheap-agent
  201. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.