Cheap Labor

Abstract

Cheap Labor exists because Codex usage is a limited pool — and most of what a coding agent does is not writing code. Reading files, exploring the repo, planning, and reviewing diffs all burn the Codex allowance without ever writing code.

Then came the key realization: ChatGPT and Codex usage are counted separately — two independent allowances. So we decided to split the work: ChatGPT does all the thinking on its own allowance, and Codex is spent only on real implementation.

That's the whole idea — a local MCP server joined over a Secure MCP Tunnel: ChatGPT on the web drives a Codex CLI on your machine, over your local repo, with a single @cheap-labor trigger.

Built With

Cheap Labor is built with a deliberately small, cross-platform stack:

• Runtime: Node.js (>= 20) — bridge server runtime

• Language: TypeScript — all bridge code

• Protocol: MCP SDK (@modelcontextprotocol/sdk) — stdio MCP server + client

• Validation: zod — tool argument schemas

• Executor: Codex CLI (codex mcp-server) — spawned child MCP client for exploration and implementation

• Connectivity: Secure MCP Tunnel (tunnel-client) — private, outbound-only link between ChatGPT web and the local server

Related MCP server: Kontrol

Prerequisites

• macOS or Linux with Node.js >= 20 + npm

• git

• A paid ChatGPT account with developer mode

• Codex CLI, logged in (codex login)

• tunnel-client — installed during setup: macOS via Homebrew; Linux via the GitHub releases binary (linux-amd64/arm64) on your PATH

• A Secure MCP Tunnel + runtime API key from the OpenAI platform (the installer points you to the right pages)

Installation

Jump to: 1. Clone & install → 2. Use it

1. Clone the repo and move into it:

   git clone https://github.com/psrisuphan/cheap-labor.git
   cd cheap-labor

2. Run the installer — it installs deps, builds the bridge, writes your tunnel profile, validates all 23 tools, and walks you through connecting the app to ChatGPT web:

   ./scripts/install.sh

Use It

1. Start the tunnel — keep it running while you use cheap-labor:

   ./scripts/tunnel.sh start    # stop: ./scripts/tunnel.sh stop

2. Open a new ChatGPT chat and type @cheap-labor — the same app name you added from the tools menu — then mention the project.

3. Confirm the project directory when asked — the session is armed.

Uninstall

./scripts/uninstall.sh

Cleans up everything the script can reach: legacy MCP registration, the tunnel daemon, .codex-bridge/ state in every initialized project, the tunnel profile and stored API key, and the build artifacts. Three prompts (press Enter for the recommended answer, n to keep). Afterwards it prints a manual cleanup guide for the parts only you can reach: the ChatGPT app connection, the Platform tunnel, the runtime API key, and the project folder.

How It Works

The bridge is dormant until armed. While dormant, the server ships only a two-line "ignore these tools" notice as its instructions, so unrelated prompts are answered without the bridge ever being considered. The full workflow rules live in the init tool's return payload and enter the conversation only after arming.

The trigger is the invocation itself — no prompt monitoring, no tag syntax, no phrase scanning:

1. The user invokes cheap-labor by typing @cheap-labor. That's the only trigger.

2. ChatGPT asks which project you want, resolves it (find_projects for fuzzy names, create_project for new directories), confirms the exact path with you, then arms the session — init(project) (or create_project directly for a brand-new directory) and receives a session_token.

3. Every other tool refuses to run without a valid session_token — a hard backstop that also blocks accidental use outside the workflow.

The Workflow

1. Arm the session — @cheap-labor + confirm the project → init returns the token.

2. Understand — git_status, list_tree, read_file, grep (all free).

3. Plan in detail — ChatGPT writes PLAN.md / SPEC.md / TASKS.md into the repo's .codex-bridge/ folder with plan_write. The plan is exact step-by-step instructions: which files to create/edit, what each change should be, which commands to run, and how to verify.

4. Small edits, done directly — write_file / edit_file handle one-file changes for free.

