Pi (pi.dev): el harness minimalista para agentes de programación y cómo se compara

A principios de 2026, buena parte de la atención en torno a los agentes se centró en OpenClaw, el agente conectado a servicios de mensajería que se volvió viral y después se convirtió en la base de un ecosistema más amplio. Debajo de esa superficie hay un proyecto más pequeño con una propuesta distinta: Pi, el harness minimalista de terminal para programación en pi.dev.

Pi no intenta ser el agente de programación con más funcionalidades. Busca ser el harness útil más pequeño que puedas extender, integrar y entender. Esa decisión de diseño importa si te interesan la ingeniería de contexto, la observabilidad de sesiones, la portabilidad entre proveedores o la creación de tu propio producto de agentes sobre una base estable.

El July 7, 2026, volví a contrastar Pi con su sitio oficial, su documentación, el README de GitHub, el ensayo de Mario Zechner de November 2025 sobre su creación y el análisis práctico de Armin Ronacher de January 2026. La propuesta se sostiene: Pi es una herramienta que pone el harness en primer lugar, dirigida a ingenieros que quieren controlar qué entra en el contexto del modelo y cómo se comportan los loops de agentes, no un producto de IDE cerrado.

TL;DR

• Pi es un harness minimalista de terminal para programación creado por Mario Zechner (badlogic/pi-mono). Incluye cuatro herramientas predeterminadas (read, write, edit, bash), un system prompt muy pequeño y hooks de extensión para todo lo demás.
• Para qué sirve: programación interactiva en terminal, ejecuciones automatizadas con pi -p, integración mediante RPC y uso integrado mediante el SDK; en particular, así es como OpenClaw integra createAgentSession() de @earendil-works/pi-coding-agent.
• Frente a Claude Code, Cursor, Codex y OpenCode: Pi renuncia al modo de planificación, MCP, subagentes, ventanas de permisos y bash en segundo plano integrados a cambio de observabilidad, control del contexto y capacidad de extenderse a sí mismo.
• Patrón de handoff: sesiones con estructura de árbol, ramificación y retroceso (/tree, /fork), planes basados en archivos (PLAN.md, TODO.md) y subsesiones de pi --print para revisión, en lugar de subagentes opacos dentro de la sesión.
• Cuándo gana Pi: para quienes construyen harnesses, trabajan con ingeniería de contexto o flujos multimodelo, y para equipos que quieren que el agente se extienda a sí mismo en vez de instalar una matriz de funcionalidades.
• Cuándo pierde Pi: para equipos que trabajan principalmente en el IDE, usuarios que quieren MCP o modo de planificación listos para usar y quienes necesitan controles de permisos sin tener que construirlos.

Qué aprenderás aquí

• Qué es Pi, qué problema resuelve y cómo está estructurado su monorepo
• Cómo se compara Pi con Claude Code, Cursor, Codex CLI y OpenCode en filosofía y flujo de trabajo
• Casos de uso comunes y patrones de handoff que sustituyen a los subagentes integrados y al modo de planificación
• Ventajas del enfoque de harness minimalista y sus límites, sin rodeos
• Una tabla de decisión para elegir entre Pi y productos cerrados

¿Qué es Pi?

Pi es un harness minimalista de terminal para programación: una CLI y un SDK que conectan un proveedor de modelos, un loop de agente, almacenamiento de sesiones y una interfaz de terminal. El sitio del producto en pi.dev lo describe como «un harness minimalista para agentes» que adaptas a tus flujos de trabajo, y no al revés.

La implementación está en el monorepo de código abierto badlogic/pi-mono. A July 2026, el repositorio agrupa cuatro capas principales:

Instálalo de forma global:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# or
curl -fsSL https://pi.dev/install.sh | sh

Después, autentícate con /login (OAuth de suscripción) o con una clave de API como ANTHROPIC_API_KEY, y ejecuta pi en el directorio de un proyecto.

Funcionalidades predeterminadas

Los valores predeterminados de Pi son deliberadamente reducidos. El README oficial indica que el modelo recibe cuatro herramientas: read, write, edit y bash. El ensayo de Mario Zechner del November 30, 2025 publica el system prompt completo; en conjunto, el prompt y las definiciones de herramientas se mantienen por debajo de ~1,000 tokens, mucho menos que los prompts de los harnesses nativos de Claude Code, Codex o stacks derivados de OpenCode.

