pi agent toolkit: cinco paquetes, receta de SDK, tabla de veredictos y checklist del lunes

TL;DR

pi es un monorepo con licencia MIT que ofrece un arnés de agente de código en cinco paquetes separados: una capa de API de modelos, el bucle del agente, una librería de interfaz de terminal, el agente de código en sí y un paquete de telemetría. Puedes quedarte con una sola pieza o con las cinco.
El CLI es un agente de código completo desde el primer día: cuatro herramientas por defecto, historial de sesiones en forma de árbol con fork y resume, un contador de coste en vivo, y lee el AGENTS.md o CLAUDE.md que ya tengas en tu repo.
El valor real está en el SDK: createAgentSession más un runtime de modelo más un gestor de sesiones dan un agente funcional en unas diez líneas de TypeScript, y defineTool añade una herramienta personalizada tipada sin proceso aparte ni protocolo.
El precio de esa transparencia es trabajo: sin avisos de permisos integrados, el aislamiento corre por tu cuenta, una versión pre-1.0 (v0.84) y alrededor de cien issues abiertas.
Conserva tu arnés de diario y usa pi como banco de pruebas que te enseña lo que ese arnés esconde. Construye productos encima solo si aceptas encargarte de las protecciones.

Lo que dicen las fuentes

pi es un monorepo: un único repositorio que aloja cinco paquetes publicados por separado, cada uno con una capa del arnés s2. pi-ai es la API unificada hacia los proveedores de modelos (OpenAI, Anthropic, Google y otros tras una sola interfaz), que gestiona el streaming de respuestas, los bloques de razonamiento con sus niveles de pensamiento y el descubrimiento dinámico de los modelos que ofrece cada proveedor s2. pi-agent-core es el bucle del agente: el estado de la conversación y el ciclo que envía un mensaje, lee las llamadas a herramientas, las ejecuta y devuelve los resultados s2. pi-tui es una librería de renderizado para terminal con renderizado diferencial, así que solo redibuja lo que cambió en pantalla s2. pi-coding-agent junta esas piezas en el CLI que instalas, y pi-telemetry te deja conectar tus propias métricas de uso sin depender de un proveedor s3.

Las cifras de adopción respaldan el diseño: 92 123 estrellas, 11 400 forks y más de 5 700 commits, todo bajo licencia MIT, que permite usar, modificar y redistribuir, también dentro de un producto comercial s1. El ritmo de publicación se mantuvo durante el verano: tres versiones en las dos primeras semanas de agosto, con la v0.84.2 publicada el día 14 s4.

La instalación es un solo comando, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, y el flag ignore-scripts importa: evita que las dependencias ejecuten sus scripts de instalación, una de las superficies de ataque más usadas en npm s3. Una vez conectado a un proveedor con el comando login, la barra inferior muestra la carpeta actual, la sesión, los tokens consumidos y el coste en tiempo real, de modo que cada petición se valora al salir y no a fin de mes s3.

Las sesiones son la función distintiva. Cada conversación se guarda como JSONL en tu carpeta personal, ordenada por proyecto, y el historial es un árbol en vez de una línea: fork vuelve a cualquier punto y se ramifica, tree navega entre ramas, y resume reabre cualquier sesión pasada, semanas después, porque todo se almacena en local s3. El modelo recibe solo cuatro herramientas por defecto: read, write, edit y bash, muy pocas comparadas con los agentes del mercado, y a propósito s3. La configuración sigue la misma lógica: un settings.json global en tu carpeta personal, otro por proyecto que lo sobrescribe, y un sistema de confianza que pregunta antes de aplicar los ajustes locales de una carpeta que abres por primera vez. El CLI también carga como contexto el AGENTS.md o CLAUDE.md de tu proyecto, así que tus instrucciones existentes funcionan sin reescribirlas s3.

