Skip to main content
Glama

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_patch support 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 install

Restart 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 login

The 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/model

Then 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 uninstall

The 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 pack

The 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 tools
delegateA

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

    A4.1/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Orchestrates 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.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      Apache 2.0