Ese núcleo pequeño es la propuesta central del producto: menos funcionalidades integradas implican menos inyecciones ocultas de contexto y menos cambios de comportamiento que no elegiste.

Cuatro modos de ejecución

Pi no es solo una TUI interactiva. La documentación oficial enumera cuatro modos:

1. Interactivo — sesión completa de terminal con comandos de barra y extensiones
2. Print / JSON — pi -p "query" para scripts; --mode json para streams de eventos estructurados
3. RPC — protocolo JSON sobre stdin/stdout para integraciones fuera de Node
4. SDK — integra Pi en aplicaciones Node.js mediante createAgentSession()

OpenClaw es la «integración de SDK en un caso real» por excelencia que cita la documentación de Pi: importa Pi directamente en lugar de ejecutarlo como subproceso, lo que da al gateway control total sobre las sesiones, herramientas y prompts.

Para qué sirve Pi

Pi se dirige a tres públicos que se superponen:

1. Desarrolladores que programan a diario en la terminal y quieren una TUI rápida, con poco parpadeo, y cambiar de modelo durante una sesión entre 15+ proveedores
2. Creadores de harnesses que integran loops de agentes en gateways, bots o herramientas internas (OpenClaw es el ejemplo más destacado)
3. Ingenieros de contexto que necesitan ver, filtrar y personalizar todo lo que entra en la ventana de contexto del modelo

Pi declara explícitamente que no intenta ser:

• un IDE (como Cursor)
• una shell empresarial sujeta a permisos (como los flujos de aprobación de Claude Code)
• un host MCP (como Codex, Claude Code o Cursor con MCP habilitado)
• un orquestador multiagente con todo incluido (como los subagentes de Claude Code o los agentes en segundo plano de Cursor)

En cambio, la documentación y la página de filosofía de Pi dicen que, si quieres subagentes, modo de planificación, MCP, listas de tareas o bash en segundo plano, le pidas a Pi que construya una extensión, uses tmux, escribas archivos o instales un paquete de pi, o bien uses otro producto.

Es una decisión de diseño, no una funcionalidad pendiente en la hoja de ruta.

Arquitectura de un vistazo

User prompt
    |
    v
+------------------+
|  pi-coding-agent |  AGENTS.md / SYSTEM.md / skills / extensions
|  (CLI or SDK)    |
+--------+---------+
         |
         v
+------------------+
|  pi-agent-core   |  tool loop, steering, follow-up queue
+--------+---------+
         |
         v
+------------------+
|     pi-ai        |  provider routing, context handoff, cost tracking
+--------+---------+
         |
         v
    LLM provider(s)

La distinción entre dirección y seguimiento es una primitiva útil para el flujo de trabajo. Mientras el agente trabaja:

• Enter envía un mensaje de dirección (se entrega después de la herramienta actual y puede interrumpir las herramientas restantes)
• Alt+Enter envía un mensaje de seguimiento (queda en cola hasta que el agente termina)

Esto permite mantener a una persona en el loop sin lanzar subagentes opacos.

Pi frente a las alternativas populares

Ningún harness gana en todas las tareas. Pi se diferencia por su minimalismo arquitectónico y extensibilidad, no por perseguir el primer lugar en los benchmarks.

Matriz comparativa

La tabla combina documentación oficial de los productos con criterio editorial sobre la «mejor opción». Vuelve a consultar la documentación de los proveedores antes de asumir compromisos para producción.

Frente a Claude Code

Claude Code es el competidor más cercano en filosofía: nativo de terminal, basado en agentes y sólido para trabajar en todo un repositorio. El ensayo de Mario Zechner sobre la creación de Pi (November 30, 2025) identifica los problemas que lo motivaron: Claude Code incorporó funcionalidades y cambiaba los system prompts y las herramientas entre versiones, lo que rompía flujos personales estables.

La respuesta de Pi:

• Prompt minimalista fijo que puedes reemplazar por completo mediante SYSTEM.md
• Sin subagentes integrados — lanzas pi --print y mantienes la salida visible
• Sin modo de planificación — colaboras en PLAN.md con observabilidad completa de los comandos
• tmux en lugar de bash en segundo plano — los procesos de larga duración siguen siendo inspeccionables

