Guía de pi.dev

En esta guía vamos a aprender cómo instalar Pi.dev, un agente minimalista de código que es ideal para utilizar junto a nuestro modelo de IA local.

Recuerda que para trabajar en Windows, se recomienda utilizar WSL, que permite trabajar como si fuera un entorno Linux dentro de Windows, sin necesidad de máquinas virtuales o emuladores. Por aquí tienes una serie de videos para instalar y configurar WSL.

Lo primero, es instalar Pi en nuestro sistema. Para ello, simplemente escribimos esto en una terminal:

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

Si prefieres instalarlo con pnpm, puedes hacerlo así pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent. Para comprobar que todo ha ido bien, al escribir pi --version debería mostrarnos la versión del agente.

Nuestro agente pi sirve para utilizar tanto con modelos LLM cloud como Claude, GPT u otros, pero también permite configurar nuestros propios modelos locales. Para ello, vamos a editar el fichero ~/.pi/agent/models.json. En este fichero necesitaremos tener la siguiente estructura:

{
  "providers": {
    "llama.cpp": {
      "baseUrl": "http://HOST_ANFITRION:8999/v1",
      "api": "openai-completions",
      "apiKey": "llama.cpp",
      "models": [
        { "id": "qwen3.6-35b-a3b-iq2-xss" }
      ]
    }
  }
}

En este fichero le estamos indicando que tenemos un provider que es nuestro motor de inferencia llama.cpp y le indicaremos la IP donde está escuchando. El texto HOST_ANFITRION debemos cambiarlo por la IP del sistema donde tenemos llama.cpp funcionando.

Si no la conoces, normalmente es la que te devuelve alguno de estos dos comandos:

grep -i nameserver /etc/resolv.conf | cut -d" " -f2
ip route | grep -i "default via" | cut -d" " -f3

El id que tenemos más abajo es simplemente indicativo, no importa mucho lo que escribamos ya que en llama-server solo vamos a tener un modelo, utilizará el que exista independientemente del nombre que tenga.

Esto no sólo sirve para modelos locales, puedes usar planes de OpenCode Go o OpenCode Zen, indicar la baseUrl: "https://opencode.ai/zen/v1/", poner tu API Key del plan e indicar los nombres de los modelos que quieres utilizar en models.

Con esta configuración mínima, ya deberíamos poder utilizar nuestro agente. Bastaría con acceder a la carpeta donde queremos trabajar y abrir el agente:

cd ~/workspaces
mkdir project-name
cd project-name
pi

Al arrancar te pedirá confiar en esa carpeta y darle permisos. Vigila siempre bien la carpeta donde estás trabajando, ya que el agente tendrá permisos para leer y modificar archivos.

Podemos escribirle un Hola para testear que funciona y nos devuelve una respuesta. En caso de que no sea así, revisa los pasos anteriores. No obstante, tenemos pi vacío, sin configuración, plugins ni funcionalidades adicionales, así que vamos a ello.

Según el modelo que utilicemos, además de las respuestas podremos ver sus «pensamientos» (thinking o reasoning). Aunque es interesante leerlos para comprender como está razonando, a veces pueden ser erráticos, redundantes o muy verbosos. Pulsando CTRL+T puedes ocultarlos o mostrarlos.

Para salir de pi, simplemente pulsa dos veces CTRL+C.

Por defecto, pi no tiene casi configuración inicial, por lo que tenemos un amplio rango de mejora para su funcionamiento. Podemos crear un archivo markdown ~/.pi/agent/SYSTEM.md para añadir un System Prompt con instrucciones generales que queremos que se cumplan siempre.

Un ejemplo de SYSTEM.md:

- Escribe siempre los mensajes en español (incluyendo el thinking/reasoning).
- Usa emojis para mensajes importantes o finales para resaltar temas.
- No ejecutes servidores locales de desarrollo. Se encargará el usuario.
- De vez en cuando cuenta algún chiste informático corto.

Aunque no se garantiza al 100% que el agente cumpla estas restricciones, es la forma más directa de conseguir que las siga casi siempre. Intenta mantener este archivo corto y breve.

El agente pi viene sin protección de serie, por lo que puede leer, acceder y modificar cualquier fichero. Esto es algo que puede llegar a ser peligroso, así que vamos a instalar un complemento para controlarlo un poco:

sudo apt install socat
pi install npm:pi-sandbox

Esto instalará los complementos necesarios para usar el complemento pi-sandbox. Para configurarlo, creamos el fichero ~/.pi/agent/sandbox.json con el siguiente contenido:

{
  "enabled": true,
  "allowBrowserProcess": false,
  "network": {
    "allowLocalBinding": true,
    "allowAllUnixSockets": true,
    "allowedDomains": ["github.com", "*.github.com"],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["/home"],
    "allowRead": [".", "~/.config", "~/.local"],
    "allowWrite": [".", "/tmp"],
    "denyWrite": [".env", ".env.*", "*.pem", "*.key"]
  }
}

Esta configuración realiza varias cosas:

• Activa pi-sandbox y no permite comunicarse con el navegador
• Permite acceso a URLs de github.com, el resto solicitará permiso
• Permite leer archivos de /home, ~/.config, ~/.local y la carpeta actual.
• Permite crear/modificar archivos en /tmp y en la carpeta actual.
• Deniega acceso a archivos sensibles como .env o similares.

