Configuración

Pi usa archivos de configuración JSON; la configuración del proyecto anula la configuración global.

Ubicación	Alcance
~/.pi/agent/settings.json	Global (todos los proyectos)
.pi/settings.json	Proyecto (directorio actual)

Edítalos directamente o usa /settings para opciones comunes.

Confianza del proyecto

Al iniciar en modo interactivo, pi pregunta antes de confiar en una carpeta de proyecto que contiene configuración local, recursos o .agents/skills del proyecto, y no tiene una decisión guardada para la carpeta o una carpeta padre en ~/.pi/agent/trust.json. Confiar en un proyecto permite a pi cargar .pi/settings.json y recursos de .pi, instalar paquetes del proyecto faltantes y ejecutar extensiones del proyecto.

Los modos no interactivos (-p, --mode json y --mode rpc) no muestran un aviso de confianza. Sin una decisión de confianza guardada aplicable, usan defaultProjectTrust de la configuración global: ask (predeterminado) y never ignoran esos recursos del proyecto, mientras always los confía. Pasa --approve/-a o --no-approve/-na para anular la confianza del proyecto en una ejecución.

Si no aplica ninguna extensión o decisión guardada, defaultProjectTrust controla el comportamiento de respaldo. Establécelo en "ask", "always" o "never" en ~/.pi/agent/settings.json, o cámbialo con /settings.

pi config y los comandos de paquetes usan el mismo flujo de confianza del proyecto, excepto pi update, que nunca pregunta. Pasa --approve para confiar en la configuración local del proyecto en un comando o --no-approve para ignorarla.

Usa /trust en modo interactivo para guardar una decisión de confianza del proyecto para sesiones futuras, incluida la confianza en la carpeta padre inmediata. Solo escribe en ~/.pi/agent/trust.json; la sesión actual no se recarga, así que reinicia pi para que los cambios surtan efecto.

Todas las configuraciones

Modelo y pensamiento

Configuración	Tipo	Predeterminado	Descripción
defaultProvider	string	-	Proveedor predeterminado (p. ej., "anthropic", "openai")
defaultModel	string	-	ID del modelo predeterminado
defaultThinkingLevel	string	-	"off", "minimal", "low", "medium", "high", "xhigh"
hideThinkingBlock	boolean	false	Ocultar bloques de pensamiento en la salida
thinkingBudgets	object	-	Presupuestos de tokens personalizados por nivel de pensamiento

thinkingBudgets

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

Interfaz y visualización

Configuración	Tipo	Predeterminado	Descripción
theme	string	"dark"	Nombre del tema ("dark", "light" o personalizado)
quietStartup	boolean	false	Ocultar el encabezado de inicio
defaultProjectTrust	string	"ask"	Comportamiento de confianza del proyecto de respaldo: "ask", "always" o "never". Solo configuración global
collapseChangelog	boolean	false	Mostrar changelog condensado tras actualizaciones
enableInstallTelemetry	boolean	true	Enviar un ping anónimo de versión de instalación/actualización tras la primera instalación o actualizaciones detectadas por changelog. No controla las comprobaciones de actualización
enableAnalytics	boolean	false	Habilitación voluntaria del análisis de datos. Actualmente solo se pregunta durante la configuración experimental inicial (PI_EXPERIMENTAL=1)
trackingId	string	-	Identificador de seguimiento analítico, generado cuando se activa enableAnalytics
doubleEscapeAction	string	"tree"	Acción para doble escape: "tree", "fork" o "none"
treeFilterMode	string	"default"	Filtro predeterminado para /tree: "default", "no-tools", "user-only", "labeled-only", "all"
editorPaddingX	number	0	Relleno horizontal del editor de entrada (0-3)
autocompleteMaxVisible	number	5	Máximo de elementos visibles en el desplegable de autocompletado (3-20)
showHardwareCursor	boolean	false	Mostrar el cursor del terminal mientras la TUI lo posiciona para soporte IME