Claude Code sigue ganando cuando quieres Plan Mode nativo de Anthropic, subagentes, integraciones con IDE y flujos de permisos sin tener que construirlos.

Frente a Cursor

Cursor está optimizado para la planificación y ejecución nativas del IDE: agentes en segundo plano, revisión de PR dentro del editor, automatizaciones de Slack y flujos visuales de diff. Pi no compite en ergonomía de IDE.

Elige Cursor cuando el equipo trabaja principalmente en el editor y quiere agentes asíncronos en la nube. Elige Pi cuando el loop deba poder automatizarse desde la terminal, integrarse en otros productos y ofrecer transparencia sobre el contexto.

Frente a Codex CLI

Las herramientas Codex de OpenAI están orientadas a la automatización con modelos de OpenAI y cuentan con interfaces de IDE y nube en expansión. Pi es independiente del proveedor por diseño; según la lista oficial de proveedores, incluye OAuth para Claude Pro/Max, suscripciones de ChatGPT/Codex y GitHub Copilot.

La capa pi-ai de Pi también admite handoff de contexto entre proveedores (con salvedades documentadas para las trazas de razonamiento y los blobs firmados). Esto importa para dirigir tareas según su costo o hacer pruebas A/B de modelos dentro de una misma sesión.

Frente a OpenCode

OpenCode (y otros harnesses de terminal similares) comparte el enfoque de Pi de admitir múltiples proveedores. Pi se diferencia por:

• Formato publicado del árbol de sesiones con /tree, /fork, /export, /share
• Sistema de extensiones con recarga en caliente (/reload) para que el agente pueda modificar su propio harness
• Postura explícita contra MCP con divulgación progresiva mediante CLI+README
• Integración mediante SDK probada a la escala de OpenClaw

Frente a OpenClaw (la capa sobre Pi)

OpenClaw no es una alternativa a Pi: es un consumidor del SDK de Pi. El gateway agrega canales (WhatsApp, Telegram, Slack), cron, búsqueda en memoria, enrutamiento multiagente y aislamiento en sandbox. Pi sigue siendo el entorno de ejecución del agente.

Distinción editorial: usa Pi cuando quieras el harness en sí; usa OpenClaw cuando quieras un agente personal conectado a servicios de mensajería sin construir la infraestructura del gateway.

Handoffs, casos de uso y patrones de flujo de trabajo

Pi elimina varias funcionalidades de conveniencia que otros harnesses incluyen. Los patrones que las sustituyen siguen una idea común: hacer que el estado sea visible, se base en archivos o pueda observarse desde fuera.

1. Planificación sin modo de planificación

Patrón: mantén PLAN.md (o artefactos de OpenSpec) en el repositorio; el agente lo lee y actualiza entre sesiones.

# PLAN.md

## Goal
Refactor auth to support OAuth

## Current step
3 — authorization endpoints

## Done when
- Integration tests pass
- Migration documented

Para exploración de solo lectura:

pi --tools read,grep,find,ls

Por qué esto supera a un modo de planificación opaco (criterio editorial): cada fuente que consultó el agente permanece en el árbol de sesiones. Claude Code Plan Mode puede delegar a subagentes que no puedes inspeccionar; Pi mantiene los comandos de planificación en la transcripción principal.

2. Handoffs de revisión con árboles de sesiones

El patrón de extensión /review de Armin Ronacher (January 31, 2026) crea una rama de la sesión para revisar código y luego incorpora los hallazgos de vuelta, usando navegación por el árbol en lugar de un subagente revisor de caja negra.

Comandos integrados que lo permiten:

• /tree — salta a cualquier punto anterior y continúa
• /fork — crea una rama a partir de un mensaje del usuario
• /clone — duplica la rama activa en una nueva sesión
• /compact — resume el contexto anterior con instrucciones personalizadas opcionales

main session (implementation)
    |
    +-- branch: /review on uncommitted diff
    |       |
    |       +-- findings recorded
    |
    +-- rewind to pre-review point
    +-- apply fixes with review context summarized

3. Trabajo de subagentes sin herramientas de subagentes

La alternativa documentada de Pi a los subagentes:

pi --print "Review PR #42 for security issues. Output markdown only."

También puedes lanzar una sesión dentro de tmux para depurar de forma interactiva en conjunto. El ensayo de Mario incluye un patrón de plantilla de prompt en el que la sesión principal delega la revisión a una ejecución hija de pi --print y reporta los hallazgos, sin una API de subagentes dedicada.

Regla de handoff (criterio editorial): usa sesiones separadas para recopilar contexto; pasa artefactos (resúmenes en Markdown, resultados de grep, notas de arquitectura) a una sesión nueva en lugar de anidar agentes opacos.

4. Procesos de larga duración

Pi intencionalmente no tiene bash en segundo plano. El patrón documentado es tmux: los servidores de desarrollo, observadores de pruebas y depuradores permanecen visibles y es posible conectarse a ellos.

Esto sacrifica comodidad a cambio de observabilidad, en línea con la postura de Pi de «no tener procesos ocultos».

5. Skills, extensiones y paquetes de pi

Pi admite tres capas de extensión:

Comparte conjuntos de funcionalidades mediante paquetes de pi:

pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom

Alternativa a MCP: construye herramientas de CLI con archivos README (divulgación progresiva), o usa mcporter de Peter Steinberger para exponer servidores MCP como comandos de CLI que Pi puede invocar mediante bash.

6. Integración en tu propio producto

Ejemplo básico del SDK tomado del README oficial:

import {
  AuthStorage,
  createAgentSession,
  ModelRegistry,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const session = await createAgentSession({
  cwd: process.cwd(),
  modelRegistry: new ModelRegistry(),
  sessionManager: SessionManager.open("my-session.jsonl"),
  authStorage: new AuthStorage(),
});

La arquitectura de OpenClaw lo importa directamente: el gateway se encarga de los canales y las políticas; Pi se encarga del loop de agente. Esa separación es el diseño de referencia para «harness por dentro, producto por fuera».

7. CI automatizada e ingeniería de loops

Para la ingeniería de loops (consulta también el agente de un ingeniero sénior que orquesta subagentes y la ingeniería de loops):

pi -p "Run tests, fix failures, stop when green" --mode json > events.jsonl

El modo JSON emite eventos estructurados para orquestadores, por lo que se parece más a una primitiva componible que a un agente de IDE cerrado.

Más ventajas del harness minimalista

Más allá de las comparaciones, el diseño de Pi aporta ventajas en áreas específicas de la ingeniería.

Ingeniería de contexto que realmente puedes ver

La documentación de Pi pone énfasis en la ingeniería de contexto: system prompt minimalista, reemplazo opcional mediante SYSTEM.md, carga jerárquica de AGENTS.md (~/.pi/agent/, directorios padres, raíz del proyecto), extensiones de compactación e inyección dinámica de contexto mediante hooks de extensión.

A diferencia de los harnesses que inyectan instrucciones ocultas, el encabezado de inicio de Pi enumera los archivos de contexto, skills, extensiones y plantillas cargados, para que sepas qué vio el modelo antes del primer turno.

Sesiones con estructura de árbol como primitiva de flujo de trabajo

Las sesiones se almacenan como árboles en un único archivo JSONL. La ramificación no es un simple adorno: permite realizar revisiones paralelas, probar correcciones y retroceder sin perder el historial. Es una primitiva de handoff de la que carecen la mayoría de las interfaces de chat.

Opciones para exportar:

• /export — HTML o JSONL
• /share — gist privado de GitHub con HTML que se puede visualizar

Sesiones multimodelo con límites de portabilidad explícitos

pi-ai permite cambiar de proveedor durante la sesión (/model, Ctrl+L). La documentación y el ensayo del creador dejan claro que las trazas de razonamiento y los blobs específicos de cada proveedor no se transfieren perfectamente: una transparencia editorial poco común en los harnesses comerciales.

Rendimiento y confiabilidad

El artículo práctico de Armin Ronacher (January 31, 2026) destaca la calidad de la TUI de Pi: poco parpadeo (especialmente en Ghostty/iTerm2), bajo consumo de memoria y estabilidad. El pi-tui de Mario usa renderizado diferencial con salida sincronizada, una alternativa deliberada a las TUI de pantalla completa que consumen el historial de desplazamiento.

Harness que se modifica a sí mismo

Pi fomenta que los agentes extiendan el harness en el que se ejecutan: escribe una extensión, ejecuta /reload e itera. La recarga en caliente vuelve moldeable el harness, algo relevante para equipos que construyen herramientas diseñadas para agentes (consulta también software que se modifica a sí mismo: de la teoría a la práctica).

Una postura de seguridad explícita, no teatral

Pi se ejecuta en modo YOLO por defecto, con acceso completo al sistema de archivos y a la shell. La documentación oficial recomienda usar contenedores (Gondolin, Docker, OpenShell) en lugar de ventanas de permisos que ofrecen una falsa sensación de seguridad. El ensayo de Mario sostiene que el teatro de los permisos falla una vez que los agentes pueden leer datos y acceder a la red; Pi opta por valores predeterminados transparentes.

Señal de benchmark (con salvedades)

La ejecución de Terminal-Bench 2.0 de Mario en November 2025 situó a Pi en una posición competitiva frente a Codex, Cursor y otros harnesses usando Claude Opus 4.5: evidencia de que un conjunto minimalista de herramientas puede rendir bien, no una prueba de que siempre ganará en tu repositorio. Considera los benchmarks como indicadores generales; compara las herramientas con tus propias tareas.

Cuándo no elegir Pi

Conviene ser explícitos sobre los límites:

• Los equipos que trabajan principalmente en el IDE tendrán dificultades con un modelo centrado en la terminal.
• Los flujos de trabajo que dependen mucho de MCP necesitan extensiones o mcporter; nada viene conectado de antemano.
• Los modelos de permisos empresariales requieren que construyas flujos de confirmación o uses contenedores.
• Los subagentes y el modo de planificación listos para usar son más rápidos de adoptar en otros productos.
• Los usuarios no técnicos no deberían empezar con acceso a la shell en modo YOLO.

Si esos son requisitos indispensables, Claude Code o Cursor suelen ser la opción más rápida.

Flujo de decisión

Need IDE + cloud agents + PR review in-editor?
  yes -> Cursor (or Claude Code IDE surfaces)
  no
    |
    v
Need Anthropic-native plan/sub-agent UX without building it?
  yes -> Claude Code
  no
    |
    v
Building a gateway/bot/product on an agent runtime?
  yes -> Pi SDK (see OpenClaw pattern)
  no
    |
    v
Care most about context control + session trees + multi-provider CLI?
  yes -> Pi
  no
    |
    v
Default -> try Pi and your incumbent side-by-side on 3 real tasks

Fuentes

Fuentes primarias consultadas el July 7, 2026:

1. Sitio del producto Pi — filosofía, funcionalidades y lista de funcionalidades que decide no incluir. pi.dev
2. Documentación de Pi — instalación, modos, sesiones, extensiones, SDK y seguridad. pi.dev/docs
3. badlogic/pi-mono — packages/coding-agent/README.md — herramientas, proveedores, comandos, SDK y filosofía. github.com/badlogic/pi-mono/tree/main/packages/coding-agent
4. Mario Zechner — «Lo que aprendí al construir un agente de programación minimalista y con una filosofía definida» (November 30, 2025) — fundamentos de diseño, argumento contra MCP, ejecución de Terminal-Bench y patrones de tmux. mariozechner.at/posts/2025-11-30-pi-coding-agent/
5. Armin Ronacher — «Pi: el agente minimalista dentro de OpenClaw» (January 31, 2026) — flujos de trabajo prácticos, extensiones (/answer, /review, /todos) y patrón de skills en lugar de MCP. lucumr.pocoo.org/2026/1/31/pi/
6. Repositorio de OpenClaw — referencia de integración del SDK citada por la documentación de Pi. github.com/openclaw/openclaw
7. Peter Steinberger — mcporter — puente de MCP a CLI recomendado por la documentación de Pi. github.com/steipete/mcporter
8. Documentación de Anthropic Claude Code — referencia de Plan Mode y del modo de permisos para la comparación. docs.anthropic.com/en/docs/claude-code
9. Documentación de Cursor — agente de IDE, agentes en segundo plano e interfaces de planificación para la comparación. cursor.com/docs

El criterio editorial está señalado a lo largo del artículo (filas de mejor opción, recomendaciones de handoff y flujo de decisión). Vuelve a verificar las funcionalidades de los proveedores antes del despliegue en producción; este campo cambia cada semana.