Pi Agent: el harness de IA abierto que puedes personalizar a tu medida

Cuando se habla de agentes de IA para programar, casi siempre aparecen nombres como Claude Code, Codex u OpenCode. Pero hay un harness que se menciona cada vez más: Pi (o Pi Agent), un agente de terminal de código abierto que puedes configurar, extender y adaptar a tu forma de trabajar.

En esta guía te muestro qué es Pi, cómo instalarlo, cómo conectar tus modelos y cómo personalizarlo con custom prompts, skills, temas, extensiones y paquetes.

📺 Este artículo acompaña al video: [ENLACE AL VIDEO]

Tabla de contenidos

¿Qué es Pi Agent?

Pi es un agente de IA extensible que trabaja desde tu terminal. Le das un objetivo y una carpeta, y puede leer archivos, ejecutar comandos, editar código y resolver tareas de varios pasos. El proyecto lo desarrolla Earendil y su código está disponible en GitHub bajo licencia MIT.

Normalmente, cuando pagas una suscripción de IA, viene con su propio harness: Claude con Claude Code, ChatGPT con Codex. Pi se parece más a OpenCode en que es abierto: puedes usarlo con prácticamente cualquier proveedor de modelos.

La gran diferencia es su filosofía: Pi viene casi vacío. No trae de fábrica subagentes, MCPs, un sistema de permisos, modo plan ni lista de tareas. Al principio puede parecer una desventaja, pero te da control total: instalas solo lo que necesitas, al estilo de los editores de código que armabas con extensiones.

Pi Agent Harness tradicionales (Claude Code, Codex)
Código fuente Abierto (MIT) Cerrado o ligado a un proveedor
Modelos Cualquier proveedor compatible Principalmente los de su empresa
Funciones incluidas Mínimas Muchas de fábrica
Personalización Extensiones en TypeScript, skills, prompts, temas, paquetes Limitada a lo que ofrece el producto

⚠️ Importante: Pi no incluye un sistema de permisos. Se ejecuta con los mismos permisos de tu usuario y no pide confirmación antes de cada comando. Para trabajo no supervisado o repositorios en los que no confías, la documentación recomienda aislarlo en un contenedor o sandbox.

Instalación

En macOS o Linux puedes usar el instalador oficial:

curl -fsSL https://pi.dev/install.sh | sh

En cualquier sistema (incluido Windows) puedes instalarlo con npm (requiere Node.js 22.19 o superior):

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Verifica la instalación y ejecútalo dentro de la carpeta en la que quieres trabajar:

pi --version
cd mi-proyecto
pi

Para Windows nativo, revisa la guía de Windows.

Conectar un modelo

Dentro de Pi, ejecuta:

/login

Tienes dos opciones:

  • Suscripción: usa una cuenta que ya pagas (por ejemplo, ChatGPT/Codex, Claude, GitHub Copilot o Kimi). Se autentica abriendo el navegador.
  • API key: conecta proveedores como OpenRouter, Hugging Face, Amazon Bedrock, la API de Anthropic, DeepSeek y muchos más.

Puedes iniciar sesión con varios proveedores y cambiar entre sus modelos.

Comandos y atajos útiles

Acción Comando / atajo
Elegir modelo /model (o Ctrl+L)
Limitar qué modelos aparecen en el selector /scoped-models
Cambiar el nivel de razonamiento /thinking o Shift+Tab para rotar niveles
Nueva línea en el prompt Shift+Enter
Expandir o contraer la salida de herramientas Ctrl+O
Ejecutar un comando de terminal !comando (por ejemplo !pwd)
Recargar configuración, skills y extensiones /reload
Ver todos los atajos activos /hotkeys

Sobre el nivel de esfuerzo (thinking): los niveles bajos responden más rápido y consumen menos tokens; los altos razonan más y suelen dar mejores respuestas en tareas complejas. Para el día a día, medium o high son un buen punto de partida.

Además, si envías un mensaje mientras Pi trabaja, se pone en cola y se usa para guiar la siguiente respuesta. No tienes que esperar a que termine para darle la siguiente instrucción.

Custom Prompts

Si repites siempre la misma instrucción de varios pasos, puedes guardarla como un prompt template: un archivo Markdown que se convierte en un comando /.

Lo más práctico es pedírselo al propio Pi:

Crea un custom prompt para hacer review de código frontend en React

Pi consulta su propia documentación, genera el archivo (por ejemplo review-react) y te dice dónde lo guardó. Luego ejecuta /reload y ya puedes usarlo como /review-react.