Telemetría y comprobaciones de actualización

enableInstallTelemetry solo controla el ping anónimo de instalación/actualización a https://pi.dev/api/report-install. Optar por no participar en telemetría no desactiva las comprobaciones de actualización; Pi aún puede obtener https://pi.dev/api/latest-version para buscar la última versión.

Establece PI_SKIP_VERSION_CHECK=1 para desactivar la comprobación de actualización de versión de Pi. Usa --offline o PI_OFFLINE=1 para desactivar todas las operaciones de red al inicio descritas aquí, incluidas comprobaciones de actualización, comprobaciones de actualización de paquetes y telemetría de instalación/actualización.

Red

Configuración	Tipo	Predeterminado	Descripción
httpProxy	string	-	URL del proxy HTTP aplicada como HTTP_PROXY y HTTPS_PROXY. Solo configuración global.

{
  "httpProxy": "http://127.0.0.1:7890"
}

Advertencias

Configuración	Tipo	Predeterminado	Descripción
warnings.anthropicExtraUsage	boolean	true	Mostrar advertencia cuando la autenticación de suscripción Anthropic puede usar uso extra de pago

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

Compaction

Configuración	Tipo	Predeterminado	Descripción
compaction.enabled	boolean	true	Habilitar auto-compaction
compaction.reserveTokens	number	16384	Tokens reservados para la respuesta del LLM
compaction.keepRecentTokens	number	20000	Tokens recientes a conservar (sin resumir)

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Resumen de ramas

Configuración	Tipo	Predeterminado	Descripción
branchSummary.reserveTokens	number	16384	Tokens reservados para resumir ramas
branchSummary.skipPrompt	boolean	false	Omitir el aviso «Summarize branch?» en la navegación de /tree (predeterminado: sin resumen)

Reintentos

Configuración	Tipo	Predeterminado	Descripción
retry.enabled	boolean	true	Habilitar reintento automático a nivel de agente en errores transitorios
retry.maxRetries	number	3	Máximo de reintentos a nivel de agente
retry.baseDelayMs	number	2000	Retraso base para backoff exponencial a nivel de agente (2s, 4s, 8s)
retry.provider.timeoutMs	number	SDK default	Tiempo de espera de solicitud del proveedor/SDK en milisegundos
retry.provider.maxRetries	number	0	Intentos de reintento del proveedor/SDK
retry.provider.maxRetryDelayMs	number	60000	Retraso máximo solicitado por el servidor antes de fallar (60s)

Cuando un proveedor solicita un retraso de reintento mayor que retry.provider.maxRetryDelayMs (p. ej., «quota will reset after 5h» de Google), la solicitud falla inmediatamente con un error informativo en lugar de esperar en silencio. Establécelo en 0 para desactivar el límite.

Mantén retry.provider.maxRetries en 0 a menos que se necesiten reintentos a nivel de proveedor explícitamente. Establecerlo por encima de 0 puede hacer que los reintentos del SDK/proveedor gestionen errores de límite de uso antes de que Pi los vea, lo que puede bloquear el agente hasta que se restablezca la cuota del proveedor en algunas circunstancias.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

Entrega de mensajes

Configuración	Tipo	Predeterminado	Descripción
steeringMode	string	"one-at-a-time"	Cómo se envían los mensajes de steering: "all" o "one-at-a-time"
followUpMode	string	"one-at-a-time"	Cómo se envían los mensajes de seguimiento: "all" o "one-at-a-time"
transport	string	"auto"	Transporte preferido para proveedores que admiten varios transportes: "sse", "websocket", "websocket-cached" o "auto"
httpIdleTimeoutMs	number	300000	Tiempo de espera inactivo de cabecera/cuerpo HTTP en milisegundos, también usado por proveedores con tiempos de espera inactivos de stream explícitos. Establécelo en 0 para desactivar.
websocketConnectTimeoutMs	number	15000	Tiempo de espera de conexión/apertura del handshake WebSocket en milisegundos para proveedores que admiten transportes WebSocket. Establécelo en 0 para desactivar.

