Pi: el agente de código minimalista que puedes extender a tu medida

Actualmente hay muchísimos agentes de código en terminal que compiten por meter todas las características dentro de un solo comando: OpenCode, Claude Code, Codex, OpenClaw y una lista que sigue creciendo. Todos quieren ser la navaja suiza definitiva.

Pero hay un proyecto que va deliberadamente en sentido contrario, y se llama Pi.

Pi es un agente minimalista. Por defecto no viene con MCPs, no tiene subagentes, no tiene plan mode, no tiene una lista infinita de herramientas precargadas. Te da un núcleo pequeño, rápido, y te deja a ti decidir qué le quieres añadir encima usando extensiones en TypeScript.

Y sorprendentemente — o no tanto — está ganando popularidad. De hecho, agentes mucho más grandes como OpenClaw lo usan por debajo como motor. En este artículo vamos a ver de qué se trata, cómo instalarlo, cómo configurarlo con varios proveedores de IA, y cómo extenderlo con skills, paquetes y extensiones.

¿Qué es Pi y por qué usarlo?

Pi es un proyecto personal de Mario Zechner (publicado bajo Earendil Inc.) disponible como paquete de npm: @mariozechner/pi-coding-agent. Ese solo detalle — que es un paquete personal de alguien — ya te dice mucho de su filosofía.

La idea de fondo es simple: adapta Pi a tu flujo de trabajo, no al revés.

¿Por qué alguien querría un agente con menos cosas? Porque muchas veces lo que sobra estorba más de lo que ayuda:

• Contextos de sistema extensos que consumen tokens en cada turno.
• Herramientas preinstaladas que no usas, pero que el modelo igual considera.
• Flujos opinados que no siempre encajan con lo que estás haciendo.

Al ser tan ligero, Pi se presta para integrarse en herramientas pequeñas y puntuales: un bot de Slack, una interfaz de chat personalizada, un runner para tareas específicas dentro de un sistema más grande. De ahí que OpenClaw lo use internamente — necesita un motor enfocado en código, embebible, que no le imponga decisiones.

Instalación

Se instala con un único comando de npm:

npm install -g @mariozechner/pi-coding-agent

Funciona en Mac, Linux y Windows. Una vez instalado, lo lanzas con:

pi

Si lo ejecutas por primera vez, te va a decir que no hay modelos disponibles. Necesitas autenticarte con algún proveedor. Pi no viene atado a ningún modelo específico.

Autenticación: OAuth vs API keys

Pi soporta dos formas de conectarte a proveedores.

Opción 1: OAuth para suscripciones

Para proveedores que ya tienes por suscripción (ChatGPT Plus, GitHub Copilot, etc.), se usa el comando:

/login

Esto abre un menú interactivo para elegir proveedor. Al seleccionar uno — por ejemplo GitHub Copilot — Pi te da una URL que abres con Ctrl+Click, te autenticas en el navegador, pegas el código que te muestra la terminal y listo. Ya tienes acceso a todos los modelos disponibles en esa suscripción.

Puedes hacer login con varios proveedores a la vez. Si ya iniciaste sesión con Copilot y después haces /login con ChatGPT, Pi va a listarte ambos al momento de escoger modelo, indicando entre paréntesis desde qué suscripción viene cada uno.

Opción 2: API keys por variables de entorno

Para proveedores a los que accedes por API (Anthropic, OpenAI directo, Google Gemini, OpenRouter, Groq, MiniMax, etc.), Pi busca tokens en variables de entorno con nombres específicos. La documentación oficial de custom providers tiene la tabla completa con el nombre exacto que necesitas para cada proveedor, y también explica cómo añadir proveedores que no están listados por defecto usando extensiones.

En Linux o Mac se exporta así:

export GEMINI_API_KEY="tu-token-aqui"

En Windows PowerShell es un poco distinto:

$env:MINIMAX_API_KEY = "tu-token-aqui"

Después de definir la variable, al entrar a Pi y ejecutar /model, el modelo correspondiente aparece listado automáticamente junto al resto. Puedes verificar que la variable quedó bien con echo $env:MINIMAX_API_KEY en PowerShell, o echo $GEMINI_API_KEY en bash.

Un detalle útil: puedes mezclar ambos métodos sin problema. Por ejemplo, OAuth para Copilot y ChatGPT, y API key para MiniMax o Gemini. Todos los modelos te aparecerán en la misma lista.

Tu primera tarea con Pi

