CodeHands (MCP Coding Harness)

Documentation source of truth

The authoritative current design, tool contracts, implementation priorities, and open decisions are maintained in docs/CURRENT_PLAN.md. Other documents provide focused background or setup guidance and must not duplicate the active plan.

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 modifies files inside it. Most runtime operations use exec-server JSON-RPC. The patch helper is built outside vendor/codex/ and links Codex's maintained codex-apply-patch crate as a source dependency. We never edit Codex's code.

---

The Codex Boundary (Critical Rule)