Usar Pi

Un perfil de modelo puede nombrar un harness, el CLI de agente en el que corren sus soldiers. Claude Code es el default. Con "harness": "pi" los soldiers de ese perfil corren en Pi, que puede usar casi cualquier proveedor y modelo, incluidos los planes gratuitos. El commander es una sesión de Claude Code salvo que también lo corras en Pi (ver Pi como commander), y una tarea conserva su harness a través de vx redispatch, vx prompt, vx decide, vx land y vx strike.

Esta página describe lo que se verificó contra Pi 1.3.0. vx doctor advierte con cualquier otra serie mayor. Para perfiles de ejemplo con modelos gratuitos y baratos, mirá Modelos para otros harnesses.

PrepararloCopiar enlace

1. Instalá Pi. Sirve el instalador o npm:

   Copiar

   curl -fsSL https://pi.dev/install.sh | sh
   npm install -g --ignore-scripts @earendil-works/pi-coding-agent

2. Corré pi una vez e iniciá sesión en un proveedor con /login, o exportá la API key del proveedor. pi --list-models lista lo que tu cuenta puede usar.

3. Instalá la integración de herdr para Pi, así herdr lee el estado de un soldier de Pi (working, idle) del propio Pi en lugar de leer la pantalla:

   Copiar

   herdr integration install pi

4. Corré vx doctor. Cuando un perfil selecciona pi, o hay un binario pi en tu PATH, informa el binario, su versión y la integración. Solo advierten: una pieza faltante nunca deja el entorno como no listo, y una configuración sin Pi no ve ninguna de estas líneas.

Agregar un perfilCopiar enlace

Agregá un perfil con "harness": "pi" a .vexillum/models.json (o al global ~/.vexillum/models.json):

{
  "profiles": {
    "pi-scout": {
      "model": "anthropic/claude-haiku-4-5",
      "effort": "low",
      "when": "Scout cuya pregunta se reduce a hechos verificables, corrido en Pi.",
      "harness": "pi"
    }
  }
}

vx dispatch "which flags does the build script accept?" --kind scout --profile pi-scout

En un perfil de Pi los dos campos significan:

vexillum revisa solo la forma: un model tiene que verse como provider/id, y effort tiene que ser uno de los niveles de Pi. Los modelos de Pi son los que ofrezcan tus proveedores, así que no puede comprobar que un modelo exista; eso lo informa Pi cuando arranca el soldier. Pi además ajusta un nivel de thinking que el modelo no soporta al más cercano que sí soporta, así que xhigh en un modelo que llega hasta high corre en high. Un alias de claude como sonnet no es un provider/id, y pasar un perfil existente a pi sin darle un modelo provider/id es un error que nombra el archivo y el campo. Una capa posterior se revisa contra el harness con el que termina el perfil, así que un archivo de proyecto puede retocar un perfil de pi de la base global.

Ids de modelo que terminan en :freeCopiar enlace

Pi lee un sufijo :level en --model como un nivel de thinking, y algunos ids terminan en un segmento con dos puntos propio, como el :free de OpenRouter. vexillum nunca arma ese sufijo: dejá el id completo en model y poné el nivel de thinking en effort, que se pasa con --thinking. Pi busca un id de modelo exacto antes de buscar un sufijo, así que openrouter/meta-llama/llama-4-scout:free se toma como el id que es. No escribas ...:free:high en model.

En qué se diferencia de un soldier de Claude CodeCopiar enlace

Soldiers blockedCopiar enlace

Cada soldier de Pi arranca con una extension chica de vexillum que le da una herramienta ask_user: una pregunta, las respuestas probables como opciones, y siempre una forma de escribir otra. La extension viene dentro del binario vx y se escribe en ~/.vexillum/projects/<key>/pi/ask_user.ts cuando despachás, y se carga con pi -e. No se agrega nada al camp, el aviso de confianza del proyecto de Pi nunca le aplica, y nada salvo el propio Pi la ejecuta (no hay que instalar Node ni Python).

Mientras el soldier espera en ask_user:

1. la extension guarda la pregunta y sus opciones en ~/.vexillum/projects/<key>/asks/<task-id>/ y le avisa a herdr que el soldier está blocked, que es lo único para lo que la integración de herdr para Pi reporta eso;
2. el sentinel marca la tarea blocked, despierta al commander y guarda la pregunta como la decision de la tarea con "kind": "ask", sus opciones y un question_id;
3. vos respondés, y el soldier sigue con tu respuesta como resultado de la herramienta.

vx status
vx decide <task-id> 2                      # el número de una opción, desde 1
vx decide <task-id> "Use the existing helper"   # el texto exacto de una opción, o cualquier texto

vx decide escribe la respuesta en un archivo que la extension está esperando, dirigida al id de esa pregunta, y espera a que la extension la tome. No se teclea nada en el pane. Se usa un archivo y no pulsaciones de tecla porque lo que hace una tecla depende de cuál de los diálogos de Pi está abierto y dónde está su cursor, y un prompt enviado a Pi mientras corre una herramienta queda en cola como mensaje de dirección en vez de responder a la herramienta. También podés responder vos mismo en el pane del soldier: el diálogo se cierra igual, y la tarea vuelve sola a running. Si después corrés vx decide, se niega con un mensaje de que la pregunta ya no está abierta, y vx decide <task-id> --dismiss limpia la tarea.

Los archivos guardan solo la pregunta y las opciones que escribió el soldier y tu respuesta: un question.json y un answer.json, legibles solo por vos. Se borran apenas la pregunta se cierra.

Si la extension no se cargó (un Pi viejo, o un pi que falló al arrancar), el soldier no tiene ask_user. Su prompt le dice entonces que termine su turno con una línea needs-decision:, la tarea pasa a blocked con una decision de prosa, y vx decide escribe tu respuesta en el pane como texto plano, así que escribí la respuesta misma y no un número de opción. vx doctor no revisa la extension, porque se carga recién cuando arranca un soldier: si un soldier ignora ask_user, mirá su pane por una línea de Pi sobre la extension, y mirá la checklist del repositorio para confirmar que se cargó.

Si la integración de herdr para Pi no está instalada, herdr no ve al soldier como blocked mientras espera. El sentinel igual bloquea la tarea a partir del archivo de la pregunta abierta, en unos segundos. --dismiss funciona como en cualquier tarea. Ver Blocked e interrupted.

No está en este releaseCopiar enlace

• Skills para los soldiers de Pi.

Para una checklist con la que verificar una configuración de Pi en una máquina real, mirá docs/verification/pi-soldier-checklist.md en el repositorio.

RelacionadoCopiar enlace

• models.json
• vx dispatch y vx doctor
• Blocked e interrupted
• Pi como commander