Dentro de pi: 92.000 estrellas para crear tu propio agente

Claude Code, Codex y Gemini CLI son arneses de agente diseñados por otra persona, y si pasas tu jornada dentro de uno, vives con esa decisión de diseño. ¿Quieres cambiar un comportamiento, añadir una herramienta, ajustar un permiso? Esperas a que el proveedor lo lance. No sabes qué contiene el system prompt, no ves el bucle que ejecuta las herramientas y no puedes cambiar nada de eso, aunque estas herramientas ya sean el puesto de trabajo principal de miles de desarrolladores.

Un proyecto open source hace justo lo contrario: pi, un toolkit que entrega las piezas sueltas para montar tu propio agente, desde el conector del modelo hasta la interfaz. Consiguió 92.000 estrellas en GitHub en su primer año y lanza un release casi cada semana. Este artículo cubre qué pone pi realmente en la caja, cómo construir tu propio agente con su SDK, y un veredicto honesto frente a los arneses ya hechos.

Un arnés es toda la maquinaria alrededor de un modelo de lenguaje que lo convierte en un agente funcional. Un modelo solo hace una cosa: leer texto y producir texto. No lee tus archivos, no ejecuta un solo comando, y no recuerda nada de una sesión a otra. Todo lo demás es el arnés: el system prompt que encuadra al modelo, las herramientas que se le exponen, el bucle que ejecuta las llamadas a herramientas y devuelve resultados, y la interfaz en tu terminal.

El arnés también decide los detalles que importan cada día: cómo se compacta el historial cuando el contexto desborda, cómo llega al modelo un error de herramienta, qué se registra y qué no. Claude Code es un arnés. Codex también. Cuando un agente te impresiona, buena parte del mérito es de esa maquinaria, no del modelo: conecta el mismo modelo a dos arneses distintos y obtienes dos agentes que no están al mismo nivel.

pi, hecho por Earendil Works, corta esa maquinaria en piezas reutilizables. Puedes usar su agente de código tal cual, o coger las piezas una a una y montar el tuyo. Esa segunda opción es la que nos interesa.

pi es un monorepo: un solo repositorio que aloja cinco paquetes publicados por separado, y cada paquete cubre un piso del arnés:

Paquete	Qué hace
pi-ai	API unificada hacia OpenAI, Anthropic, Google y el resto: streaming de respuestas, bloques de razonamiento con sus niveles, descubrimiento dinámico de los modelos de cada proveedor. Cambia de proveedor solo cambiando un argumento.
pi-agent-core	El bucle de agente en sí: estado de la conversación, más el ciclo que envía el mensaje, lee las llamadas a herramientas, las ejecuta y devuelve resultados hasta terminar la tarea. Los casos raros —una herramienta que falla, una respuesta cortada, llamadas en paralelo— ya están resueltos.
pi-tui	Librería de renderizado en terminal con render diferencial: solo redibuja lo que cambia en pantalla.
pi-coding-agent	El agente de código completo, montado a partir de las piezas anteriores: la prueba de que el toolkit basta para construir un producto terminado.
pi-telemetry	Conecta tus propias métricas de uso sin depender de un proveedor.

El bucle de agente es justo la pieza que reescribirías mal desde cero; escribirla bien son semanas de trabajo que te ahorras con un import. El equipo aplica la misma receta en otro sitio: un repositorio aparte, pi-chat, reutiliza las mismas piezas para automatizar conversaciones.

Los números avalan la fórmula:

Métrica	Valor
Estrellas en GitHub	92.123
Forks	11.400
Commits	5.700+
Licencia	MIT
Releases en las dos primeras semanas de agosto de 2026	3 (v0.84.2 lanzada el 14 de agosto)

La licencia MIT significa que puedes usar, modificar y redistribuir pi sin restricciones, incluso en un producto comercial. pi no es un framework más: es un arnés completo entregado por piezas, mantenido a buen ritmo.

El CLI de pi es el agente de código ya ensamblado que obtienes antes de tocar nada de código, y por ahí es por donde vas a empezar. La instalación es una línea, y su flag --ignore-scripts no es un detalle: evita que tus dependencias ejecuten scripts de instalación, una de las vías de ataque más explotadas en npm. Lanza pi, conecta tu proveedor con el comando de login, y tienes un agente de código aquí mismo, en tu terminal. La barra de estado muestra la carpeta actual, la sesión, los tokens gastados y el coste en tiempo real: ves cada petición con precio en el momento en que sale, en vez de descubrir la factura a fin de mes.

Los comandos slash cubren el día a día: model para cambiar de modelo sobre la marcha, compact para resumir el historial cuando el contexto crece, export para sacar la conversación, settings para el resto. Un archivo markdown en la carpeta de prompts se convierte en un comando que activas escribiendo su nombre.

La firma real de pi es la gestión de sesiones. Cada conversación se guarda en JSONL en tu carpeta home, ordenada por proyecto, y el historial es en realidad un árbol, no una línea. Puedes volver a cualquier punto de una conversación y tomar otro camino con fork, y luego moverte entre ramas con tree. Un prompt fallido ya no te cuesta nada: vuelves al nodo anterior y lo intentas de nuevo sin perder la rama previa. Como todo se guarda en local, resume te devuelve a cualquier sesión pasada, incluso semanas después. Ni Claude Code ni Codex ofrecen una navegación de historial así.

Por defecto, el modelo solo recibe cuatro herramientas: read, write, edit y bash. Es muy poco frente a los agentes del mercado, y es deliberado (volvemos a eso más abajo). La configuración sigue la misma lógica: un archivo global en tu carpeta home, uno por proyecto que lo sobreescribe, y un sistema de confianza que pregunta antes de aplicar los ajustes de una carpeta que abres por primera vez. Si migras, pi carga automáticamente tus archivos AGENTS.md o CLAUDE.md existentes como contexto, así que tus instrucciones funcionan sin reescribirlas.