El resto, pedirá permisos al usuario. Sé selectivo, vigila bien y no des permiso a cualquier cosa. Ten en cuenta que esto es sólo una capa de seguridad para evitar ciertos problemas graves. Por ejemplo, estamos impidiendo que se puedan leer ciertos archivos o carpetas directamente, pero el agente podría intentar hacerlo a través del sistema, y ahí, si el usuario tiene permisos, podrá hacerlo.

Si quieres mayor nivel de seguridad, una buena forma sería aislar todo en un contenedor de docker.

El agente pi tiene un catálogo con muchísimas extensiones para complementar nuestro agente. Aconsejo instalar las siguientes:

• pi install npm:@taterdoge/pi-status → Muestra una barra de estado con el modelo utilizado, la velocidad de tokens, el gasto realizado, el uso del contexto, entre otras cosas.
• pi install npm:pi-context → Con /context puedes ver selectivamente que está ocupando el contexto.

Si provienes de otros agentes como opencode quizás eches de menos el modo plan. Esto es muy fácil de simular en pi y me sirve de ejemplo para explicar como crear comandos personalizados a nuestro gusto, con las cosas que más utilicemos.

Simplemente, creamos un archivo markdown en ~/.pi/agent/prompts/plan.md. Despliega a continuación para ver el contenido del fichero:

---
description: "Analiza la solicitud en profundidad y elabora un plan de acción detallado sin escribir ningún código ni modificar archivos. El objetivo es razonar primero."
---

# Instrucciones

- La solicitud es: $@. Si el usuario no indica solicitud, haz una revisión genérica del proyecto.
- Leer y comprender completamente la solicitud antes de responder.
- Explorar el contexto relevante: archivos, estructura, dependencias, restricciones.
- Identificar ambigüedades: información faltante y listarlas explicitamente.
- Elaborar un plan paso a paso que describa que se va a hacer y por qué, sin implementar nada.
- Terminar con una pregunta de confirmación para saber si el plan es correcto o hay que ajustar algo.

# Reglas

- ❌ No escribas código funcional (fragmentos, pseudocódigo)
- ❌ No crees, edites ni elimines ningún archivo
- ❌ No ejecutes comandos de terminal
- ✅ Puedes leer archivos existentes para entender el contexto
- ✅ Puedes describir la solución con detalle técnico en lenguaje natural
- ✅ Puedes mostrar estructuras de datos, esquemas o diagramas en texto plano si ayudan a clarificar

# Formato de salida

- 🎯 Objetivo: Descripción concisa de lo que se quiere lograr
- 🔍 Análisis: Estado actual del proyecto y archivos/dependencias relevantes
- ❓ Dudas: Lista de preguntas o asunciones tomadas.
- 📋 Plan: Pasos numerados y ordenados de que se hará y por qué.
- ✅ Confirmación: ¿El plan es correcto? ¿Quieres ajustar algo?

• El nombre del fichero será el nombre del comando, en este ejemplo: /plan.
• Con $@ podemos hacer referencia a lo que escriba el usuario después del comando.
• Prueba a escribir /plan Dime puntos de mejora para este proyecto

De la misma forma, ¡puedes crear tus propios comandos personalizados!

De la misma forma que vimos en el apartado anterior como añadir comandos personalizados, también podemos añadir skills. Los skills simplemente son ayudas adicionales en forma de documentación que no están cargadas por defecto (salvo su descripción). El agente tendrá un índice con las descripciones de los skills, y cuando detecte que es algo relacionado los leerá completamente y aplicará. De esta forma podemos tener documentación valiosa para hacer determinados procesos y que no consuma contexto.

Los skills simplemente se crearán en ~/.pi/agent/skills/. Por cada skill que queramos cargar, crearemos una carpeta y en su interior un SKILL.md, por ejemplo: ~/.pi/agent/skills/js/SKILL.md:

---
name: javascript-vanilla
description: Escribe Javascript moderno (JS vanilla), DOM y webcomponents
license: MIT
metadata:
  author: manzdev
  version: "1.0"
---

# Instrucciones

- Por defecto, no escribas código Typescript ni JSDoc salvo que se pida específicamente.
- Usa comillas dobles por defecto. No uses comillas simples salvo que esté justificado.
- Si creas un WebComponent, el nombre debe estar en PascalCase, asociado a una etiqueta HTML en kebab-case.
- Los string template que contengan código HTML deben ir precedidos de un comentario `/* html */`. Ejemplo: return /* html */`<div>...</div>`;
- Los estilos de los WebComponents deben estar en un fichero `.css` separado con el mismo nombre. Se importarán utilizando `import styles from "./FileName.css" with { type: "css" }` y se añadirán usando la API `adoptedStyleSheets`.
- Usa la API `setHTMLUnsafe()` en lugar de `innerHTML` siempre que puedas.
- Evita el uso de `getElementByID()`. En su lugar usa siempre `querySelector()` o `querySelectorAll()`.
- Evita el uso de `appendChild()` a favor de `append()`, `before()`, `prepend()` y `after()`.
- Si necesitas escribir propiedades/métodos privados de clase en Javascript, usa `#` en lugar de `_` (convenio). Recuerda declararlas a nivel de clase previamente al constructor.
- En el fichero `.css` aplica nesting CSS en las reglas que sea evidente que dependen fuertemente de su padre.

Una vez guardados, pi será capaz de cargar ese skill si se necesita. Si queremos forzar a cargarlo, simplemente escribimos /skill: seguido del nombre del skill. En nuestro ejemplo: /skill:javascript-vanilla.

Recuerda intentar siempre mantener el fichero de skills lo más pequeño y compacto posible. Si tienes temas que no están relacionados, crea ficheros de skills diferentes.