Personalización de temas de Pi Agent
Pi Agent admite la personalización de los colores de la interfaz de terminal.
Este capítulo explica cómo usar los temas integrados y crear temas personalizados.
Descripción general de temas
Pi Agent utiliza archivos de tema en formato JSON para definir todos los colores de la interfaz TUI.
Cada tema debe definir51 tokens obligatorios + 4 tokens opcionales (thinkingMax, scrollbarThumb, searchMatchBg, searchMatchText)que cubren los colores de diversos elementos de la interfaz, como la UI principal, el fondo de los mensajes, el renderizado de Markdown, el resaltado de sintaxis y los bordes del editor.
Temas integrados
Pi Agent incluye dos temas integrados:
| Nombre del tema | Escenario de uso | Descripción |
|---|---|---|
| dark | Fondo de terminal oscuro (predeterminado) | Adecuado para terminales oscuros de la mayoría de los desarrolladores |
| light | Fondo de terminal claro | Adecuado para terminales con tema claro |
Al iniciar por primera vez, Pi Agent detecta automáticamente el color de fondo de tu terminal y selecciona dark o light.
En el modo interactivo, escribe /settings y cambia directamente en las opciones de tema:
/settings
También puedes escribir el campo theme en settings.json y cambiar el valor de theme al nombre del tema:
Ejemplo
"theme": "light"
}
Crear un tema personalizado
Primero, crea el directorio y el archivo del tema:
mkdir -p ~/.pi/agent/themes vim ~/.pi/agent/themes/my-theme.json
Luego define el archivo de tema. A continuación se muestra un ejemplo completo de tema personalizado:
Ejemplo
"name": "my-theme",
"vars": {
"blue": "#0066cc",
"gray": 242,
"orange": "#ffaa00",
"green": "#0055AA"
},
"colors": {
"accent": "blue",
"border": "blue",
"borderAccent": "#00ffff",
"borderMuted": "gray",
"success": "green",
"error": "#ff0000",
"warning": "#ffff00",
"muted": "gray",
"dim": 240,
"text": "",
"thinkingText": "gray",
"selectedBg": "#2d2d30",
"userMessageBg": "#2d2d30",
"userMessageText": "",
"customMessageBg": "#2d2d30",
"customMessageText": "",
"customMessageLabel": "blue",
"toolPendingBg": "#1e1e2e",
"toolSuccessBg": "#1e2e1e",
"toolErrorBg": "#2e1e1e",
"toolTitle": "blue",
"toolOutput": "",
"mdHeading": "orange",
"mdLink": "blue",
"mdLinkUrl": "gray",
"mdCode": "#00ffff",
"mdCodeBlock": "",
"mdCodeBlockBorder": "gray",
"mdQuote": "gray",
"mdQuoteBorder": "gray",
"mdHr": "gray",
"mdListBullet": "#00ffff",
"toolDiffAdded": "green",
"toolDiffRemoved": "#ff0000",
"toolDiffContext": "gray",
"syntaxComment": "gray",
"syntaxKeyword": "blue",
"syntaxFunction": "#00aaff",
"syntaxVariable": "orange",
"syntaxString": "green",
"syntaxNumber": "#ff00ff",
"syntaxType": "#00aaff",
"syntaxOperator": "blue",
"syntaxPunctuation": "gray",
"thinkingOff": "gray",
"thinkingMinimal": "blue",
"thinkingLow": "#00aaff",
"thinkingMedium": "#00ffff",
"thinkingHigh": "#ff00ff",
"thinkingXhigh": "#ff0000",
"thinkingMax": "#ff0088",
"bashMode": "orange"
}
}
Luego habilita tu tema en settings.json:
Ejemplo
"theme": "my-theme"
}
Cuando editas el archivo de tema personalizado que estás usando actualmente, Pi Agent recarga el tema automáticamente, lo que te permite ver los cambios al instante, sin necesidad de hacer nada.
Ubicación de carga de archivos de tema
Pi Agent busca los archivos de tema en las siguientes ubicaciones.
Los temas ubicados en diferentes posiciones tienen distinto alcance de visibilidad y condiciones de carga.
| Ubicación | Alcance |
|---|---|
| Integrado | dark y light siempre disponibles |
| ~/.pi/agent/themes/*.json | Tema global, disponible para todos los proyectos |
| .pi/themes/*.json | Tema de proyecto, se carga solo después de confiar en el proyecto |
| Pi Packages | Directorio themes/ del paquete |
| Ruta --theme | Carga temporal desde la línea de comandos |
Formatos de valores de color
Pi Agent admite cuatro formatos de valores de color:
| Formato | Ejemplo | Descripción |
|---|---|---|
| Color Hex | "#ff0000" | Color RGB hexadecimal de 6 dígitos |
| Paleta de 256 colores | 39 | Índice de la paleta de 256 colores de xterm (0-255) |
| Referencia a variable | "blue" | Hace referencia a variables definidas en vars |
| Color predeterminado del terminal | "" | Usa el color de primer plano/fondo predeterminado del terminal |
La sección vars se usa para definir variables de color reutilizables, que se referencian por nombre en colors.
Al extraer el color principal como variable, cambiar la combinación de colores solo requiere modificar un lugar, lo que facilita el mantenimiento del tema.
Clasificación de tokens de color
Cada token en colors corresponde al color de un tipo de elemento de la interfaz.
A continuación, todos los tokens se dividen en seis categorías según su uso, para facilitar la consulta.
UI principal (11)
Este grupo controla los colores de los elementos básicos de la interfaz, como el editor y la barra de estado.
| Token | Uso |
|---|---|
| accent | Color principal (Logo, elemento seleccionado, cursor) |
| border | Borde normal |
| borderAccent | Borde resaltado |
| borderMuted | Borde suave del área del editor |
| success | Estado de éxito |
| error | Estado de error |
| warning | Estado de advertencia |
| muted | Texto secundario |
| dim | Texto terciario (menos visible) |
| text | Color de texto predeterminado (normalmente se deja vacío) |
| thinkingText | Texto del proceso de razonamiento de la IA |
Fondo y contenido (11 obligatorios + 3 opcionales)
Este grupo controla el fondo y el texto de los elementos seleccionados, las burbujas de mensaje y el área de salida de herramientas.
| Token | Uso |
|---|---|
| selectedBg | Fondo del elemento seleccionado (entrada actual en la lista) |
| userMessageBg | Fondo del mensaje del usuario |
| userMessageText | Texto del mensaje del usuario |
| customMessageBg | Fondo del mensaje expandido |
| customMessageText | Texto del mensaje expandido |
| customMessageLabel | Color de la etiqueta de título del mensaje expandido |
| toolPendingBg | Fondo durante la ejecución de la herramienta |
| toolSuccessBg | Fondo cuando la ejecución de la herramienta es exitosa |
| toolErrorBg | Fondo cuando la ejecución de la herramienta falla |
| toolTitle | Texto del título de la tarjeta de herramienta |
| toolOutput | Texto de salida de la herramienta |
| scrollbarThumb | Color del pulgar de la barra de desplazamiento de pantalla completa (opcional, usa selectedBg como respaldo si no se define) |
| searchMatchBg | Fondo de coincidencia de búsqueda (opcional, usa selectedBg como respaldo si no se define) |
| searchMatchText | Texto de coincidencia de búsqueda (opcional, usa text como respaldo si no se define) |
Renderizado de Markdown (10)
Este grupo controla los colores de los elementos Markdown en las respuestas de la IA.
| Token | Uso |
|---|---|
| mdHeading | Título |
| mdLink | Texto del enlace |
| mdLinkUrl | Dirección URL del enlace |
| mdCode | Código en línea |
| mdCodeBlock | Contenido del bloque de código |
| mdCodeBlockBorder | Borde del bloque de código |
| mdQuote | Texto del bloque de cita |
| mdQuoteBorder | Borde del bloque de cita |
| mdHr | Línea divisoria |
| mdListBullet | Símbolo de lista |
Resaltado de sintaxis (9)
Este grupo controla los colores del resaltado de sintaxis dentro de los bloques de código.
| Token | Uso |
|---|---|
| syntaxComment | Comentario |
| syntaxKeyword | Palabra clave |
| syntaxFunction | Nombre de función |
| syntaxVariable | Nombre de variable |
| syntaxString | Cadena |
| syntaxNumber | Número |
| syntaxType | Tipo |
| syntaxOperator | Operador |
| syntaxPunctuation | Signo de puntuación |
Bordes de nivel de razonamiento (7)
Este grupo controla el color de indicación del nivel de razonamiento actual en el borde del editor.
| Token | Nivel correspondiente |
|---|---|
| thinkingOff | Razonamiento desactivado |
| thinkingMinimal | Razonamiento mínimo |
| thinkingLow | Razonamiento bajo |
| thinkingMedium | Razonamiento medio |
| thinkingHigh | Razonamiento alto |
| thinkingXhigh | Razonamiento muy alto |
| thinkingMax | Razonamiento máximo (opcional) |
thinkingMax es un token opcional; si no se define, se usa el color de thinkingXhigh como respaldo.
Colores para Diff y Bash (4)
Este grupo controla el resaltado de diff y el color de indicación del modo bash; son los que se ven con más frecuencia al editar código.
| Token | Uso |
|---|---|
| toolDiffAdded | Línea añadida en diff (normalmente en verde) |
| toolDiffRemoved | Línea eliminada en diff (normalmente en rojo) |
| toolDiffContext | Línea de contexto en diff (mantener discreta) |
| bashMode | Color de indicación en modo bash |
Colores para exportación HTML
Si usas /export para exportar la sesión a HTML, puedes definir los colores de la página exportada en el tema:
Ejemplo
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}
Si se omite la configuración de export, la página exportada deduce automáticamente los colores a partir de userMessageBg.
Consejos para crear temas
Los siguientes consejos prácticos ayudan a que los temas personalizados se vean estables en diferentes terminales.
- Terminal oscuro: usa colores brillantes y saturados, con contraste suficientemente alto
- Terminal claro: usa colores más oscuros y suaves; el contraste puede reducirse adecuadamente
- Armonía de color: usa como base esquemas de color consolidados como Nord, Gruvbox, Tokyo Night
- Pruebas exhaustivas: Garantizar que se muestre correctamente en diferentes tipos de mensajes, estados de herramientas, contenido Markdown y ajuste de línea en textos largos.