En el lado del SDK, createAgentSession recibe un ModelRuntime y un SessionManager y devuelve un agente funcional. El SessionManager es la decisión de persistencia: en memoria para un script desechable, en disco para recuperar tus conversaciones entre ejecuciones, y las sesiones creadas por el SDK comparten la estructura de las del propio CLI s8. La lista de opciones de createAgentSession también permite elegir el conjunto exacto de herramientas expuestas, e incluso todo el prompt de sistema mediante un ResourceLoader cuando quieres partir de una página en blanco s8. Las herramientas personalizadas pasan por defineTool: un nombre, una descripción, un esquema de parámetros tipado y una función execute, que se pasan a createAgentSession en customTools. La herramienta le aparece al modelo exactamente igual que read o bash, el esquema tipado te da autocompletado en el editor y el agente recibe entradas ya validadas. Es el mismo mecanismo que un servidor MCP, salvo que todo vive en tu archivo, sin proceso aparte ni protocolo de por medio s8.

El propio CLI se personaliza con cuatro mecanismos, todos en carpetas de tu proyecto o de tu carpeta personal: extensiones (módulos TypeScript que registran herramientas, comandos slash, atajos de teclado o elementos de interfaz, cargados al arrancar desde la carpeta extensions), skills (paquetes de capacidades que siguen el estándar Agent Skills, invocados por el modelo o llamados a mano, así que los skills existentes se reutilizan tal cual), plantillas de prompt y temas que se recargan con el CLI en marcha s3. El README resume la filosofía en una línea: adapta pi a tus flujos de trabajo y no al revés, sin hacer fork ni tocar las entrañas s3. Donde los grandes arneses integran subagentes, modo plan y permisos en el producto, pi los deja fuera a propósito, para escribirlos como extensiones o instalarlos desde la comunidad s3.

Los límites los documenta el propio proyecto. No hay avisos de permisos integrados: por defecto el agente puede ejecutar un comando bash sin preguntar. La guía oficial de contenedores lo reconoce y propone tres patrones de aislamiento, Docker entre ellos, pero montar uno antes de soltar al agente en una máquina que importa es cosa tuya s5. La madurez es el otro coste: v0.84 y no 1.0, alrededor de cien issues abiertas y APIs todavía marcadas como experimentales, como el cliente de sesión remota añadido en las últimas semanas s7. Las mismas piezas ya sirven a otro producto: pi-chat las aplica a la automatización de conversaciones s6.

Veredicto: conservar, probar o descartar

Pieza de pi	Veredicto	Por qué
CLI como banco de aprendizaje junto a tu arnés de diario	Conservar	Sesiones locales en árbol, coste en vivo, cuatro herramientas: ves cada capa que un arnés integrado esconde
SDK (createAgentSession + defineTool) para productos de agente	Probar ya	Diez líneas hasta un agente funcional, herramientas personalizadas tipadas sin la fontanería de MCP, proveedor intercambiable
CLI como único asistente de diario	Descartar por ahora	Sin avisos de permisos, aislamiento a tu cargo, cambios de API pre-1.0
Extensiones para protecciones (confirmación de bash, políticas)	Probar	El lugar previsto para una capa de permisos; versionada con tu proyecto
Carpeta de skills	Conservar	Estándar Agent Skills, tus skills actuales se cargan sin cambios
APIs experimentales (cliente de sesión remota)	Descartar	Marcadas como experimentales, pueden cambiar antes de la 1.0

Haz esto el lunes

Instala el CLI con npm install -g --ignore-scripts @earendil-works/pi-coding-agent, ejecuta pi, conecta un proveedor con el comando login y mira la barra de coste durante una tarea real.
Abre un repo que ya tenga un AGENTS.md o CLAUDE.md y comprueba que pi lo toma; compara las primeras respuestas del agente con las de tu arnés habitual con el mismo prompt.
Haz una conversación, luego un fork desde un nodo anterior y toma otra dirección; lista ~/.pi/agent/sessions/ para ver los archivos JSONL y sus carpetas de proyecto.
Escribe un our-agent.ts de veinte líneas: importa createAgentSession, pasa un ModelRuntime y un SessionManager en memoria, pregúntale qué contiene la carpeta actual y ejecútalo con npx tsx.
Añade un defineTool que lea algo de tu propio sistema (una API interna, una vista de base de datos, un CSV) y pásalo en customTools; confirma que el agente lo llama solo ante una pregunta relevante.
Antes de cualquier ejecución con bash habilitado en una máquina que te importe, elige uno de los tres patrones de aislamiento de la guía de contenedores y móntalo.
Esboza una primera extensión que intercepte las llamadas a bash y pida confirmación en los comandos destructivos; guárdala en la carpeta extensions de tu proyecto bajo control de versiones.
Echa un vistazo una vez a la lista de issues abiertas para saber qué partes se mueven antes de construir encima.

