cheap-agent-codex
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cheap-agent-codex delegate fixing the failing tests to a cheap worker in an isolated worktree"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cheap Agent for Codex
A standalone Codex integration for Cheap Agent. Codex plans and handles recovery; cheaper worker models perform research and implementation in isolated git worktrees. Successful changes land uncommitted for review.
What is included
MCP tools for delegation, research, job progress, blocked-job replies, and landing.
Six Codex skills:
$cheapag,$cheapag-plan,$cheapag-status,$cheapag-clean,$cheapag-hook, and$cheapag-allow.Codex lifecycle and tool hooks, including native
apply_patchsupport and per-turn recovery budgets.Install, diagnostics, and uninstall commands that preserve existing MCP servers, hooks, and user-edited skills.
The upstream worker, verification, model routing, cost limits, and cleanup engine.
Related MCP server: pi-mcp
Quick start
Requires Git and Node.js 20.11 or newer; Node 22+ is recommended with current Codex releases.
npm ci
npm run build
node dist/index.js codex installRestart Codex and review the Cheap Agent hooks in its Hooks settings. The installer never grants itself trust. It respects CODEX_HOME and defaults to ~/.codex.
Set up your worker provider from your own terminal:
node dist/index.js codex loginThe login flow accepts the API key through hidden terminal input and makes a tiny paid connectivity check. Do not paste keys into a chat. OpenCode Go, OpenRouter and DeepSeek are supported by the upstream engine.
Before sending a repository's code to the worker, review its provider and model route and personally grant consent from that repository:
node /absolute/path/to/cheap-agent-codex/dist/index.js allow
# Optional restrictions:
node /absolute/path/to/cheap-agent-codex/dist/index.js allow --zdr-only
node /absolute/path/to/cheap-agent-codex/dist/index.js allow --models provider/modelThen ask Codex to use $cheapag for a task. Installed skills contain the exact CLI path, so a global install is unnecessary. Keep this checkout in place after installation.
Commands
node dist/index.js codex doctor
node dist/index.js codex status
node dist/index.js codex hook on
node dist/index.js codex hook off
node dist/index.js codex clean
node dist/index.js codex uninstallThe edit guard is optional and off by default. It encourages delegation; it is not a security sandbox. External workers have their own permissions, and local command hooks require a compatible local Codex environment. See CODEX.md for behavior, consent, backups, removal, and limitations.
Development
npm run typecheck
npm test -- --maxWorkers=4
npm packThe suite includes isolated worker simulations and a full delegated worktree/verification/landing cycle. The Codex port was validated with 395 passing tests and 5 skipped, plus the real Codex configuration parser. Live paid model inference requires separate credentials and repository consent.
This repository is marked private in package.json to prevent accidental npm publication. Local packaging with npm pack remains available. The inherited cheapag executable is retained for compatibility; this port is not the public cheap-agent npm release.
Attribution
Based on Cheap Agent 1.2.5 by muaaz9329, upstream commit abe39a81f7e73a55f17493695d1138a98c7bce4c. The original MIT LICENSE and an upstream README snapshot are retained. Codex integration details are documented in CODEX.md.
Available Tools
6 toolsdelegateA
Make any code change: use this for every edit, including small, mechanical, "quick" or multi-file ones; those are exactly what the cheap worker is for, and your tokens cost the user far more than its. One call: task = what to change, which files, how to check. The worker edits an isolated worktree, runs the checks, and lands an OK result (uncommitted) in your working tree; read the result block instead of re-checking. Pass difficulty, rated from the issue as the time an engineer new to the code needs to fix and test it: easy < 15 min, medium < 1 h, hard > 1 h. For multi-step work pass plan + steps instead of task. Plan format: one "# " line, then per step a "## " heading followed by "files: ", "do: ", "done-when: " (optional "dont:", "needs: ", "difficulty: easy|medium|hard"), each key at the start of its line, not a bullet. In done-when, backticked text is run as a shell command that must succeed; put only commands in backticks.
Inputs: note, plan, task, wait, +6 more.
jobsA
List jobs, show a job's last result block again, wait for a job or batch to settle, or cancel a running job (keeps its worktree).
Inputs: action (required), job.
landA
Land or discard finished jobs that did not land (PARTIAL, FAIL, CONFLICT…). apply: 3-way applies a job's worktree changes to your working tree, uncommitted (a conflict leaves the tree untouched); discard: deletes its worktree. One line per job.
Inputs: job (required), action (required).
pingA
Check that the Cheap Agent server is running and report its version.
Inputs: no named parameters.
replyA
Answer a BLOCKED job's question and resume its worker in the same session. Returns the job's next result block (OK, FAIL, or BLOCKED again); for a job in a batch, the batch block at its next settlement.
Inputs: job (required), answer (required).
researchA
Find and explain code in this repository: asks the cheap read-only research worker a question (it reads the working tree, uncommitted changes included). Returns a short answer with path:line refs and a confidence; verify low-confidence answers before acting.
Inputs: question (required), paths, max_words.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a mostly distinct role: delegate creates work, reply unblocks existing work, jobs manages job state, land finalizes worktrees, research queries code, and ping checks health. There is some overlap because delegate, reply, and jobs can all return result blocks, but the descriptions make the intended entry points reasonably clear.
All names are short, lowercase, single-word commands, giving a consistent CLI-like style. The only notable deviation is 'jobs' as a plural noun while the others are mostly verbs, but the set remains predictable and readable.
Six tools is well-scoped for an asynchronous coding-worker orchestration server. Each tool covers a distinct lifecycle area, and none feels redundant or merely decorative.
The surface covers the full worker lifecycle: delegate work, research code, monitor/wait/cancel jobs, reply to blocked jobs, land or discard finished work, and health-check the server. No obvious dead ends are apparent for the stated purpose.
Related MCP Connectors
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceCoordinates parallel AI coding agents by providing task ownership, scoped file locks, handoffs, and verification workflows.MIT
- AlicenseNot gradedqualityBmaintenanceOrchestrates multiple coding agents at once so an MCP client can delegate implementation work while retaining judgment: each agent runs in its own isolated git worktree and branch, claims the files it edits, and communicates via a mailbox and shared board. Supports blocking questions to the orchestrator, Codex-written acceptance tests locked before workers start, scope validation, and reporting on first-pass success.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables a primary agent to dispatch, wait on, and supervise multiple parallel Codex CLI workers, each running in its own isolated Git worktree with conflict-checked path ownership. Persists every worker's state, goals, and event stream to disk so work can be tracked, resumed, reconnected, searched, and cancelled across restarts.433 npm3MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents and other MCP clients to hand bounded jobs to remote worker agents, track progress, and review reports or patches before accepting results, with repository access denied until explicitly granted and owner approval required.580 npmApache 2.0