Una vez autenticado, seleccionas un modelo con /model, le das Enter, y ya puedes pedirle cosas:

crea una web de recetas de cocina

Pi arranca la planificación, empieza a llamar herramientas, escribe archivos y ejecuta comandos. En la parte inferior de la terminal tiene una barra de estado que muestra:

• Tokens consumidos.
• Equivalente aproximado en dólares.
• Contexto disponible.

No tiene UI espectacular, pero es funcional y rápida.

Cambiando de modelo al vuelo

Si tienes varias suscripciones conectadas (Copilot + ChatGPT + MiniMax, por ejemplo), cambiar entre modelos es trivial:

• /model o Ctrl+L → menú completo de modelos disponibles.
• Ctrl+P → ciclar entre tus modelos favoritos (presiónalo varias veces y va alternando).

En la barra inferior siempre ves qué modelo estás usando y de qué suscripción viene. Esto es oro cuando trabajas con varios proveedores y quieres ir rotando según el tipo de tarea (un modelo barato para refactors simples, uno fuerte para arquitectura, etc.).

Cola de mensajes: steering vs follow-up

Esta es una de mis características favoritas de Pi, y algo que la mayoría de agentes no hace bien por defecto.

Mientras Pi está ejecutando una tarea, puedes seguir escribiendo. Tienes dos opciones:

Enter → Steering

Envía un mensaje que se entrega después de la herramienta actual, interrumpiendo lo que queda. Útil cuando quieres corregir el rumbo de la tarea actual sobre la marcha.

Ejemplo: el agente está creando un formulario de login y le dices "no olvides la pantalla de forgot password". Esto se añade a la tarea en curso.

Alt+Enter → Follow-up

Envía el mensaje a una cola. Pi va a terminar lo que está haciendo y luego va a procesar el mensaje como una nueva tarea independiente.

Ejemplo: mientras construye el login, le pides "crea una página de perfil en el dashboard". Esto no modifica la tarea actual, espera su turno.

Puedes acumular varias tareas con Alt+Enter y las va ejecutando una tras otra. Incluso puedes editar mensajes ya enviados con Alt+↑.

Esto es lo que muchos esperamos de Claude Code o Codex y no tenemos por defecto.

Hot keys y comandos útiles

Al ser un agente nuevo, Pi tiene sus propios atajos. Con /hotkeys ves la lista completa, pero algunos que vale la pena memorizar:

• Tab → autocompletado.
• Escape → cancelar el autocompletado.
• Ctrl+C → limpiar el editor.
• Ctrl+D → salir.
• Ctrl+Z → suspender el proceso (útil cuando tienes tareas en background).
• @ → referenciar archivos con autocompletado (igual que otros agentes).

Ejecutar bash desde el prompt

Pi te permite lanzar comandos de bash directamente desde el prompt de chat, con dos modos distintos:

# → Un solo numeral

El comando se ejecuta y la salida se añade al contexto del agente. Útil cuando quieres que Pi "vea" el resultado:

#ls -la

## → Doble numeral

El comando se ejecuta y te muestra la salida, pero no se añade al contexto. Útil cuando solo quieres consultar algo sin ensuciar la conversación:

##echo "prueba"

Esto es muy potente porque puedes llamar cualquier programa: credenciales de AWS, comandos de Azure, herramientas locales, lo que sea — y decidir si el agente debería saberlo o no.

Sesiones con estructura de árbol

En lugar de sesiones lineales tipo "chat continuo", Pi guarda todo en una estructura de árbol. Comandos relevantes:

• /new → arranca una sesión nueva limpia.
• /name documentacion → ponle un nombre a la sesión actual.
• /session → muestra detalles de la sesión (mensajes, tool calls, tokens).
• /tree → navega el árbol completo y salta a cualquier punto anterior.
• /export → exporta la sesión a HTML.
• /share → sube la sesión a un Gist de GitHub con URL compartible.

La magia del /tree está en que puedes volver a cualquier punto pasado y ramificar desde ahí, creando una nueva línea de conversación sin perder la anterior. Cuando saltas, Pi te pregunta si quieres resumir el contexto previo o arrancar limpio. Todas las ramas viven en un único archivo.

Ingeniería de contexto: personalizar Pi

Como Pi es minimalista, la personalización es clave. Estas son las piezas que tienes disponibles:

AGENTS.md

Archivo con instrucciones del proyecto, cargado al iniciar Pi. Se busca en:

