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

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

Clone the repo and move into it:

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

Run the installer — it installs deps, builds the bridge, writes your tunnel profile, validates all 25 tools, and walks you through connecting the app to ChatGPT web:
```
./scripts/install.sh
```

Use It

Start the tunnel — keep it running while you use cheap-labor:
```
./scripts/tunnel.sh start    # stop: ./scripts/tunnel.sh stop
```
Open a new ChatGPT chat and type @cheap-labor (or whatever you named the app/plugin when creating it).
Confirm the project directory when asked — the session is armed.
Approval Mode — defaults to normal (asks you before running every command). Switch to auto-approve (GPT decides the risk) with @cheap-labor, switch to auto-approve.

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 short "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:

The user invokes cheap-labor by typing @cheap-labor. That's the only trigger.
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.
Every other tool refuses to run without a valid session_token — a hard backstop that also blocks accidental use outside the workflow.

The Workflow

Arm the session — @cheap-labor + confirm the project → init returns the token.
Understand — git_status, list_tree, read_file, grep (all free).
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.
Small edits, done directly — write_file / edit_file handle one-file changes for free.
Delegate heavy work — implement hands the plan to Codex, which executes the steps literally, runs builds/tests, fixes what breaks, and returns IMPLEMENTATION COMPLETE.
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.
Three-Bucket Command Safety: provably-safe read-only commands (git status/log/diff, ls, cat, grep, …) run freely; dangerous ones (file deletes, git rewrites, network installs, interpreter one-liners) always require your explicit approval; everything else depends on the approval mode — ask first (normal, default) or let ChatGPT judge safe commands itself (auto). Switch modes in chat any time with set_approval_mode.
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):

Tool	Purpose
`init`	Arm the session for a project (the single entry point); returns the `session_token` + an operation-mode brief
`list_tree`	Directory structure, depth-limited
`read_file`	File contents, line-ranged, size-capped, secrets redacted (`redact_secrets: false` to disable)
`grep`	Regex search with path-aware include/exclude globs (`.ts`, `src//.ts`), secrets redacted (`redact_secrets: false` to disable)
`git_status` / `git_diff` / `git_log`	Repo state + the review loop (untracked files surfaced)
`run_command`	Three-bucket execution (tests, build, typecheck): safe allowlist runs freely; dangerous commands always need your approval; the rest follows the approval mode. Output secrets redacted (`redact_secrets: false` to disable)
`set_approval_mode`	Switch the global approval mode — `normal` (ask first) or `auto` (ChatGPT judges safe commands itself); dangerous commands always ask
`get_settings`	Read current bridge settings (e.g. the approval mode)
`write_file`	Create a new file directly (refuses to overwrite)
`edit_file`	Exact-match edit of an existing file (content-based stale guard)
`edit_pack`	Batch edits/writes after validating every guard before application
`checkpoint`	Snapshot HEAD + working tree for rollback (auto before `implement`)
`rollback`	Restore to a checkpoint (user-confirmed; itself undoable)
`git_commit`	Stage + commit locally with a user-approved message; refuses existing staged work and never pushes
`checkpoints`	List recorded checkpoints
`find_projects`	Resolve fuzzy names to candidate paths (shallow, well-known locations)
`create_project`	Create a new project directory (no git init); returns a `session_token`
`plan_read` / `plan_write` / `task_update`	Manage `.codex-bridge/` handoff files

Codex-backed tools (spend the Codex pool):

Tool	Purpose
`deep_explore`	Read-only Codex session for questions free tools can't answer (model upgrade per-call with your confirmation)
`implement`	Workspace-write Codex on the current plan; returns summary + `git diff` (model upgrade per-call with your confirmation)
`codex_reply`	Continue a session by thread id (approval veto loop, follow-ups); bound to the project that created it

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: implement / deep_explore accept a stronger model (e.g. gpt-5.6-sol), but the bridge refuses it unless the call passes model_confirmed: true — set only after you explicitly agree to that exact model in chat. Per-call: each non-default model run needs its own confirmation.
Auto-safe approvals — Codex shell approvals surface as MCP elicitations: commands on the provably-safe allowlist are auto-approved; dangerous ones (writes, network, git mutations, interpreter one-liners) are always declined — in auto mode too — and recorded so ChatGPT relays them to you for a veto. The veto is executed with codex_reply.
Approval modes — run_command buckets every command. The safe allowlist (git status/log/diff/show/rev-parse, ls, cat, pwd, echo, grep, rg, sort, uniq, wc, head, tail, printf, date) always runs. Dangerous commands (file deletion/overwrite, git rewrites, network installs, interpreter one-liners) always require your approval — the bridge refuses them without approved: true. Everything else follows the mode: normal (default) asks you first; auto lets ChatGPT judge safe commands itself but still makes it ask you for dangerous ones. Change it any time with set_approval_mode — it applies to every chat immediately.
write_file only creates new files; edit_file only edits existing ones via exact-match replacement (stale/ambiguous matches write nothing); edit_pack validates the full batch before applying it. 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 refuses a non-empty index, then 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.
Git-backed tools require the approved project to be the repository root, preventing nested projects from affecting sibling directories.
read_file / grep / git_diff / run_command redact known secret patterns by default; pass redact_secrets: false when a task genuinely needs the raw content.

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
│   ├── git.ts               # Exact repository-root boundary for Git-backed tools
│   ├── safety.ts            # Project scoping, redaction, risk classification, command buckets
│   ├── projects.ts          # Session approvals, ledger, find/create
│   ├── planstore.ts         # .codex-bridge/ I/O
│   ├── settings.ts          # Approval mode (normal / auto)
│   ├── approvals.ts         # Auto-safe policy
│   ├── skips.ts             # Shared directory-skip list
│   └── tools/               # context, command, 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)
npm run build        # tsc → dist/

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.

Bridge settings (the approval mode) live in ~/.codex/cheap-labor-settings.json (chmod 600), and the list of initialized projects in ~/.codex/cheap-labor-approved-projects.json (read by the uninstaller to purge .codex-bridge/ state).

Plans and handoff files are written into each project's .codex-bridge/ folder at runtime (gitignored). Checkpoint metadata is stored under Git's private directory and snapshots are pinned under refs/bridge-checkpoints/. 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.

Cheap Labor