Terminal e imágenes

Configuración	Tipo	Predeterminado	Descripción
terminal.showImages	boolean	true	Mostrar imágenes en el terminal (si está soportado)
terminal.imageWidthCells	number	60	Ancho preferido de imagen en línea en celdas del terminal
terminal.clearOnShrink	boolean	false	Borrar filas vacías cuando el contenido se reduce (puede causar parpadeo)
images.autoResize	boolean	true	Redimensionar imágenes a un máximo de 2000x2000
images.blockImages	boolean	false	Bloquear que todas las imágenes se envíen al LLM

Shell

Configuración	Tipo	Predeterminado	Descripción
shellPath	string	-	Ruta shell personalizada (p. ej., para Cygwin en Windows)
shellCommandPrefix	string	-	Prefijo para cada comando bash (p. ej., "shopt -s expand_aliases")
npmCommand	string[]	-	argv del comando usado para operaciones de búsqueda/instalación de paquetes npm (p. ej., ["mise", "exec", "node@20", "--", "npm"])

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand se usa para todas las operaciones del gestor de paquetes npm, incluidas instalaciones, desinstalaciones e instalaciones de dependencias dentro de paquetes git. Los paquetes npm de ámbito de usuario se instalan en ~/.pi/agent/npm/; los de ámbito de proyecto en .pi/npm/. Usa entradas estilo argv exactamente como debe lanzarse el proceso. Cuando npmCommand está configurado, las instalaciones de dependencias de paquetes git usan plain install para evitar flags específicos de npm en wrappers o gestores alternativos.

Sesiones

Configuración	Tipo	Predeterminado	Descripción
sessionDir	string	-	Directorio donde se almacenan los archivos de sesión. Acepta rutas absolutas o relativas, además de ~.

{ "sessionDir": ".pi/sessions" }

Cuando varias fuentes especifican un directorio de sesión, la precedencia es --session-dir, PI_CODING_AGENT_SESSION_DIR, luego sessionDir en settings.json.

Ciclo de modelos

Configuración	Tipo	Predeterminado	Descripción
enabledModels	string[]	-	Patrones de modelo para ciclar con Ctrl+P (mismo formato que el flag CLI --models)

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

Configuración	Tipo	Predeterminado	Descripción
markdown.codeBlockIndent	string	" "	Sangría para bloques de código

Recursos

Estas configuraciones definen desde dónde cargar extensiones, habilidades, prompts y temas.

Las rutas en ~/.pi/agent/settings.json se resuelven relativas a ~/.pi/agent. Las rutas en .pi/settings.json se resuelven relativas a .pi. Se admiten rutas absolutas y ~.

Configuración	Tipo	Predeterminado	Descripción
packages	array	[]	Paquetes npm/git desde los que cargar recursos
extensions	string[]	[]	Rutas de archivos o directorios de extensiones locales
skills	string[]	[]	Rutas de archivos o directorios de habilidades locales
prompts	string[]	[]	Rutas de plantillas de prompts locales o directorios
themes	string[]	[]	Rutas de archivos o directorios de temas locales
enableSkillCommands	boolean	true	Registrar habilidades como comandos /skill:name

Los arrays admiten patrones glob y exclusiones. Usa !pattern para excluir. Usa +path para forzar la inclusión de una ruta exacta y -path para forzar la exclusión de una ruta exacta.

packages

La forma de cadena carga todos los recursos de un paquete:

{
  "packages": ["pi-skills", "@org/my-extension"]
}

La forma de objeto filtra qué recursos cargar:

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

Consulta packages.md para detalles de gestión de paquetes.

Ejemplo

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

Anulaciones del proyecto

La configuración del proyecto (.pi/settings.json) anula la configuración global. Los objetos anidados se fusionan:

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}