1. ~/.pi/agent/ (global).
2. Directorios padre del proyecto.
3. El directorio actual.

Es equivalente al CLAUDE.md de Claude Code, pero con el estándar abierto AGENTS.md.

SYSTEM.md

Permite reemplazar o ampliar el system prompt por defecto, por proyecto. Útil cuando quieres que Pi se comporte de manera muy distinta según el repositorio.

Compaction

Cuando el contexto se acerca al límite, Pi auto-resume mensajes antiguos. Puedes reemplazar esto con una extensión: summaries por tema, summaries conscientes del código, o usar un modelo distinto solo para compactar.

Skills

Los skills son paquetes de capacidades (instrucciones + herramientas) que Pi carga bajo demanda. Esto significa que no ocupan contexto hasta que realmente se necesitan — evitando romper el cache del prompt.

Un skill típico tiene:

• Una carpeta con su nombre.
• Un archivo SKILL.md con instrucciones.
• Opcionalmente, scripts o binarios auxiliares.

Pi carga skills desde dos lugares:

• .claude/ → sigue el estándar (compatible con otros agentes).
• .pi/ → específico de Pi, para skills globales o del proyecto.

Instalar un skill de ejemplo

Digamos que quieres el skill de "interface design" que viene en el repo. Sales de Pi y ejecutas el comando de instalación desde la documentación:

# ejemplo del esquema general
pi install <skill-name> --dir ./recetas-web

Esto te crea la carpeta .claude/ dentro de tu proyecto con el skill dentro. Al volver a entrar a Pi, al cargar te muestra los skills detectados.

Para usarlo, simplemente lo mencionas en tu prompt:

mejora la UI del dashboard usando interface design

Pi lee el skill, aplica sus instrucciones y ejecuta los cambios.

Prompt templates

Son prompts reutilizables guardados como archivos Markdown. Escribes /nombre-del-template y Pi lo expande. Personalmente los veo bastante intercambiables con los skills — un skill puede hacer todo lo que hace una plantilla y más. Pero están ahí si los quieres, parecidos a los slash commands que tenían versiones antiguas de Claude o ChatGPT.

Extensiones: el núcleo de la filosofía de Pi

Aquí es donde Pi se pone interesante. Las extensiones son módulos de TypeScript que tienen acceso a:

• Tools del agente.
• Comandos slash personalizados.
• Atajos de teclado.
• Eventos del ciclo del agente.
• La TUI completa.

Con extensiones puedes construir literalmente cualquier cosa que otros agentes traen incluido:

• Subagentes.
• Plan mode.
• Permission gates.
• Path protection.
• Ejecución por SSH.
• Sandboxing.
• Integración con MCP (sí, la integración que Pi no trae por defecto, la puedes añadir como extensión).
• Barras de estado, overlays, editores custom.

En el repo oficial hay más de 50 ejemplos de extensiones, incluyendo una que corre Doom dentro de Pi. Esto no es broma: hay una captura con Doom ejecutándose como overlay. Es el tipo de cosa que demuestra lo flexible que es.

Paquetes: instala y comparte

Las extensiones, skills, prompts y themes se pueden empaquetar como pi packages y distribuir por npm o git:

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

Comandos útiles:

• pi install <fuente> → instalar.
• pi list → ver paquetes instalados.
• pi config → configurar.
• pi update → actualizar todos.
• pi -e git:usuario/repo → probar sin instalar.

Puedes pinchar versiones específicas con @1.2.3 o @tag.

Para descubrir paquetes tienes dos lugares:

1. npm, buscando el keyword pi-package.
2. La página oficial en pi.dev/packages.

En el marketplace encuentras cosas como:

• myp → configuración personal.
• tmux → para lanzar múltiples instancias de Pi al mismo tiempo, similar a lo que permite Codex en escritorio o Claude Code en escritorio.
• pi-web-access → búsqueda web (usa XAMCP por debajo).
• Una mascota 3D que aparece en la TUI (sí, existe).

Ejemplo práctico: subagentes y Taskplane

Pi no trae subagentes, pero hay paquetes que los añaden. Uno popular es pi-subagents, que instalas con:

pi install <comando-del-paquete>

Una vez instalado, al escribir / ves nuevos comandos:

• /parallel → ejecutar varios agentes al mismo tiempo.
• /chain → ejecutar agentes en secuencia.
• /run <agente> <tarea> → ejecutar un agente específico.
• /agents → listar los agentes disponibles (incluye ejemplos como context-builder, planner, worker).

