Cheap Labor

Resumen

Cheap Labor existe porque el uso de Codex es una cuota limitada, y la mayor parte de lo que hace un agente de codificación no es escribir código. Leer archivos, explorar el repositorio, planificar y revisar diffs consume la cuota de Codex sin escribir ni una línea de código.

Luego llegó la idea clave: el uso de ChatGPT y Codex se contabiliza por separado, dos cuotas independientes. Así que decidimos dividir el trabajo: ChatGPT hace todo el razonamiento con su propia cuota, y Codex se gasta solo en la implementación real.

Esa es toda la idea: un servidor MCP local conectado a través de un Secure MCP Tunnel: ChatGPT en la web controla un Codex CLI en tu máquina, sobre tu repositorio local, con un único disparador @cheap-labor.

Tecnologías

Cheap Labor está construido con una pila deliberadamente pequeña y multiplataforma:

• Runtime: Node.js (>= 20) — runtime del servidor puente

• Lenguaje: TypeScript — todo el código del puente

• Protocolo: MCP SDK (@modelcontextprotocol/sdk) — servidor y cliente MCP stdio

• Validación: zod — esquemas de argumentos de herramientas

• Ejecutor: Codex CLI (codex mcp-server) — cliente MCP hijo generado para exploración e implementación

• Conectividad: Secure MCP Tunnel (tunnel-client) — enlace privado solo de salida entre ChatGPT web y el servidor local

Related MCP server: Kontrol

Requisitos previos

• macOS o Linux con Node.js >= 20 + npm

• git

• Una cuenta de ChatGPT de pago con modo desarrollador

• Codex CLI, con sesión iniciada (codex login)

• tunnel-client — se instala durante la configuración: en macOS mediante Homebrew; en Linux mediante el binario de GitHub releases (linux-amd64/arm64) en tu PATH

• Un Secure MCP Tunnel + clave de API de runtime de la plataforma OpenAI (el instalador te indica las páginas correctas)

Instalación

Ir a: 1. Clonar e instalar → 2. Cómo usarlo

1. Clona el repositorio y entra en él:

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

2. Ejecuta el instalador — instala las dependencias, compila el puente, escribe tu perfil de túnel, valida las 23 herramientas y te guía paso a paso para conectar la app a ChatGPT web:

   ./scripts/install.sh

Cómo usarlo

1. Inicia el túnel — mantenlo en ejecución mientras uses cheap-labor:

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

2. Abre un nuevo chat de ChatGPT y escribe @cheap-labor — el mismo nombre de app que añadiste desde el menú de herramientas — y luego menciona el proyecto.

3. Confirma el directorio del proyecto cuando se te pregunte — la sesión queda armada.

Desinstalar

./scripts/uninstall.sh

Limpia todo lo que el script puede alcanzar: el registro MCP heredado, el demonio del túnel, el estado de .codex-bridge/ en cada proyecto inicializado, el perfil del túnel y la clave de API almacenada, y los artefactos de compilación. Tres avisos (pulsa Enter para la respuesta recomendada, n para conservar). Después imprime una guía de limpieza manual para las partes a las que solo tú puedes acceder: la conexión de la app de ChatGPT, el túnel de la plataforma, la clave de API de runtime y la carpeta del proyecto.

Cómo funciona

El puente está inactivo hasta que se arma. Mientras está inactivo, el servidor solo envía un aviso de dos líneas "ignora estas herramientas" como sus instructions, de modo que las indicaciones no relacionadas se responden sin que el puente se tenga en cuenta. Las reglas completas del flujo de trabajo viven en la carga de retorno de la herramienta init y entran en la conversación solo después de armarse.

El disparador es la propia invocación — sin monitoreo de indicaciones, sin sintaxis de etiquetas, sin escaneo de frases:

1. El usuario invoca cheap-labor escribiendo @cheap-labor. Ese es el único disparador.

2. ChatGPT pregunta qué proyecto quieres, lo resuelve (find_projects para nombres aproximados, create_project para directorios nuevos), confirma la ruta exacta contigo y luego arma la sesión — init(project) (o create_project directamente para un directorio completamente nuevo) y recibe un session_token.

3. Todas las demás herramientas se niegan a ejecutarse sin un session_token válido — una salvaguarda firme que también bloquea el uso accidental fuera del flujo de trabajo.

El flujo de trabajo

1. Arma la sesión — @cheap-labor + confirma el proyecto → init devuelve el token.

