Guía de Configuración de Pi Coding Agent: Instala, Configura Modelos y Mejores Extensiones

He estado usando OpenCode y Hermes Agent durante un tiempo, pero Pi seguía apareciendo en conversaciones. La gente en Reddit y Hacker News lo llamaba “el mínimo que no se interpone en tu camino.” Después de dos semanas de uso diario, entiendo por qué. Pi es un agente de codificación en terminal creado por Mario Zechner que se mantiene pequeño en el núcleo. Lo instalas, lo apuntas a un proyecto, y empiezas a trabajar. Todo lo demás — memoria, soporte MCP, sub-agentes, temas, habilidades — se añade a través de extensiones que tú eliges.

Ese minimalismo es el punto. Donde OpenCode se envía con una TUI, modo plan y soporte de imágenes desde el inicio, Pi te da una base limpia y un sistema de extensiones en TypeScript. Construyes el agente que quieres en lugar de desactivar las funciones que no necesitas.

Esta guía cubre la instalación, configuración de modelos con proveedores baratos, las extensiones que merece la pena instalar, y cómo saltarte la fase de investigación con LazyPi.

Si todavía estás decidiendo entre agentes de codificación, nuestra guía de OpenCode cubre la alternativa open source a Claude Code, y el artículo de alternativas a GitHub Copilot analiza qué hacer tras el cambio de precios del 1 de junio.

Qué es realmente Pi

Pi es un agente de codificación en terminal que lee tu base de código, planifica cambios, edita archivos, ejecuta comandos de shell, e itera cuando hay errores. La instalación por defecto te da cuatro herramientas: lectura, escritura, edición y bash. Eso es todo. Sin modo plan, sin soporte MCP, sin memoria, sin sub-agentes. Los añades a través de extensiones.

El sistema de extensiones es TypeScript. Dejas un archivo .ts en ~/.pi/agent/extensions/ y Pi lo carga. Las extensiones pueden registrar herramientas personalizadas que el LLM puede llamar, interceptar llamadas a herramientas antes de que se ejecuten (para bloquear rm -rf por ejemplo), añadir comandos slash, modificar el prompt del sistema, y construir componentes de TUI personalizados. Puedes recargarlas en caliente con /reload sin reiniciar Pi.

Instalando Pi

Pi se distribuye como un paquete npm.

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

Luego ejecútalo en el directorio de un proyecto:

cd /ruta/al/proyecto
pi

Pi necesita Node.js 18+. Si no tienes Node, instálalo primero:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

docker run -it --rm -v $(pwd):/workspace -w /workspace node:22 \
  npx @mariozechner/pi-coding-agent

Autenticación

Pi soporta dos enfoques de autenticación. Elige el que te convenga.

Inicio de sesión con suscripción — si tienes Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, o Google Gemini CLI:

pi
/login
# Selecciona tu proveedor

Clave API — para acceso directo al proveedor u OpenRouter:

export ANTHROPIC_API_KEY=sk-ant-...
pi

O guarda las claves en ~/.pi/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openrouter": { "type": "api_key", "key": "sk-or-..." }
}

Las entradas del archivo de autenticación tienen prioridad sobre las variables de entorno.

Configurando modelos

Aquí es donde Pi se vuelve interesante. Puedes conectar cualquier proveedor de modelos a través de variables de entorno, el archivo de autenticación, o un archivo models.json personalizado.

Usando proveedores integrados

Pi tiene soporte integrado para estos proveedores:

Configura la clave y Pi auto-descubre todos los modelos de ese proveedor:

export OPENROUTER_API_KEY=sk-or-...
pi
# /model muestra todos los más de 200 modelos de OpenRouter

Añadiendo modelos personalizados con models.json

Para proveedores que no están integrados — o para Ollama, LM Studio, vLLM, y cualquier API compatible con OpenAI — crea ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

El campo apiKey es obligatorio pero Ollama lo ignora, así que cualquier cadena funciona. El archivo se recarga cada vez que abres /model, así que puedes editarlo durante una sesión sin reiniciar Pi.

