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 temaEscenario de usoDescripción
darkFondo de terminal oscuro (predeterminado)Adecuado para terminales oscuros de la mayoría de los desarrolladores
lightFondo de terminal claroAdecuado 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ónAlcance
Integradodark y light siempre disponibles
~/.pi/agent/themes/*.jsonTema global, disponible para todos los proyectos
.pi/themes/*.jsonTema de proyecto, se carga solo después de confiar en el proyecto
Pi PackagesDirectorio themes/ del paquete
Ruta --themeCarga temporal desde la línea de comandos

Formatos de valores de color

Pi Agent admite cuatro formatos de valores de color:

FormatoEjemploDescripción
Color Hex"#ff0000"Color RGB hexadecimal de 6 dígitos
Paleta de 256 colores39Í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.

TokenUso
accentColor principal (Logo, elemento seleccionado, cursor)
borderBorde normal
borderAccentBorde resaltado
borderMutedBorde suave del área del editor
successEstado de éxito
errorEstado de error
warningEstado de advertencia
mutedTexto secundario
dimTexto terciario (menos visible)
textColor de texto predeterminado (normalmente se deja vacío)
thinkingTextTexto 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.

TokenUso
selectedBgFondo del elemento seleccionado (entrada actual en la lista)
userMessageBgFondo del mensaje del usuario
userMessageTextTexto del mensaje del usuario
customMessageBgFondo del mensaje expandido
customMessageTextTexto del mensaje expandido
customMessageLabelColor de la etiqueta de título del mensaje expandido
toolPendingBgFondo durante la ejecución de la herramienta
toolSuccessBgFondo cuando la ejecución de la herramienta es exitosa
toolErrorBgFondo cuando la ejecución de la herramienta falla
toolTitleTexto del título de la tarjeta de herramienta
toolOutputTexto de salida de la herramienta
scrollbarThumbColor del pulgar de la barra de desplazamiento de pantalla completa (opcional, usa selectedBg como respaldo si no se define)
searchMatchBgFondo de coincidencia de búsqueda (opcional, usa selectedBg como respaldo si no se define)
searchMatchTextTexto 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.

TokenUso
mdHeadingTítulo
mdLinkTexto del enlace
mdLinkUrlDirección URL del enlace
mdCodeCódigo en línea
mdCodeBlockContenido del bloque de código
mdCodeBlockBorderBorde del bloque de código
mdQuoteTexto del bloque de cita
mdQuoteBorderBorde del bloque de cita
mdHrLínea divisoria
mdListBulletSímbolo de lista

Resaltado de sintaxis (9)

Este grupo controla los colores del resaltado de sintaxis dentro de los bloques de código.

TokenUso
syntaxCommentComentario
syntaxKeywordPalabra clave
syntaxFunctionNombre de función
syntaxVariableNombre de variable
syntaxStringCadena
syntaxNumberNúmero
syntaxTypeTipo
syntaxOperatorOperador
syntaxPunctuationSigno 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.

TokenNivel correspondiente
thinkingOffRazonamiento desactivado
thinkingMinimalRazonamiento mínimo
thinkingLowRazonamiento bajo
thinkingMediumRazonamiento medio
thinkingHighRazonamiento alto
thinkingXhighRazonamiento muy alto
thinkingMaxRazonamiento 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.

TokenUso
toolDiffAddedLínea añadida en diff (normalmente en verde)
toolDiffRemovedLínea eliminada en diff (normalmente en rojo)
toolDiffContextLínea de contexto en diff (mantener discreta)
bashModeColor 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.
Otras extensiones