5. Delegate heavy work — implement hands the plan to Codex, which executes the steps literally, runs builds/tests, fixes what breaks, and returns IMPLEMENTATION COMPLETE.

6. Review — ChatGPT reads the returned git diff and sends targeted corrections back through the same loop.

Features

• One-Trigger Activation: @cheap-labor in any ChatGPT chat is the only trigger; the bridge stays dormant (zero model attention) until invoked — no prompt monitoring, no tag syntax, no phrase scanning.

• Risk-Gated Execution: commands classified read-only vs. risky; risky work goes through Codex auto-review and your veto.

• Built-In Safety Rails: project path scoping, secret redaction, checkpoints before every heavy run, and local-only commits that never push.

• Cross-Platform: macOS and Linux, no public ports, outbound-only tunnel.

Tools Reference

Free bridge tools (deterministic local I/O, no Codex cost):

Codex-backed tools (spend the Codex pool):

Safety Model

• implement / deep_explore always pass an explicit sandbox (workspace-write / read-only) — never danger-full-access.

• Fixed Codex model — every Codex call pins gpt-5.6-luna with medium reasoning and Fast Mode off, passed as per-call overrides. The bridge never writes to ~/.codex/config.toml. The one exception: deep_explore accepts a stronger model, but only after you confirm the change in chat.

• Auto-safe approvals — Codex shell approvals surface as MCP elicitations: read-only commands are auto-approved; anything risky (writes, network, git mutations) is declined and recorded so ChatGPT relays it to you for a veto. The veto is executed with codex_reply.

• run_command runs executables directly (no shell). Risky commands are delegated to Codex's auto-review — never full access, nothing risky runs unprompted.

• write_file only creates new files; edit_file only edits existing ones via exact-match replacement (stale/ambiguous matches write nothing); edit_pack batches all-or-nothing. All cap sizes and refuse binary files.

• Ship mode — checkpoint snapshots HEAD + working tree (taken automatically before every implement); rollback restores a checkpoint (itself undoable); git_commit commits locally with a user-approved message. Push/pull/reset/rebase/checkout are never exposed.

• Bridge tools refuse paths outside the session-approved project directory.

• read_file / git_diff redact known secret patterns by default.

Project Structure

cheap-labor/
├── assets/                  # Logo / icons
├── scripts/                 # Installer, uninstaller, tunnel control, setup
│   ├── install.sh           # All-in-one installer
│   ├── uninstall.sh         # Clean uninstaller
│   ├── tunnel-setup.sh      # Writes the tunnel-client profile
│   ├── tunnel.sh            # start / stop / restart / status / logs the tunnel daemon
│   └── setup.mjs            # Prerequisite check
├── src/                     # Bridge MCP server
│   ├── index.ts             # Server entry, tool registration, server instructions
│   ├── safety.ts            # Project scoping, redaction, risk classification
│   ├── projects.ts          # Session approvals, ledger, find/create
│   ├── planstore.ts         # .codex-bridge/ I/O
│   ├── approvals.ts         # Auto-safe policy
│   └── tools/               # context, command, codexCommand, codex, deepExplore,
│                            # implement, edit, plans, ship
├── tests/                   # Node test suite
├── dist/                    # Build output (gitignored)
└── package.json

Testing

To run the unit test suites:

npm run typecheck    # tsc --noEmit
npm test             # node --test (tsx)

Local Data & Logs

Cheap Labor stores its tunnel profile, runtime API key, and daemon logs locally, outside the project directory:

• macOS / Linux: ~/.config/tunnel-client/

Inside this directory you will find:

• cheap-labor.yaml — the tunnel-client profile (contains the tunnel id).

• cheap-labor.key — the runtime API key, chmod 600, never committed.

• cheap-labor.log — the tunnel daemon log.

Plans and handoff files are written into each project's .codex-bridge/ folder at runtime (gitignored). Codex's own configuration and auth live in ~/.codex/.

License

This project is licensed under the MIT License. See the LICENSE file for the full license text.