Para ir más allá

Lee la documentación del SDK para ver la lista completa de opciones de createAgentSession: conjunto de herramientas, prompt de sistema vía ResourceLoader, gestores de sesiones s8.
Estudia los tres patrones de aislamiento de la guía de contenedores antes de entregar nada que ejecute bash en la máquina de un usuario s5.
Mira pi-chat para ver cómo se reordenan los mismos cinco paquetes para automatizar conversaciones en lugar de programar s6.
Recorre la carpeta packages y lee pi-agent-core por separado: es la versión legible más pequeña del bucle que ejecuta cualquier arnés integrado s2.
Sigue la página de releases: de la v0.84.0 a la v0.84.2 salieron en dos semanas de agosto, así que espera notas de cambios que afecten a las extensiones s4.
Usa las issues abiertas como mapa de lo que sigue siendo experimental, empezando por el cliente de sesión remota s7.
Reutiliza los skills que ya escribiste para otras herramientas: la carpeta de skills de pi sigue el estándar Agent Skills s3.

Fuentes

pi: the agent toolkit (repository), Earendil Works. Por qué leerlo: el README con la lista de paquetes, el número de estrellas y forks y la licencia MIT.
pi monorepo packages, Earendil Works. Por qué leerlo: los cinco paquetes lado a lado, la forma más rápida de ver qué capa gestiona cada uno.
pi-coding-agent package README, Earendil Works. Por qué leerlo: comando de instalación, herramientas por defecto, sesiones y los cuatro mecanismos de extensión.
pi releases, Earendil Works. Por qué leerlo: el ritmo y el changelog de la línea v0.84.
pi containerization guide (isolation patterns), Earendil Works. Por qué leerlo: los tres patrones de aislamiento a aplicar antes de habilitar bash donde importa.
pi-chat: the same bricks applied to conversation automation, Earendil Works. Por qué leerlo: un segundo producto hecho con los mismos paquetes, útil para juzgar cuánto se pueden reutilizar.
pi open issues, Earendil Works. Por qué leerlo: la lista en vivo de lo que es inestable o experimental en la versión actual.
pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. Por qué leerlo: los nombres exactos de las opciones de createAgentSession, defineTool y los gestores de sesiones.

FAQ

¿Puede pi sustituir hoy a mi agente de código de diario?

No como reemplazo directo. Viene sin avisos de permisos, el aislamiento corre por tu cuenta y la versión es pre-1.0 con alrededor de cien issues abiertas. Conserva tu arnés actual para trabajar y ejecuta pi al lado.

¿Necesito MCP para darle una herramienta personalizada a pi?

No. defineTool recibe un nombre, una descripción, un esquema de parámetros tipado y una función execute, y la herramienta se pasa a createAgentSession en customTools. Se comporta como una herramienta integrada, sin proceso aparte ni protocolo.

¿Funcionarán mis AGENTS.md, CLAUDE.md y skills existentes?

Sí. El CLI carga automáticamente el AGENTS.md o CLAUDE.md de tu proyecto, y su carpeta de skills sigue el estándar Agent Skills, así que los skills existentes se cargan sin cambios.

¿Por qué solo cuatro herramientas por defecto?

read, write, edit y bash son todo el conjunto por defecto, muchas menos que los agentes del mercado, y el proyecto lo presenta como una decisión. Todo lo demás se añade de forma deliberada con customTools o una extensión.