pi-agent-switcher/README.md

Agent Switcher

Cambio de agentes estilo opencode para pi: alterna entre agentes (p. ej. planner y build) y cada agente aplica su propio modelo, nivel de thinking, allowlist de herramientas, rol de solo lectura y system prompt.

Instalación

• Instalación permanente: pi install https://git.sargatxet.cloud/sargatxet/pi-agent-switcher
• Una sola sesión: pi -e https://git.sargatxet.cloud/sargatxet/pi-agent-switcher
• Manual (fallback): git clone https://git.sargatxet.cloud/sargatxet/pi-agent-switcher.git ~/.pi/agent/extensions/agent-switcher o probar sin instalar: pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts

Comandos

Comando / atajo	Acción
/agent	Selector de agentes (lista si no hay TUI)
/agent <nombre>	Cambiar al agente <nombre> (también alias)
/agents	Listar agentes con su estado y modelo
/agent model	Modelo efectivo del agente activo
/agent model <ref>	Fijar el modelo del agente activo para esta sesión
/agent model reset	Quitar el override y volver al model: del archivo
F5 / F6	Cambiar al agente planner/build (configurable con shortcut:)
pi --agent planner	Arrancar con un agente concreto

El agente activo se confirma con el aviso Agente activo: … · modelo … al cambiar, y con /agent list. La línea de estado del footer se eliminó por resultar confusa.

Definir agentes

Cada agente es un Markdown con frontmatter en:

• ~/.pi/agent/agents/*.md — agentes de usuario
• <proyecto>/.pi/agents/*.md — agentes de proyecto (sobrescriben al mismo nombre)

Ejemplo (~/.pi/agent/agents/build.md):

---
name: build
description: Implementation agent running on the fast model
aliases: constructor, implement
advertise: true
model: provider/model-id
thinking: medium
systemPromptMode: append
inheritProjectContext: true
inheritSkills: true
---

You are `build`: the implementation agent. ...

Claves del frontmatter

Clave	Defecto	Significado
name	nombre del archivo	Identificador único para /agent <nombre>
description	—	Texto mostrado en el selector
aliases	—	Nombres alternativos, separados por comas
advertise	true	false = oculto en el selector y en el ciclo
shortcut	—	Atajos directos al agente, separados por comas (p. ej. f5). Conflicto con atajos nativos: pi lo descarta con aviso
model	—	provider/id o un id único. Sin valor = conserva el modelo actual
thinking	—	off|minimal|low|medium|high|xhigh|max
systemPromptMode	append	replace = el cuerpo sustituye el prefijo del prompt; append = se añade
inheritProjectContext	true	false = el agente no ve AGENTS.md/archivos de contexto
inheritSkills	true	false = el agente no ve las skills
tools	—	Allowlist de herramientas activas (separadas por comas o espacios)
acceptanceRole	—	read-only = bloquea edit/write y restringe bash a comandos de solo lectura
defaultContext	—	Aceptado e ignorado (fresco no aplica al cambio inline)

El cuerpo del archivo (tras el frontmatter) es el system prompt del agente.

Semántica (equivalente a opencode)

• El agente activo gobierna: su model y thinking se aplican al activarse y se reafirman en cada before_agent_start; su tools y su prompt también se aplican cada run (todo idempotente).
• Agente sin model = no toca el modelo: conserva el de la sesión (útil para un build que simplemente hereda el modelo por defecto de pi).
• Overrides de sesión: solo /agent model <ref> crea un override para el agente activo y se restaura al volver a él. Los cambios con /model o Ctrl+P aplican de inmediato, pero el modelo del agente se reafirma en cada prompt (los eventos de modelo ya no se autograban: así los cambios de otras extensiones no pueden intercambiar los modelos de los agentes). El override lleva memoria del valor del archivo que tenía al crearse: si editas model: en el .md, el archivo manda y el override se descarta. /agent model reset lo borra a mano; /agent list marca los agentes con modelo «(sesión)». Para fijarlo de forma permanente, edita el model: del archivo del agente.
• Persistencia: el agente activo y los overrides se guardan en la sesión y se restauran al reanudarla.
• Solo lectura: además de desactivar las herramientas de escritura, hay una segunda barrera en tool_call que bloquea edit/write y cualquier comando bash que no esté en la lista de solo lectura (policy.ts).

Notas

• Los agentes se recargan en cada inicio de sesión; tras editar un .md durante la sesión usa /reload (también recarga los atajos nuevos).

Los atajos de teclado no funcionan

1. ¿La sesión cargó la extensión? Ejecuta /hotkeys: debe aparecer Cambiar al agente …. Si no aparece, ejecuta /reload (o reinicia pi): las sesiones abiertas antes de instalar el plugin no lo cargan solas.
2. ¿El terminal entrega la combinación? La configuración por defecto usa teclas de función (f5, f6) precisamente porque llegan en todos los terminales. Si cambias a combinaciones como ctrl+alt+x, estas solo llegan a pi si el terminal usa el protocolo kitty/CSI-u (kitty, Ghostty, WezTerm con enable_kitty_keyboard, VS Code ≥ 1.109.5) o si envía ESC + carácter de control; fallan en terminales clásicas, dentro de tmux y con teclado español donde AltGr = Ctrl+Alt.
3. En tmux, habilita set -s extended-keys on para que lleguen las teclas modificadas (ver la doc de pi sobre tmux).
4. Cambia las teclas editando shortcut: en el .md del agente y ejecutando /reload. Cualquier combinación que aparezca en /hotkeys es válida.

• Si otra extensión también llama a setModel en before_agent_start (p. ej. un cambio de modelo automático por fases), las dos competirán en cada run: mantén solo una estrategia activa.
• Con pi-subagents instalado, subagents_enable se fuerza siempre en las herramientas activas. En agentes con tools:/read-only esa llamada se bloquea en tool_call (delegar permitiría escribir ficheros); el resto de su comportamiento no se ve afectado.
• Para probar sin instalar nada: pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts.