CodeHands (MCP Coding Harness)

The Problem

Web AI assistants like ChatGPT and Claude Chat are incredibly smart — they can reason about code, plan fixes, and write solutions. But they're trapped behind a browser. They can't reach into your computer to actually read your files, edit your code, or run your tests. The brain is there, but it has no hands.

Meanwhile, tools like Cursor and Codex CLI work great locally — but only from one specific app on one specific machine. You can't use them from your phone, from a different browser, or from ChatGPT's interface.

The Vision

Code from anywhere. Open ChatGPT or Claude Chat on your phone, your tablet, any browser, any device — type "fix the null check in src/app.ts line 42" — and it happens on your development machine. The AI thinks, your machine executes.

What This Is

A thin MCP server that gives web AI assistants (ChatGPT, Claude Chat) step-by-step control over your local development machine.

The web AI is the brain. This server is just the hands.

This server does not think. It does not make coding decisions. It does not run an agent loop. It only routes commands and enforces safety rules.

---

The Three Layers

┌─────────────────────────────────────────────────────────┐
│  BRAIN: Web AI (ChatGPT / Claude Chat)                  │
│  Decides what to read, edit, and run. Controls step     │
│  by step. IS the agent loop.                            │
└────────────────────────┬────────────────────────────────┘
                         │ MCP tool calls
                         ▼
┌─────────────────────────────────────────────────────────┐
│  ROUTER: CodeHands (this MCP server, TypeScript)        │
│  Receives each tool call. Checks policy (is this        │
│  workspace approved?). Forwards to exec-server.         │
│  Returns results. Logs activity.                        │
│  Never makes coding decisions.                          │
└────────────────────────┬────────────────────────────────┘
                         │ JSON-RPC
                         ▼
┌─────────────────────────────────────────────────────────┐
│  EXECUTOR: Codex exec-server (lean Rust process)        │
│  Actually reads/writes files, runs terminal commands,   │
│  manages sandboxing and safety. All the hard low-level  │
│  work. Already built, open-source, battle-tested.       │
└─────────────────────────────────────────────────────────┘

The web AI says "read this file" → this server checks policy → Codex reads the file → result flows back to the web AI. Every operation follows this path.

---

Why Codex CLI (The Hard Reality)

To make this vision work, the server needs to actually do things on your machine: read files safely, write files safely, run terminal commands in a sandbox, manage Git, validate paths. Building all of that from scratch is a massive amount of work — sandboxing alone is months of effort.

OpenAI already solved this problem. Their Codex CLI is open-source (Apache 2.0), lightweight, Rust-based, ranked #1 on Terminal-Bench. It handles file I/O, terminal execution, sandboxing, Git, and safety — all battle-tested.

So instead of rebuilding the wheel, we use their wheel. We clone Codex CLI into our project and talk to it through its public interface. Our code never goes inside it. We never touch Codex's code. Ever.

---

The Codex Boundary (Critical Rule)

vendor/codex/ is a clone of the OpenAI Codex repository. It is never modified. No harness code goes inside it. No patches, no edits, no exceptions.

All our code lives OUTSIDE that folder. The entire harness is built around Codex, not inside it.

Why this matters: OpenAI actively updates Codex CLI on GitHub. When they release improvements — better sandboxing, new features, performance fixes — we want those updates instantly. Because we never touched their code, upgrading is one command:

git submodule update --remote vendor/codex

No merge conflicts. No broken patches