Temas

pi puede crear temas. Pídele que cree uno para tu configuración.

Temas

Los temas son archivos JSON que definen colores para la TUI.

Tabla de contenidos

• Ubicaciones
• Seleccionar un tema
• Crear un tema personalizado
• Formato del tema
• Tokens de color
• Valores de color
• Consejos

Ubicaciones

Pi carga temas desde:

• Integrados: dark, light
• Global: ~/.pi/agent/themes/*.json
• Proyecto: .pi/themes/*.json (solo después de que el proyecto sea de confianza)
• Paquetes: directorios themes/ o entradas pi.themes en package.json
• Configuración: array themes con archivos o directorios
• CLI: --theme <path> (repetible)

Desactiva el descubrimiento con --no-themes.

Seleccionar un tema

Selecciona un tema mediante /settings o en settings.json:

{
  "theme": "my-theme"
}

En la primera ejecución, pi detecta el fondo de tu terminal y usa dark o light por defecto.

Crear un tema personalizado

1. Crea un archivo de tema:

mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json

2. Define el tema con todos los colores requeridos (consulta Tokens de color):

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "primary": "#00aaff",
    "secondary": 242
  },
  "colors": {
    "accent": "primary",
    "border": "primary",
    "borderAccent": "#00ffff",
    "borderMuted": "secondary",
    "success": "#00ff00",
    "error": "#ff0000",
    "warning": "#ffff00",
    "muted": "secondary",
    "dim": 240,
    "text": "",
    "thinkingText": "secondary",
    "selectedBg": "#2d2d30",
    "userMessageBg": "#2d2d30",
    "userMessageText": "",
    "customMessageBg": "#2d2d30",
    "customMessageText": "",
    "customMessageLabel": "primary",
    "toolPendingBg": "#1e1e2e",
    "toolSuccessBg": "#1e2e1e",
    "toolErrorBg": "#2e1e1e",
    "toolTitle": "primary",
    "toolOutput": "",
    "mdHeading": "#ffaa00",
    "mdLink": "primary",
    "mdLinkUrl": "secondary",
    "mdCode": "#00ffff",
    "mdCodeBlock": "",
    "mdCodeBlockBorder": "secondary",
    "mdQuote": "secondary",
    "mdQuoteBorder": "secondary",
    "mdHr": "secondary",
    "mdListBullet": "#00ffff",
    "toolDiffAdded": "#00ff00",
    "toolDiffRemoved": "#ff0000",
    "toolDiffContext": "secondary",
    "syntaxComment": "secondary",
    "syntaxKeyword": "primary",
    "syntaxFunction": "#00aaff",
    "syntaxVariable": "#ffaa00",
    "syntaxString": "#00ff00",
    "syntaxNumber": "#ff00ff",
    "syntaxType": "#00aaff",
    "syntaxOperator": "primary",
    "syntaxPunctuation": "secondary",
    "thinkingOff": "secondary",
    "thinkingMinimal": "primary",
    "thinkingLow": "#00aaff",
    "thinkingMedium": "#00ffff",
    "thinkingHigh": "#ff00ff",
    "thinkingXhigh": "#ff0000",
    "bashMode": "#ffaa00"
  }
}

3. Selecciona el tema mediante /settings.

Recarga en caliente: Cuando editas el archivo de tema personalizado actualmente activo, pi lo recarga automáticamente para obtener retroalimentación visual inmediata.

Formato del tema

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "text": "",
    ...
  }
}

• name es obligatorio, debe ser único y no puede contener /.
• vars es opcional. Define colores reutilizables aquí y luego refiérelos en colors.
• colors debe definir los 51 tokens requeridos.

El campo $schema habilita la autocompletación y validación del editor.

Tokens de color

Cada tema debe definir los 51 tokens de color. No hay colores opcionales.

UI principal (11 colores)

Token	Propósito
accent	Acento principal (logo, elementos seleccionados, cursor)
border	Bordes normales
borderAccent	Bordes resaltados
borderMuted	Bordes sutiles (editor)
success	Estados de éxito
error	Estados de error
warning	Estados de advertencia
muted	Texto secundario
dim	Texto terciario
text	Texto predeterminado (normalmente "")
thinkingText	Texto del bloque de pensamiento

Fondos y contenido (11 colores)

Token	Propósito
selectedBg	Fondo de línea seleccionada
userMessageBg	Fondo del mensaje del usuario
userMessageText	Texto del mensaje del usuario
customMessageBg	Fondo del mensaje de extensión
customMessageText	Texto del mensaje de extensión
customMessageLabel	Etiqueta del mensaje de extensión
toolPendingBg	Caja de herramienta (pendiente)
toolSuccessBg	Caja de herramienta (éxito)
toolErrorBg	Caja de herramienta (error)
toolTitle	Título de herramienta
toolOutput	Texto de salida de herramienta

Markdown (10 colores)

Token	Propósito
mdHeading	Encabezados
mdLink	Texto del enlace
mdLinkUrl	URL del enlace
mdCode	Código en línea
mdCodeBlock	Contenido del bloque de código
mdCodeBlockBorder	Delimitadores del bloque de código
mdQuote	Texto de cita
mdQuoteBorder	Borde de cita
mdHr	Regla horizontal
mdListBullet	Viñetas de lista

Diff de herramientas (3 colores)

Token	Propósito
toolDiffAdded	Líneas añadidas
toolDiffRemoved	Líneas eliminadas
toolDiffContext	Líneas de contexto

Resaltado de sintaxis (9 colores)

Token	Propósito
syntaxComment	Comentarios
syntaxKeyword	Palabras clave
syntaxFunction	Nombres de funciones
syntaxVariable	Variables
syntaxString	Cadenas
syntaxNumber	Números
syntaxType	Tipos
syntaxOperator	Operadores
syntaxPunctuation	Puntuación

Bordes de nivel de pensamiento (6 colores)

Colores de borde del editor que indican el nivel de pensamiento (jerarquía visual de sutil a prominente):

Token	Propósito
thinkingOff	Pensamiento desactivado
thinkingMinimal	Pensamiento mínimo
thinkingLow	Pensamiento bajo
thinkingMedium	Pensamiento medio
thinkingHigh	Pensamiento alto
thinkingXhigh	Pensamiento extra alto

Modo Bash (1 color)

Token	Propósito
bashMode	Borde del editor en modo bash (prefijo !)

Exportación HTML (opcional)

La sección export controla los colores para la salida HTML de /export. Si se omite, los colores se derivan de userMessageBg.

{
  "export": {
    "pageBg": "#18181e",
    "cardBg": "#1e1e24",
    "infoBg": "#3c3728"
  }
}

Valores de color

Se admiten cuatro formatos:

Formato	Ejemplo	Descripción
Hex	"#ff0000"	RGB hex de 6 dígitos
256 colores	39	Índice de paleta xterm de 256 colores (0-255)
Variable	"primary"	Referencia a una entrada de vars
Predeterminado	""	Color predeterminado del terminal

Paleta de 256 colores

• 0-15: Colores ANSI básicos (dependen del terminal)
• 16-231: Cubo RGB 6×6×6 (16 + 36×R + 6×G + B donde R, G, B son 0-5)
• 232-255: Escala de grises

Compatibilidad con terminales

Pi usa colores RGB de 24 bits. La mayoría de terminales modernos lo soportan (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). Para terminales antiguos con soporte solo de 256 colores, pi recurre a la aproximación más cercana.

Comprueba el soporte de truecolor:

echo $COLORTERM  # Should output "truecolor" or "24bit"

Consejos

Terminales oscuros: Usa colores brillantes y saturados con mayor contraste.

Terminales claros: Usa colores más oscuros y apagados con menor contraste.

Armonía de color: Comienza con una paleta base (Nord, Gruvbox, Tokyo Night), defínela en vars y refiérela de forma consistente.

Pruebas: Comprueba tu tema con diferentes tipos de mensajes, estados de herramientas, contenido markdown y texto largo con ajuste de línea.

VS Code: Establece terminal.integrated.minimumContrastRatio en 1 para colores precisos.

Ejemplos

Consulta los temas integrados:

• dark.json
• light.json