Temas

pi pode criar temas. Peça para construir um para sua configuração.

Os temas são arquivos JSON que definem as cores do TUI.

• Locations
• Selecting a Theme
• Creating a Custom Theme
• Theme Format
• Color Tokens
• Color Values
• Tips

Pi carrega temas de:

• Integrado: dark, light
• Globais: ~/.pi/agent/themes/*.json
• Projeto: .pi/themes/*.json (somente depois que o projeto for confiável)
• Pacotes: diretórios themes/ ou entradas pi.themes em package.json
• Configurações: themes array com arquivos ou diretórios
• CLI: --theme <path> (repetível)

Desative a descoberta com --no-themes.

Selecione um tema via /settings ou em settings.json:

{
  "theme": "my-theme"
}

Na primeira execução, pi detecta o plano de fundo do seu terminal e o padrão é dark ou light.

1. Crie um arquivo de tema:

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

2. Defina o tema com todas as cores necessárias (veja Color Tokens):

{
  "$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",
    "scrollbarThumb": "#555566",
    "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",
    "thinkingMax": "#ff0088",
    "bashMode": "#ffaa00"
  }
}

3. Selecione o tema via /settings.

Recarregamento a quente: Quando você edita o arquivo de tema personalizado atualmente ativo, o pi o recarrega automaticamente para feedback visual imediato.

{
  "$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 é obrigatório, deve ser exclusivo e não deve conter /.
• vars é opcional. Defina cores reutilizáveis ​​aqui e referencie-as em colors.
• colors deve definir todos os 51 tokens necessários. thinkingMax é opcional e volta para thinkingXhigh; scrollbarThumb é opcional e volta para selectedBg.

O campo $schema permite o preenchimento automático e a validação do editor.

Cada tema deve definir todos os 51 tokens de cores necessários. thinkingMax e scrollbarThumb são opcionais para compatibilidade com temas existentes; quando omitidos, eles usam thinkingXhigh e selectedBg, respectivamente.

Cores da borda do editor indicando o nível de pensamento (hierarquia visual de sutil a proeminente):

A seção export controla as cores da saída HTML /export. Se omitido, as cores serão derivadas de userMessageBg.

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

Quatro formatos são suportados:

• 0-15: Cores ANSI básicas (dependente do terminal)
• 16-231: cubo RGB 6×6×6 (16 + 36×R + 6×G + B onde R,G,B são 0-5)
• 232-255: Rampa em tons de cinza

Pi usa cores RGB de 24 bits. A maioria dos terminais modernos suporta isso (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). Para terminais mais antigos com suporte apenas para 256 cores, pi volta para a aproximação mais próxima.

Verifique o suporte truecolor:

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

Terminais escuros: Use cores brilhantes e saturadas com maior contraste.

Terminais claros: use cores mais escuras e suaves com menor contraste.

Harmonia de cores: Comece com uma paleta base (Nord, Gruvbox, Tokyo Night), defina-a em vars e faça referência de forma consistente.

Testes: Verifique seu tema com diferentes tipos de mensagens, estados de ferramentas, conteúdo de marcação e texto longo.

Código VS: Defina terminal.integrated.minimumContrastRatio como 1 para cores precisas.

Veja os temas integrados:

• dark.json
• light.json