Para modelos locales que no soportan el rol developer usado por modelos de razonamiento, añade flags de compatibilidad:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "qwen3.6:27b",
          "reasoning": true
        }
      ]
    }
  }
}

Conectando a OpenRouter para modelos baratos

OpenRouter es la forma más fácil de acceder a todos los modelos asequibles en un solo lugar. Configura tu clave:

export OPENROUTER_API_KEY=sk-or-...

Luego usa /model en Pi para elegir de la lista completa. Los modelos que sigo usando:

Para un análisis completo de estos modelos con benchmarks y precios, consulta la guía de mejores modelos baratos para Hermes Agent — los mismos modelos funcionan con Pi.

Usando OpenCode Go con Pi

OpenCode Go es una suscripción de $10/mes que incluye 12 modelos como MiniMax M2.7, Qwen 3.6 Plus, GLM 5.1, DeepSeek V4 Pro, y Kimi K2.6. Pi lo soporta como proveedor integrado. Para un análisis detallado, consulta la guía de OpenCode Go.

export OPENCODE_API_KEY=tu-clave-opencode-go
pi
# /model, selecciona el proveedor opencode-go

Sobrescribiendo URLs de proveedores integrados

Si quieres enrutar un proveedor integrado a través de un proxy, añade una entrada mínima a models.json:

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://mi-proxy.example.com/v1"
    }
  }
}

Todos los modelos integrados de Anthropic permanecen disponibles. La autenticación existente sigue funcionando.

Instrucciones del proyecto con AGENTS.md

Pi carga archivos de contexto al inicio. Crea un archivo AGENTS.md en la raíz de tu proyecto:

# Instrucciones del Proyecto

- Ejecuta `npm run check` después de cambios en el código.
- No ejecutes migraciones de producción en local.
- Usa el patrón existente de manejo de errores en src/errors/.
- Mantén las respuestas concisas.

Pi carga ~/.pi/agent/AGENTS.md para instrucciones globales y AGENTS.md desde directorios padre y el directorio actual. Ejecuta /reload después de cambios.

Extensiones que merece la pena instalar

Las extensiones son donde Pi se convierte en algo más que un agente básico. Aquí están las que marcan una diferencia real.

Extensiones que hacen a Pi más inteligente

pi-memory-md — Memoria persistente almacenada como archivos Markdown. El agente recuerda lo que aprendió sobre tu proyecto entre sesiones. Sin esto, Pi empieza desde cero cada vez. Esta es la primera extensión que instalo.

pi-mcp-adapter — Conecta Pi a cualquier servidor de herramientas compatible con MCP. GitHub, Playwright, Brave Search, Postgres, Notion, Slack — cualquier servidor MCP funciona. Si usas MCP con otros agentes como Hermes o OpenClaw, esto te permite reutilizar las mismas herramientas.

pi-subagents — Ejecuta sub-agentes aislados para trabajo paralelo. Cuando una tarea tiene partes independientes, los sub-agentes las abordan simultáneamente en lugar de hacer todo en secuencia.

pi-plan — Modo de planificación de solo lectura con ejecución basada en aprobación. Como el modo plan de OpenCode con Tab. Pi describe lo que haría, tú revisas, luego apruebas. Más seguro para código en producción.

Extensiones que te ahorran tiempo

pi-web-access — Búsqueda web y obtención de URLs dentro de Pi. El agente puede buscar documentación, consultar Stack Overflow, o obtener referencias de API sin salir de la terminal.

pi-autoresearch — Bucle de investigación de larga duración. Dile a Pi que investigue un tema e itera — buscando, leyendo, resumiendo, buscando de nuevo — hasta tener una respuesta completa.

pi-simplify — Revisa el código cambiado recientemente para claridad y consistencia. Después de que el agente haga cambios, ejecuta esto para detectar problemas de estilo y código muerto.

Extensiones que mejoran la interfaz

pi-powerbar — Línea de estado mostrando nombre del modelo, uso de tokens y estado del contexto de un vistazo. Algo pequeño que marca una gran diferencia cuando cambias de modelo frecuentemente.

