pi-portable

Setup portable de PI (agentes, extensiones, skills) listo para instalar en cualquier máquina.

La config de Herdr (tema, plugins, fuente) es otro repo: herdr-portable. Este no la despliega. Siguen aquí las piezas de PI que hablan con Herdr: skill herdr, herdr-blocked, subagent-minion-status, paquete pi-herdr-subagents.

Qué incluye

• Parent por defecto: /ship — Go Flash orquesta y scout (low). GLM-5.3-Flash planifica (high, 2× Go, pocas llamadas). Composer pica (low). Grok revisa (high, one-shot). /opus solo cambia el reviewer a Opus. Nunca cli: claude/cursor.
• Overflow: /nogo (Go 429) · /codex (Cursor 429) · /codexonly · /go · /zen (Zen free, $0)
• 6 agentes: planner, reviewer, scout, worker, researcher, visual-tester
• Extensiones: goal, autonomy, custom-header, memory, read-only, filechanges, bash-guard, herdr-blocked, video-extract, youtube-search, ask-user-question, context, md-link, help, claude-sub, profile (/ship, /nogo, /opus, /codex, /codexonly, /go, /zen — ver /profiles), cache-miss-alarm, subagent-result-trim, subagent-minion-status, context-inspector, cost-rollup
• Paquetes npm (9): pi-mcp-adapter, pi-observational-memory, pi-herdr-subagents, pi-cache-optimizer, @dietrichgebert/ponytail, pi-web-access, @quartermaster-labs/pi-on-demand-context, @netandreus/pi-cursor-provider, @juicesharp/rpiv-todo
• Paquete git: pi-repomap (EnTeQuAk) — mapa tree-sitter + PageRank, cache .pi/cache/repomap.json; scout/worker usan tool repomap
• Skills: 3 — reddit, stop-slop, herdr
• MCP: obsidian (apuntando al vault 500 AI)
• Tema: lavender — tema custom de la TUI (config/themes/lavender.json), a juego con el logo lavanda de custom-header.ts

Requisitos

• pi CLI instalado (npm install -g @mariozechner/pi-coding-agent)
• herdr en PATH si vas a delegar minions — configúralo con herdr-portable, no con este repo
• Fish shell (para el alias pi-yolo)
• Node.js + npm
• Toolchain C++ para tree-sitter (g++/clang++, python3, make) — pi-repomap; en Node reciente suele hacer falta CXXFLAGS=-std=c++20
• Login del plan OpenCode Go en pi (pi auth, entrada opencode-go en ~/.pi/agent/auth.json) — parent, scout y planner GLM
• Suscripción Cursor Pro + pi-cursor-provider — worker Composer y reviewer Grok de /ship y /nogo
• Claude Pro via claude-sub — solo reviewer de /opus (quema puntual)
• ChatGPT Plus / Codex — overflow /nogo (Luna orquesta) y /codexonly (Luna orquesta/pica, Terra max). /codex (Cursor 429) sigue en Go: Flash pica, GLM juzga.
• API keys de crof, DeepSeek directo, Synthetic, Vercel (opcionales — fuera del stack de perfiles de suscripción)

Instalación

git clone https://git.okvicio.club/vicio/pi-portable.git
cd pi-portable
./install.sh

El script:

1. Detecta la máquina por hostname y fija VAULT_ROOT (LXC, .env, o prompt)
2. Carga el .env si existe
3. Comprueba las API keys (Synthetic obligatoria, prompt + persistencia en fish) y avisa si faltan el auth de opencode-go o claude
4. Crea ~/.pi/agent/ si no existe
5. Instala paquetes npm (pi-mcp-adapter, pi-observational-memory, pi-herdr-subagents, pi-cache-optimizer, @dietrichgebert/ponytail, pi-web-access, @quartermaster-labs/pi-on-demand-context, @netandreus/pi-cursor-provider, @juicesharp/rpiv-todo)
6. Copia agentes, extensiones, skills y configs a ~/.pi/agent/
7. Instala las dependencias npm de las extensiones empaquetadas (bash-guard, filechanges)
8. Restaura el config.json de pi-herdr-subagents (que npm update borra) y el patch de minions-tab
9. Instala pi-repomap (clone git + npm con legacy-peer-deps)
10. Añade el alias pi-yolo a fish si no está

API keys

Copia .env.example a .env y rellena las claves, o exporta las variables de entorno antes de lanzar pi-yolo:

set -Ux CROF_API_KEY "sk-..."
set -Ux DEEPSEEK_API_KEY "sk-..."
set -Ux SYNTHETIC_API_KEY "sk-..."
set -Ux VERCEL_API_KEY "..."
set -Ux OPENCODE_API_KEY "..."