2. Comprende — git_status, list_tree, read_file, grep (todo gratis).

3. Planifica en detalle — ChatGPT escribe PLAN.md / SPEC.md / TASKS.md en la carpeta .codex-bridge/ del repositorio con plan_write. El plan son instrucciones exactas paso a paso: qué archivos crear/editar, qué debe cambiar en cada uno, qué comandos ejecutar y cómo verificar.

4. Ediciones pequeñas, hechas directamente — write_file / edit_file gestionan cambios de un solo archivo gratis.

5. Delega el trabajo pesado — implement entrega el plan a Codex, que ejecuta los pasos literalmente, ejecuta compilaciones/pruebas, arregla lo que se rompe y devuelve IMPLEMENTATION COMPLETE.

6. Revisa — ChatGPT lee el git diff devuelto y envía correcciones específicas de vuelta por el mismo bucle.

Características

• Activación con un solo disparador: @cheap-labor en cualquier chat de ChatGPT es el único disparador; el puente permanece inactivo (cero atención del modelo) hasta que se invoca — sin monitoreo de indicaciones, sin sintaxis de etiquetas, sin escaneo de frases.

• Ejecución con control de riesgo: los comandos se clasifican como de solo lectura o de riesgo; el trabajo arriesgado pasa por la revisión automática de Codex y tu veto.

• Salvaguardas de seguridad integradas: delimitación de rutas del proyecto, redacción de secretos, puntos de control antes de cada ejecución pesada y commits solo locales que nunca se envían.

• Multiplataforma: macOS y Linux, sin puertos públicos, túnel solo de salida.

Referencia de herramientas

Herramientas gratuitas del puente (E/S local determinista, sin coste de Codex):

Herramientas respaldadas por Codex (gastan la cuota de Codex):

Modelo de seguridad

• implement / deep_explore siempre pasan un sandbox explícito (workspace-write / read-only) — nunca danger-full-access.

• Modelo de Codex fijo — cada llamada a Codex fija gpt-5.6-luna con razonamiento medium y Fast Mode desactivado, pasado como anulaciones por llamada. El puente nunca escribe en ~/.codex/config.toml. La única excepción: deep_explore acepta un modelo más potente, pero solo después de que confirmes el cambio en el chat.

• Aprobaciones automáticamente seguras — las aprobaciones de shell de Codex se presentan como solicitudes de MCP: los comandos de solo lectura se aprueban automáticamente; cualquier cosa arriesgada (escrituras, red, mutaciones de git) se rechaza y se registra para que ChatGPT te la transmita para un veto. El veto se ejecuta con codex_reply.

• run_command ejecuta ejecutables directamente (sin shell). Los comandos arriesgados se delegan a la revisión automática de Codex — nunca acceso completo, nada arriesgado se ejecuta sin que se te pida.

• write_file solo crea archivos nuevos; edit_file solo edita archivos existentes mediante reemplazo por coincidencia exacta (las coincidencias obsoletas o ambiguas no escriben nada); edit_pack agrupa cambios de todo o nada. Todos limitan los tamaños y rechazan archivos binarios.

• Modo ship — checkpoint crea una instantánea de HEAD + el árbol de trabajo (se toma automáticamente antes de cada implement); rollback restaura un checkpoint (que a su vez se puede deshacer); git_commit hace commit localmente con un mensaje aprobado por el usuario. Push/pull/reset/rebase/checkout nunca se exponen.

• Las herramientas del puente rechazan rutas fuera del directorio del proyecto aprobado en la sesión.

• read_file / git_diff redactan patrones de secretos conocidos por defecto.

Estructura del proyecto

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

Pruebas

Para ejecutar las suites de pruebas unitarias:

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

Datos y registros locales

Cheap Labor guarda su perfil de túnel, la clave de API de ejecución y los registros del daemon localmente, fuera del directorio del proyecto:

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

Dentro de este directorio encontrarás:

• cheap-labor.yaml — el perfil de tunnel-client (contiene el id del túnel).

• cheap-labor.key — la clave de API de ejecución, chmod 600, nunca se hace commit.

• cheap-labor.log — el registro del daemon del túnel.

Los planes y los archivos de traspaso se escriben en la carpeta .codex-bridge/ de cada proyecto en tiempo de ejecución (ignorada por git). La configuración y la autenticación propias de Codex viven en ~/.codex/.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para ver el texto completo de la licencia.