Los prompts de usuario se guardan en ~/.pi/agent/prompts/ y los de proyecto en .pi/prompts/.

¿En qué se diferencian de las skills?

  • Custom prompts: se ejecutan solo cuando los llamas. Son como un snippet de Markdown reutilizable.
  • Skills: el modelo las carga automáticamente cuando la tarea coincide con su descripción, y pueden incluir scripts y archivos de apoyo.

Skills

Las skills son carpetas con un archivo SKILL.md que le dan al agente instrucciones especializadas para un tipo de trabajo. Pi implementa la especificación de Agent Skills, así que las skills que usas en otros agentes también funcionan aquí.

Pi solo agrega al contexto el nombre y la descripción de cada skill; las instrucciones completas se cargan cuando la tarea lo requiere. Así ahorras tokens.

Dónde busca las skills

  • ~/.pi/agent/skills/ (skills de usuario de Pi)
  • .pi/skills/ (skills del proyecto)
  • ~/.agents/skills/ y .agents/skills/ (ubicaciones estándar de Agent Skills)

Por eso, si ya instalaste skills en la carpeta estándar para otros agentes, Pi las detecta de inmediato. También puedes agregar rutas extra desde la configuración.

Instalar skills desde skills.sh

En skills.sh encuentras un directorio de skills de todo tipo: diseño frontend, control del navegador, mejores prácticas y más. Copias el comando de instalación, lo pegas en tu terminal y el instalador te pregunta en qué agentes y a qué nivel (global o proyecto) instalarla. Al instalarla en la carpeta estándar .agents, Pi la carga sin configuración extra.

Luego puedes usarla de dos formas:

  1. Automática: describe la tarea y deja que el modelo la cargue. Por ejemplo: "Crea una app de tareas con JavaScript y haz que tenga un buen diseño frontend" activa la skill de diseño frontend.
  2. Explícita: fuerza la carga con /skill:nombre, por ejemplo /skill:frontend-design.

Las skills no solo dan instrucciones: también pueden ejecutar acciones. Por ejemplo, con una skill de Playwright CLI el agente puede abrir el navegador, probar tu aplicación y reportarte los resultados (pídele el modo headed si quieres ver la ventana).

Crear tu propia skill

También puedes pedirle a Pi que cree una skill por ti:

Crea un skill llamado tester-deploy que use Playwright CLI para testear el
proyecto en modo headed. Si todo pasa, haz commit y push. Si falla, dame un
resumen corto con opciones para decidir.

Los nombres de las skills van en minúsculas, con guiones entre palabras. Después de crearla, ejecuta /reload y ya está disponible.

🎥 Si quieres entender las skills a fondo, mira mi video sobre skills: [ENLACE VIDEO SKILLS]

Themes

Puedes cambiar el tema desde /settings, en la opción de tema (vienen light y dark). También puedes crear el tuyo pidiéndoselo a Pi:

Crea un tema para Pi basado en los colores de Tokyo Night

Pi genera el archivo JSON del tema. Ejecuta /reload, vuelve a /settings y selecciónalo. Los temas de usuario se guardan en ~/.pi/agent/themes/. Más detalles en la documentación de temas.

Context

Para que el agente siga reglas del proyecto sin repetírselas en cada conversación, Pi lee archivos de contexto: AGENTS.md y también CLAUDE.md.

  • Pi los carga desde su carpeta de configuración, desde la carpeta de trabajo y desde las carpetas padre.
  • Solo necesitas uno de los dos. Lo recomendable es AGENTS.md, que es el estándar.
  • Mantenlo corto y al grano: se carga en el contexto en cada petición.

Pi no tiene un comando /init, pero basta con pedirle: "Crea un archivo AGENTS.md para este proyecto".

Además, en la parte inferior verás el porcentaje de contexto usado. Cuando se acerca al límite, Pi compacta el historial automáticamente (más detalles en Sessions).

Extensiones

Las extensiones son la característica más poderosa de Pi y una de las razones por las que muchos lo eligen. Son archivos TypeScript (el mismo lenguaje en que está hecho Pi) que pueden:

  • Agregar o cambiar elementos de la interfaz.
  • Crear comandos y herramientas nuevas.
  • Reaccionar a eventos (por ejemplo, antes de ejecutar una herramienta).
  • Cambiar el comportamiento del agente, el enrutado de modelos y más.

Tampoco necesitas escribir el código tú mismo: le pides a Pi que cree la extensión. Algunos ejemplos:

Crea una extensión que muestre un ASCII art que diga "Pi" cada vez que inicio sesión