El install.sh te pide la key de Synthetic (obligatoria) si falta y la persiste en fish (set -Ux); las demás solo avisan si faltan.

opencode-go no lleva env var ni entrada de apiKey: es un provider built-in de pi y su credencial vive en ~/.pi/agent/auth.json, la misma que crea pi auth. models.json solo lo sobrescribe con el bloque compat.

Uso

# Herdr (otro repo) si vas a delegar en panes:
#   git clone https://git.okvicio.club/vicio/herdr-portable.git && ./install.sh
herdr
# dentro del pane:
pi-yolo

Comandos clave dentro de PI:

• /daily — default: Flash orquesta/review · Composer pica (día a día)
• /ship — PRO Go (GLM plan/research, Grok arch/review, Composer pica)
• /terra — PRO Codex (Terra plan/research, Grok arch/review, Composer pica)
• /research <pregunta> — researcher del perfil (GLM en /ship, Terra en /terra)
• /architect <sistema> — diseño + amenazas (Grok; solo PRO)
• /scout <qué> · /review <qué> · /plan <qué> — recon, diffs, planning
• /goal <objetivo> — fija la meta persistente
• /autonomy on — activa el loop infinito
• /subagent <agente> <tarea> — delega a mano (el padre debe pasar model+thinking)
• /read-only on — modo auditoría
• /memory — toggle de MEMORY.md

Estructura del repo

pi-portable/
├── agents/              # 6 agentes con frontmatter (modelo + thinking)
├── extensions/          # extensiones (algunas propias: goal.ts, autonomy.ts, cost-rollup.ts; las empaquetadas versionan su package-lock.json)
├── skills/              # reddit, stop-slop, herdr
├── config/
│   ├── settings.json    # config principal de pi
│   ├── models.json      # providers y modelos (apiKey con env vars / comando)
│   ├── themes/
│   │   └── lavender.json          # tema custom de la TUI de pi
│   ├── mcp.json         # MCP obsidian (VAULT_ROOT se expande en install)
│   ├── npm-package.json # package.json mínimo para npm install
│   └── pi-herdr-subagents-config.json # routing de modelos (npm update lo borra)
├── .env.example         # plantilla de API keys
├── install.sh           # script de instalación portable
└── README.md            # esto

Trampas conocidas

• npm update en ~/.pi/agent/npm/ borra pi-herdr-subagents/config.json y el patch de spawn. El install.sh restaura ambos (config + patches/pi-herdr-subagents/ → tab minions · <padre> con splits).
• DeepSeek no tiene thinking low (solo high/max). Los agentes llevan thinking explícito.
• SYNTHETIC_API_KEY va en el entorno de fish, no en auth.json.
• pi -p no carga skills (modo no interactivo). Para pruebas usa pi interactivo y mira la cabecera con Ctrl+O.
• El vault de Obsidian se configura en mcp.json — el install.sh expande VAULT_ROOT según hostname.
• pi-cache-optimizer solo toca providers openai-completions/openai-responses — o sea todos los de models.json, pero no los providers de extensión que spawnean un subproceso (tipo claude-sub). Los dos conviven sin pisarse.
• pi-cache-optimizer no modifica models.json en operación normal; solo /cache-optimizer fix, y con preview + confirmación + backup con timestamp.
• El tema se referencia por nombre: settings.json dice "theme": "lavender" y el fichero vive en ~/.pi/agent/themes/lavender.json. Si copias settings.json sin el tema, pi cae al tema por defecto sin avisar. El install.sh despliega config/themes/ y verifica que el nombre tenga fichero.
• pi-cache-optimizer-stats.json (en ~/.pi/agent/) es estado de runtime — no se versiona.

Verificación

Después de instalar:

1. pi-yolo
2. Deberías ver la cabecera con [Agents] y [Commands]
3. Prueba delegación end-to-end: /subagent scout 'enumera los ficheros de este repo'

Mantenimiento

• Para actualizar paquetes: cd ~/.pi/agent/npm && npm update (luego ./install.sh para restaurar config + patch de pi-herdr-subagents)
• Para añadir un agente: crea agents/nuevo.md con frontmatter name, description, thinking
• Para añadir una extensión: copia el .ts a extensions/ y reinicia pi

Minions en Herdr

Cada PI padre abre un tab minions · <HERDR_PANE_ID> y mete ahí a todos sus subagentes en splits (no un tab por minion).

• Zoom / focus en grande del pane activo: Ctrl+b z (prefix+z; otra vez para salir)
• CLI: herdr pane zoom / herdr pane zoom --on / herdr pane zoom --off
• Mover foco entre panes: prefix+h/j/k/l