Construir un agente con el SDK de pi empieza con un solo import: createAgentSession, al que le pasas un runtime de modelo y un gestor de sesión, devuelve un agente funcional. El gestor de sesión es la elección de persistencia: en memoria para un script desechable, o en disco para recuperar tus conversaciones de una vez a otra.

Lo probamos en un proyecto local. Nuestro script pregunta qué hay en la carpeta actual; el agente llama a su herramienta read, lee la carpeta y responde. Ese es el bucle completo, escrito por nosotros, en unas diez líneas de TypeScript. Las sesiones que crea el SDK tienen la misma estructura en árbol que las del CLI —cada mensaje va ligado a su padre— así que el ramificado de historial también funciona en tu propio código.

Las herramientas custom es donde se pone interesante. defineTool toma un nombre, una descripción, un esquema de parámetros tipado y una función de ejecución, y tu herramienta aparece ante el modelo exactamente igual que read o bash. Escribimos una que consulta la lista de vídeos del canal, la pasamos en customTools, y el agente la llamó solo desde la primera pregunta relevante. Es básicamente el mismo mecanismo que un servidor MCP, salvo que todo vive en tu archivo: sin proceso separado, sin protocolo de por medio. Como el esquema de parámetros es tipado, tu editor autocompleta los argumentos y el agente recibe entradas ya validadas.

También controlas el modelo, el nivel de razonamiento (de completamente apagado hasta máximo), la lista exacta de herramientas que ve el modelo, e incluso todo el system prompt mediante un cargador de recursos si quieres empezar desde una página en blanco. Para mostrar todo, session.subscribe te da cada evento —texto en streaming, llamadas a herramientas, errores— para redirigirlo donde quieras: un terminal, un bot de mensajería, o una pipeline de CI que comenta tus pull requests. En una tarde pasas de usar un agente a haber escrito uno, y por fin sabes qué pasa en cada vuelta del bucle.

El CLI de pi se personaliza mediante cuatro mecanismos, todos en carpetas normales de tu proyecto o tu directorio home:

• Extensiones: módulos TypeScript que registran herramientas, comandos slash, atajos de teclado o elementos de interfaz. Sueltas el archivo en la carpeta de extensiones y carga al arrancar. Ahí es donde escribirías un guardarraíl de permisos, por ejemplo: una extensión que intercepta comandos bash y pide confirmación antes de los peligrosos.
• Skills: paquetes de capacidades que siguen el estándar Agent Skills, el mismo que popularizó Anthropic, así que tus skills existentes se reutilizan tal cual.
• Prompts: prompts reutilizables como simples archivos markdown.
• Temas: se recargan en caliente mientras el CLI está en marcha.

Todo se instala como cualquier paquete: pi install toma un paquete npm o un repositorio git, y un solo comando actualiza todo. Los docs resumen la filosofía en una frase: adapta pi a tus flujos de trabajo, no al revés, sin forkear ni tocar el interior.

Es lo contrario de los grandes arneses. Donde Claude Code trae sub-agentes, plan mode y permisos dentro del producto, pi los deja fuera deliberadamente, para construirlos como extensión o instalarlos desde la comunidad. La apuesta es clara: un núcleo mínimo que apenas cambia, y toda la personalización viviendo de tu lado, en archivos versionados con tu proyecto.

La transparencia de pi se paga con trabajo, y ese coste tiene tres partes.

Primero los guardarraíles: por defecto no hay permisos integrados, así que el agente puede correr un comando bash sin preguntarte nada. Los docs oficiales lo reconocen y proponen tres patrones de aislamiento, Docker incluido, pero ponerlos en marcha antes de soltar al agente en una máquina importante es cosa tuya.

Luego la madurez: esto es v0.84, no 1.0, con un centenar de issues abiertas y algunas APIs aún marcadas como experimentales, como el cliente de sesión remota añadido estas últimas semanas. Lo que hoy funciona puede romperse en el próximo release; ese es el precio normal de un proyecto que avanza tan rápido.

Por último, el tiempo. Cada comodidad que Claude Code trae de serie —plan mode, sub-agentes, permisos finos— es un proyecto que construyes tú mismo aquí, o un paquete de la comunidad que persigues esperando que se mantenga. El ecosistema de extensiones tiene un año: encontrarás menos paquetes listos que huecos que llenar. Hasta la instalación te enseñó el nivel de cuidado que hace falta, con su flag --ignore-scripts, y tendrás que mantenerlo en toda la cadena. Si tu meta es lanzar código esta noche, pi te va a frenar antes de acelerarte: no cambies tu arnés principal esta semana solo por este vídeo.

pi es para desarrolladores que construyen productos con agentes, no solo con un agente. Para ellos es probablemente la mejor inversión de aprendizaje del momento: instala el CLI, escribe un agente de veinte líneas con el SDK, y dale una herramienta propia. Haz eso y entenderás Claude Code mejor que la mayoría de sus usuarios.

Si solo quieres un asistente productivo hoy, quédate con tu arnés integrado y vuelve cuando el 1.0 traiga los guardarraíles: el valor de pi está en entender y controlar, no en la comodidad inmediata. Entre ambos hay un terreno sin riesgo: quédate con Claude Code para el trabajo, y usa pi como banco de pruebas para ver qué te oculta tu herramienta principal.

Lo que más queda es que los arneses ya no son cajas negras: las piezas están sobre la mesa, documentadas, con licencia MIT. La próxima vez que un agente te impresione o te moleste, sabrás exactamente qué pieza mirar.