El detalle a considerar: muchos de estos paquetes están construidos pensando en la API de Anthropic. Si usas otro proveedor puede que tengas que ajustar la configuración manualmente (crear la carpeta extension/, definir subagentes, etc.). La documentación de cada paquete te guía.

Taskplane

Otro paquete interesante es taskplane. Se instala, se inicializa con:

taskplane init

Te hace algunas preguntas (nombre del proyecto, número de agentes paralelos, directorio, área por defecto), y crea agentes especializados dentro de carpetas estructuradas. Después lanzas:

pi
# dentro de pi:
/orchestrate

Y ejecuta las tareas pendientes, mostrándote una tabla con el estatus de cada una. Incluso trae un dashboard web que lanzas con:

taskplane dashboard

Donde ves visualmente cada tarea ejecutándose paso a paso. Obviamente, la utilidad depende de qué tan bien definas las tareas al inicio. Si las defines mal, el dashboard no te salva.

¿Cuándo vale la pena usar Pi?

Pi no es para todo el mundo. Si lo que quieres es un agente que "simplemente funcione" con todas las campanas y silbatos el primer día, probablemente prefieras Claude Code, Codex u OpenCode.

Pi brilla en estos escenarios:

• Integraciones embebidas. Quieres un motor de agente dentro de tu propia aplicación (bot de Slack, interfaz custom, herramienta interna). Pi tiene cuatro modos de uso: interactivo, print/JSON, RPC y SDK. OpenClaw es el ejemplo de referencia.
• Quieres control total del contexto. System prompt minimalista, compactación personalizable, control exacto sobre qué entra y qué sale del context window.
• Te estorban las opiniones de otros agentes. No te gusta el plan mode de X, los permission popups de Y, el background bash de Z. Pi no los trae — y si los quieres, los construyes como los quieres.
• Vas a construir tus propias herramientas. Si ya tienes en mente extensiones específicas para tu equipo o flujo, Pi es el lienzo en blanco.

Y no brilla en estos:

• Quieres empezar rápido sin configurar nada. Vas a pasar tiempo leyendo repos y ajustando.
• Necesitas funcionalidades empresariales out of the box. Permission systems, auditoría, compliance — todo eso hay que construirlo.
• No te sientes cómodo escribiendo TypeScript. Porque tarde o temprano vas a querer extender algo.

Es un poco como comparar Vim vs VS Code. Vim viene casi vacío y tú decides qué plugins le pones. VS Code viene cargado con extensiones por defecto. Ambos son válidos — depende del tipo de editor (o agente) que quieras tener.

Conclusión

Pi es un agente de código pensado para desarrolladores a los que les gusta tener el control. Su apuesta es clara: un núcleo pequeño, rápido y bien diseñado, que se extiende con TypeScript y se comparte como paquetes de npm. Sin MCPs por defecto, sin subagentes, sin plan mode — y con la promesa de que todo eso lo puedes añadir si lo necesitas.

En un ecosistema donde los agentes compiten por ser lo más grande posible, Pi apuesta por ser lo más pequeño y flexible posible. Y la verdad, tiene sentido: proyectos más grandes como OpenClaw ya lo usan por debajo precisamente por eso.

Si te interesa probarlo, empieza simple:

npm install -g @mariozechner/pi-coding-agent
pi
/login

Y de ahí en adelante, ve explorando la documentación oficial en el repo de GitHub (badlogic/pi-mono) y la lista de paquetes en pi.dev/packages. Lo ideal es que vayas añadiéndole cosas a medida que las necesites, no todo al principio.

Si quedó alguna duda sobre cómo configurarlo con un proveedor específico o cómo crear tu propia extensión, déjalo en los comentarios. Nos vemos en un próximo post.

Recursos adicionales

Sitio oficial y documentación

• shittycodingagent.ai — sitio oficial de Pi.
• Repositorio en GitHub — código fuente y documentación completa.
• Custom providers — cómo conectar modelos vía suscripción o API keys, y cómo añadir proveedores personalizados con extensiones.

Paquetes mencionados

• pi.dev/packages — marketplace oficial de paquetes.
• pi-subagents — añade subagentes con ejecución paralela y en cadena.
• pi-web-access — búsqueda web integrada (usa XAMCP por debajo).
• taskplane — planificación de tareas con dashboard visual.

Paquete npm principal

• @mariozechner/pi-coding-agent — el paquete que instalas globalmente.