Pi, el dispositivo de aprovechamiento del agente de codificación mínima: extensiones, habilidades, sesiones y seguridad
Por qué un pequeño conjunto de herramientas de codificación con cuatro herramientas y una breve indicación del sistema puede superar a los agentes con muchas funciones: instalación, modelos, árboles de sesión, extensiones, habilidades y entorno aislado.
Los agentes de codificación en terminal como Claude Code, Cursor y OpenCode se han convertido en una parte habitual del día a día de muchos desarrolladores, especialmente desde que OpenAI hizo público el Codex CLI en abril. Pi, un entorno de codificación deliberadamente sencillo, surge de una queja respecto a todos ellos: la herramienta sigue cambiando constantemente.
La queja no se refiere a errores. Se trata de que el entorno cambia, y el comportamiento del modelo también cambia junto con él. Los ingenieros quieren herramientas en las que puedan confiar. Los LLM en sí mismos son poco fiables, pero al menos las partes circundantes pueden hacerse deterministas, incluidas las herramientas, los prompts del sistema y todo lo que se les introduce.
Claude Code y Codex aportan mucho contexto sin mostrarlo en la interfaz, y esas adiciones ocultas perturban el flujo de trabajo de maneras sutiles. Las actualizaciones se realizan una vez al día o incluso varias veces al día. Un flujo de trabajo que funciona perfectamente a las nueve de la mañana puede desmoronarse a las diez y comportarse de manera completamente diferente a las tres, sin que el modelo cambie y solo cambiando el entorno de uso. Nuevas funciones llegan casi cada mes, entre ellas MCP, subagentes, modo de planificación y ejecución en segundo plano, y resulta cada vez más difícil seguir lo que ocurre detrás de escena.
La respuesta de Pi es una regla de diseño: si no es necesario, no se crea. Las herramientas existentes inyectan contexto de forma invisible, y los usuarios no pueden ver qué está sucediendo. Esa fue la motivación.
Qué inspiró el minimalismo
Antes de desarrollar a Pi, su creador, Mario Zechner, observó la tabla de clasificación de Terminal Bench, donde destacaba un entorno de desarrollo llamado Terminus. Este proporciona al modelo únicamente una herramienta: una interfaz para una sesión tmux. El modelo de lenguaje grande envía teclas individualmente y lee la salida ANSI de tmux para completar la tarea. Con eso solamente, casi siempre logra posicionarse entre los tres primeros y con frecuencia ocupa el primer lugar.
Esto evidencia una intuición útil: los modelos se entrenan actualmente en gran medida con aprendizaje por refuerzo, por lo que ya saben qué es un entorno de desarrollo de programación y no necesitan muchas capas adicionales. Pi encarna esa idea como un entorno mínimo pero extensible.
¿Qué hace diferente a Pi?
La característica distintiva de Pi es lo que omite: funcionalidades que otros agentes de codificación consideran estándar. Tomemos como ejemplo a MCP: al conectarse a un servidor, cada definición de herramienta inunda el contexto al inicio de cada sesión. Las herramientas de línea de comandos vienen con archivos README, que se leen y ejecutan solo cuando es necesario, por lo que no hay razón para saturar constantemente el contexto con ellos.
Qué tiene que otros carecen
Pi fue diseñado mediante sustracción, pero cuenta con capacidades que Claude Code no posee. Las extensiones y paquetes se instalan con unos pocos comandos:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
El mecanismo de extensiones
Las extensiones se escriben utilizando una API importada del paquete Pi:
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Una extensión puede conectarse a eventos como las llamadas a herramientas. Un ejemplo sirve para proteger contra comandos de shell peligrosos:
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Instalación
La instalación se realiza con un único comando:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Un script de instalación es una alternativa:
curl -fsSL https://pi.dev/install.sh | sh
Existen dos formas de autenticación. Una utiliza una clave API:
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
El otro reutiliza una suscripción que ya tienes:
# Use an existing subscription
pi
/login # Select a provider
Con /login, las suscripciones existentes como Anthropic Claude Pro o Max, OpenAI ChatGPT Plus o Pro (Codex) y GitHub Copilot pueden utilizarse tal como están. La curva de aprendizaje es muy baja: úsalo, comienza a hablar con él y funcionará.
2. Configuración del modelo
Pi admite a más de 15 proveedores de LLM. Los principales son:
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Es completamente normal cambiar de modelo en medio de una sesión:
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Se pueden agregar proveedores personalizados en ~/.pi/agent/models.json. Cualquier API compatible con OpenAI, Anthropic o Google funciona únicamente mediante la configuración, y servidores de enrutamiento como llama.cpp pueden servir un modelo local. El hecho de “no estar vinculado a un proveedor” es una de las ventajas que Pi destaca con mayor énfasis.
3. Gestión de sesiones
Las sesiones se almacenan como un archivo JSONL con estructura en forma de árbol, en ~/.pi/agent/sessions/, y cada mensaje incluye los campos id y parentId. Gracias a esta estructura, un único archivo permite realizar todas estas operaciones:
pi -c # Continue the most recent session
pi -r # Select from previous sessions
La orden /tree es especialmente interesante. Puedes volver a cualquier punto de la conversación y partir desde allí. Toda la historia se encuentra en un solo archivo, por lo que es fácil decir “Quería seguir el camino que tomé hace media hora” y hacerlo realmente.
/compact resume los mensajes antiguos para comprimir el contexto. La compactación automática está activa por defecto, y si el contexto se llena, se recupera y vuelve a intentarlo por sí mismo.
4. Extensiones en profundidad
Aquí es donde Pi demuestra realmente para qué sirve. La personalización tiene cuatro niveles:
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Los paquetes de npm o git se gestionan de esta manera:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Las extensiones pueden hacer todo lo siguiente:
- Agregar herramientas personalizadas, incluyendo sustitutos para las integradas.
- Crear subagentes y modos de planificación personalizados.
- Aplicar controles de permisos y protección de rutas.
- Añadir elementos de interfaz como línea de estado, encabezado y pie de página.
- Crear puntos de control de git o commits automáticos.
- Integrar servidores MCP.
- Ejecutar Doom mientras esperas, si lo deseas.
El punto clave es que todas las funcionalidades que otros agentes incorporan al producto, incluidos los subagentes, los modos de planificación y las ventanas emergentes de permisos, pueden crearse como extensiones. Por lo tanto, la filosofía es mantener el núcleo mínimo.
5. Habilidades
Las habilidades son paquetes de capacidades escritos en Markdown. Siguiendo el estándar Agent Skills, una carpeta que contenga un archivo SKILL.md constituye una habilidad.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Se puede llamar a una habilidad de forma explícita con /skill:name, y el agente también la carga por sí mismo cuando la tarea lo permite. La decisión de diseño clave es que las habilidades entran en el contexto solo cuando son necesarias. En lugar de incluir todo en el prompt del sistema, se activan al ser utilizadas, y así es como el prompt del sistema mantiene alrededor de mil tokens.
6. Pi Web, la interfaz del navegador
También existe una interfaz de navegador llamada Pi Web:
npx @agegr/pi-web@latest
Sus características principales:
- Un espacio de trabajo de sesión para listar, reanudar, renombrar y eliminar conversaciones anteriores por proyecto.
- Dos formas de crear ramas: iniciar una nueva sesión a partir de un mensaje o hacer un fork dentro de la sesión actual.
- Visualización de archivos de proyecto y muestra de diferencias con Git.
- Cambio de árboles de trabajo de Git.
- Inicio de sesión en el proveedor, configuración de modelos, paquetes y habilidades directamente en el navegador.
Dado que comparte la configuración de ~/.pi/agent y los archivos de sesión con la versión de terminal, pasar de la versión del navegador a la de terminal es sencillo.
7. Memoria
La memoria resulta ser algo sencillo. La idea es que Pi no necesita una base de datos separada para la memoria a largo plazo; en su lugar existen tres mecanismos:
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
En otras palabras, lo que se ha hecho permanece en la sesión, y lo que se desea tener en cuenta se encuentra en AGENTS.md. Añadir memoria a través de una extensión también es un caso de uso derivado común.
8. Mantenerse seguro
Pi no cuenta con un entorno aislado integrado. Las operaciones de lectura, escritura, edición y ejecución se realizan con los privilegios de quien lo inició, y lo mismo ocurre con las extensiones. Esto se hace intencionadamente. Un entorno aislado parcialmente integrado solo ofrece una barrera aparentemente segura, por lo que la postura oficial es dejar la verdadera isolación en el sistema operativo y en las capas de contenedor o máquina virtual. Los repositorios no confiables y las ejecuciones sin supervisión deben realizarse en un entorno aislado.
Una opción es colocar todo el entorno de Pi en Docker, el enfoque más sencillo:
# 1. Put the entire pi environment in Docker (simplest)
Otra opción es ejecutar Pi en el host y redirigir solo la ejecución de las herramientas a una micro-VM local:
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Una función llamada project trust añade una protección de entrada. Impide que los repositorios sobrescriban silenciosamente la configuración o las extensiones de Pi, y por defecto solicita confirmación para los proyectos no verificados. Sin embargo, no evita por completo la inyección de comandos, así que tenga eso en cuenta al trabajar con código o documentos desconocidos.
9. Creando su propia extensión
La extensión más sencilla es un único archivo de TypeScript. Este registra una herramienta:
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
Y puede agregar comandos o interceptar llamadas a herramientas:
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Coloque el archivo en ~/.pi/agent/extensions/ para todos los proyectos, o en .pi/extensions/ para un proyecto específico; así se cargará automáticamente al iniciar Pi. Para una prueba puntual, basta con ejecutar pi -e ./my-ext.ts. El repositorio oficial contiene numerosos ejemplos: auto-commit, puntos de control de Git, integración MCP y compactación personalizada. En Pi, es normal que falten ciertas funcionalidades; lo habitual es añadirlas uno mismo o instalar un paquete.
Qué enseña Pi
Para quienes desarrollan su propio agente, las decisiones de Pi constituyen una referencia útil. Evite los paquetes que incluyen todo; comience con cuatro herramientas y un prompt del sistema de aproximadamente mil tokens, y añada solo lo necesario. El diseño debe comenzar por determinar qué eliminar y no por qué añadir.
Leer más
- Las cinco capas de un agent harness, con código que falla sin ellas — Un recorrido práctico por los cinco lugares donde un agent harness aplica reglas en el código, desde los límites de ejecución hasta las tuberías de contexto, y lo que la investigación puede y no puede demostrar.
- Notas prácticas: Construyendo un agente de programación en nube privada: OpenCode + un LLM local — Guía paso a paso de las Notas prácticas: Construyendo un agente de programación en nube privada: OpenCode + un LLM local: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.