Crea una extensión que muestre siempre el directorio actual en la interfaz de Pi

Crea una extensión que me pida confirmación cada vez que se vaya a eliminar un archivo

Esta última es especialmente útil porque, como vimos, Pi no trae un sistema de permisos.

Las extensiones de usuario se guardan en ~/.pi/agent/extensions/. Después de crear una, reinicia Pi o ejecuta /reload. Para eliminarla, puedes pedírselo al mismo Pi: "Lista las extensiones que he creado y elimina la de ASCII art".

Packages

Los paquetes agrupan extensiones, skills, prompts y temas en una sola unidad que se instala con un comando. Se distribuyen por npm o git:

pi install npm:@usuario/paquete
pi install git:github.com/usuario/paquete
pi list
pi remove <paquete>

En la galería de paquetes encontrarás paquetes de la comunidad para agregar lo que Pi no trae de fábrica. Te recomiendo guiarte por la cantidad de descargas. Algunos tipos de paquetes útiles:

  • Modo "calm": oculta la ejecución de cada herramienta y solo muestra la respuesta final, para una interfaz menos saturada.
  • Listas de tareas al estilo Claude Code.
  • Modo plan: el agente analiza el proyecto, te hace preguntas y te propone un plan antes de implementar.
  • Soporte para MCP: Pi no soporta MCP de fábrica, pero hay paquetes que lo agregan para conectar tu agente con servicios externos como Notion, Google Calendar, Jira o Stripe.
  • Subagentes y tareas en segundo plano.

⚠️ Los paquetes pueden ejecutar código en tu máquina. Revisa el código fuente de los paquetes de terceros antes de instalarlos.

MCP vs skills

Mucho de lo que antes se hacía con MCPs hoy también se puede hacer con skills y herramientas de consola. Por lo general, las skills consumen menos tokens y son más fáciles de crear, pero algunos servicios solo ofrecen MCP, así que conviene tener ambas opciones.

🎥 Comparo ambos enfoques en detalle en este video: [ENLACE VIDEO SKILLS VS MCP]

Sessions

Pi guarda cada conversación automáticamente como una sesión, en ~/.pi/agent/sessions/, agrupada por carpeta de trabajo y en formato JSONL.

Acción Comando
Continuar la última sesión de la carpeta pi --continue
Elegir una sesión guardada pi --resume o /resume
Nueva sesión /new
Ponerle nombre a la sesión /name frontend
Ver el historial como árbol y volver a un punto anterior /tree
Crear una sesión nueva desde un mensaje anterior /fork
Copiar la rama actual en una nueva sesión /clone
Compactar el historial para ahorrar contexto /compact

Nombrar sesiones es útil cuando trabajas en paralelo, por ejemplo una sesión frontend y otra tester.

Con /tree puedes volver a un mensaje anterior sin perder el camino que dejas atrás: Pi guarda las ramas y puede resumir la rama abandonada para conservar lo relevante.

Y con /compact reduces el historial cuando el contexto se llena. Conviene hacerlo antes de llegar a porcentajes altos, porque con el contexto muy lleno los modelos suelen responder peor.

Preguntas frecuentes

¿Pi Agent es gratis?

Sí, Pi es de código abierto (licencia MIT). Solo pagas el modelo que uses, ya sea con una suscripción o por API.

¿Qué modelos puedo usar con Pi?

Modelos de OpenAI, Anthropic, Google, DeepSeek, Kimi, OpenRouter, Amazon Bedrock y muchos más, además de modelos locales y endpoints compatibles.

¿Pi soporta MCP?

No de fábrica, pero puedes agregarlo instalando un paquete de la comunidad.

¿Las skills de Claude Code funcionan en Pi?

Sí. Pi implementa el estándar Agent Skills y lee las carpetas .agents/skills. También puedes agregar rutas de otros agentes en la configuración.

¿En qué lenguaje se escriben las extensiones?

En TypeScript. Pero puedes pedirle al propio Pi que las escriba por ti.

Conclusión

Pi no intenta darte todo resuelto: te da una base mínima y las herramientas para construir tu propio agente. Si te gusta tener control sobre tus herramientas, poder cambiar de modelo sin atarte a un proveedor y ajustar cada detalle de tu flujo de trabajo, vale la pena probarlo.

¿Tienes dudas o quieres ver algún flujo en particular con Pi? Déjalo en los comentarios del video.

Recursos

¿Necesitas ayuda para configurar agentes de IA en tu flujo de trabajo? En fazt.dev puedes reservar asesorías personalizadas.