pi-usage-extension — Rastrea el uso de tokens y el coste de la API en la sesión. Si estás intentando reducir costes con modelos baratos, esto te muestra exactamente cuánto cuesta cada solicitud.

pi-manage-todo-list — Seguimiento de trabajo multi-paso con un widget de progreso en vivo. Divide una tarea en pasos, rastrea qué está hecho, qué está en progreso, qué queda.

pi-btw — Haz preguntas rápidas secundarias sin contaminar el historial de la conversación. Útil para “espera, ¿qué hace esta función otra vez?” sin descarrilar tu tarea actual.

pi-add-dir — Carga directorios de proyecto adicionales en la sesión actual de Pi. Si tu trabajo abarca múltiples repos, esto permite a Pi verlos todos.

Instalando extensiones

Las extensiones de un solo archivo van directamente en el directorio de extensiones:

# Ejemplo: copiar una sola extensión
cp ask-user-question.ts ~/.pi/agent/extensions/

Extensiones de directorio:

# Copiar el directorio
cp -r pi-memory-md ~/.pi/agent/extensions/

# Instalar dependencias npm si la extensión tiene package.json
cd ~/.pi/agent/extensions/pi-memory-md
npm install

Luego reinicia Pi o ejecuta /reload.

LazyPi: un comando, todo configurado

Si no quieres investigar y elegir extensiones individuales, LazyPi lo hace por ti.

npx @robzolkos/lazypi

Esto instala Pi si no lo tienes, luego añade:

Puedes instalar todo a la vez o usar el selector interactivo para elegir paquetes específicos. Al re-ejecutar el comando se salta lo que ya está instalado.

El catálogo de LazyPi incluye todas las extensiones listadas arriba además de más de 60 habilidades comunitarias y 76 temas de terminal (Dracula, Nord, Gruvbox, Tokyo Night, Kanagawa, y más).

Configuración comunitaria: pi-config

El repositorio pi-config de amosblomqvist es una colección curada de habilidades y extensiones personales para Pi. No está pensado para instalarse como un solo paquete — explora el repositorio y copia lo que necesites.

Qué contiene

Extensiones:

• bash-guard — bloquea comandos peligrosos antes de que se ejecuten
• context.ts — carga contexto adicional desde fuentes externas
• filechanges — rastrea modificaciones de archivos entre turnos
• google-image-search — busca en Google Images desde Pi
• memory.ts — otra implementación de memoria persistente
• subagents — soporte para sub-agentes
• web-fetch — obtén y lee páginas web
• web-search — integración de búsqueda web
• youtube-search — busca en YouTube desde Pi
• video-extract — extrae información de URLs de vídeo
• zz-read-only-mode — fuerza el modo de solo lectura (bloquea todas las escrituras)

Habilidades:

• orchestrator — coordina flujos de trabajo multi-paso
• pdf-reader — lee y extrae texto de archivos PDF
• reddit — busca y lee posts de Reddit
• stop-slop — evita que el agente genere contenido de baja calidad

Cómo usarlo

# Copiar una extensión de un solo archivo
cp extensions/ask-user-question.ts ~/.pi/agent/extensions/

# Copiar una extensión de directorio
cp -r extensions/web-fetch ~/.pi/agent/extensions/

# Instalar dependencias si es necesario
cd ~/.pi/agent/extensions/web-fetch
npm install

# Copiar una habilidad
cp -r skills/reddit ~/.pi/agent/skills/

# Recargar
# En Pi: /reload

Algunas extensiones necesitan herramientas del sistema:

# Para youtube-search y video-extract
brew install yt-dlp ffmpeg

# Para pdf-reader
python3 -m venv ~/.pi/agent/skills/pdf-reader/.venv
~/.pi/agent/skills/pdf-reader/.venv/bin/pip install -r ~/.pi/agent/skills/pdf-reader/requirements.txt

pi_agent_rust: el puerto en Rust

Si quieres el mismo concepto de agente pero compilado en un solo binario con inicio más rápido y menor uso de memoria, está pi_agent_rust.

Qué es

Un agente de codificación IA CLI de alto rendimiento escrito en Rust con código cero unsafe. 823 estrellas en GitHub, 2,812 commits, 13 releases, y desarrollo activo (el último commit fue hace horas al momento de escribir). Es una implementación desde cero en Rust que soporta las mismas siete herramientas integradas que Pi (read, write, edit, bash, grep, find, ls) además de proveedores Anthropic y OpenAI con streaming.

Por qué podrías quererlo

• Binario único — no necesita Node.js. El binario de release ocupa menos de 8MB.
• Tiempo de inicio — 12ms frente a varios cientos de milisegundos de la versión Node.js.
• Ecosistema de extensiones — soporta extensiones TypeScript a través de un runtime QuickJS integrado, así que las extensiones existentes de Pi funcionan.
• Seguridad — modelo de amenazas formal, pruebas de fuzz, forbid(unsafe_code), y más de 60 páginas de documentación de seguridad.
• Gestión de sesiones — sesiones con SQLite con navegación por ramas y árbol.

Instalando pi_agent_rust

# Instalador de una línea
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh | bash

O compila desde la fuente:

git clone https://github.com/Dicklesworthstone/pi_agent_rust.git
cd pi_agent_rust
cargo build --release
# Binario en target/release/pi

Cuándo usar el puerto en Rust

El puerto en Rust es mejor para quienes quieren el agente de terminal más rápido posible, ejecutan en máquinas con recursos limitados, o prefieren una distribución de binario único. La versión Node.js tiene el ecosistema de extensiones más grande y más desarrollo comunitario activo. Ambos leen los mismos archivos models.json y auth.json, así que puedes cambiar entre ellos sin reconfigurar.

Pi vs OpenCode vs Claude Code

Pi empieza más pequeño pero crece a través de extensiones. Si quieres construir tu propio flujo de trabajo de agente desde partes, Pi es la mejor base. Si quieres que todo funcione desde el inicio, OpenCode te lleva ahí más rápido.

Consejos para el flujo de trabajo diario

Cambiando modelos

Usa /model o Ctrl+L para elegir un modelo. Usa Shift+Tab para ciclar el nivel de razonamiento. Usa Ctrl+P / Shift+Ctrl+P para ciclar entre modelos con ámbito.

Referenciando archivos

Escribe @ en el editor para buscar archivos por fuzzy-search, o pásalos en la línea de comandos:

pi @README.md "Resume esto"
pi @src/app.ts @src/app.test.ts "Revisa estos juntos"

Ejecutando comandos de shell

Prefija con ! para ejecutar un comando y enviar su salida al modelo:

!npm run test

Usa !! para ejecutar un comando sin añadirlo al contexto.

Sesiones

Las sesiones se guardan automáticamente. Continúa tu última sesión:

pi -c

Navega sesiones anteriores:

pi -r

Dentro de Pi, usa /resume, /new, /tree, /fork, y /clone para gestionar sesiones.

Modo no interactivo

Para prompts de una sola vez en scripts o CI:

pi -p "Resume esta base de código"
cat README.md | pi -p "Resume este texto"
pi -p @captura.png "¿Qué hay en esta imagen?"

Usa --mode json para salida estructurada o --mode rpc para integración con procesos.

Ejecutando Pi en un VPS

Pi funciona sobre SSH. Lo ejecuto en un VPS de $6/mes y me conecto desde mi portátil.

# Usa tmux para que las sesiones sobrevivan desconexiones
tmux new -s pi
cd /ruta/al/proyecto
pi

Desconecta con Ctrl+B, D y reconecta después con tmux attach -t pi.

Para una mejor experiencia SSH, usa mosh:

mosh user@tu-ip-vps

Preguntas Frecuentes

Para más guías de agentes IA, consulta la guía de Hermes Agent, la guía de OpenCode, y los mejores modelos baratos para cualquier agente de codificación. Para los cambios de precios de GitHub Copilot y lo que significan para tu flujo de trabajo, consulta el artículo de alternativas a Copilot. Para una comparación lado a lado de OpenCode y Pi, consulta la comparación de OpenCode vs Pi Agent.