Themen

pi kann Themen erstellen. Bitten Sie es, eines für Ihr Setup zu erstellen.

Themen sind JSON Dateien, die Farben für TUI definieren.

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

Pi lädt Themen von:

• Eingebaut: dark, light
• Global: ~/.pi/agent/themes/*.json
• Projekt: .pi/themes/*.json (nur nachdem das Projekt vertrauenswürdig ist)
• Pakete: themes/ Verzeichnisse oder pi.themes Einträge in package.json
• Einstellungen: themes Array mit Dateien oder Verzeichnissen
• CLI: --theme <path> (wiederholbar)

Deaktivieren Sie die Erkennung mit --no-themes.

Wählen Sie ein Thema über /settings oder in settings.json:

{
  "theme": "my-theme"
}

Beim ersten Start erkennt pi den Hintergrund Ihres Terminals und stellt standardmäßig dark oder light ein.

1. Erstellen Sie eine Theme-Datei:

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

2. Definieren Sie das Theme mit allen benötigten Farben (siehe 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",
    "searchMatchBg": "#2d2d30",
    "searchMatchText": "",
    "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. Wählen Sie das Thema über /settings aus.

Hot Reload: Wenn Sie die aktuell aktive benutzerdefinierte Designdatei bearbeiten, lädt Pi sie automatisch neu, um sofortiges visuelles Feedback zu erhalten.

{
  "$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 ist erforderlich, muss eindeutig sein und darf / nicht enthalten.
• vars ist optional. Definieren Sie hier wiederverwendbare Farben und referenzieren Sie sie dann in colors.
• colors muss alle 51 erforderlichen Token definieren. thinkingMax, scrollbarThumb und die beiden Token für die Suchhervorhebung sind optional und verwenden die unten aufgeführten Fallbacks.

Das Feld $schema ermöglicht die automatische Vervollständigung und Validierung des Editors.

Jedes Thema muss alle 51 erforderlichen Farbtoken definieren. Die optionalen Token erhalten die Kompatibilität mit bestehenden Themes: thinkingMax greift auf thinkingXhigh zurück, scrollbarThumb und searchMatchBg auf selectedBg und searchMatchText auf text. Andere Suchtreffer verwenden searchMatchText auf searchMatchBg mit Unterstreichung; der aktuelle Treffer vertauscht dieses Vordergrund-/Hintergrundpaar und verwendet Fettdruck.

Die Rahmenfarben des Editors geben die Denkebene an (visuelle Hierarchie von subtil bis prominent):

Der Abschnitt export steuert die Farben für die /export HTML-Ausgabe. Wenn es weggelassen wird, werden die Farben von userMessageBg abgeleitet.

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

Vier Formate werden unterstützt:

• 0-15: Grundlegende ANSI-Farben (terminalabhängig)
• 16-231: 6×6×6 RGB-Würfel (16 + 36×R + 6×G + B wobei R,G,B 0-5 sind)
• 232-255: Graustufenrampe

Pi verwendet 24-Bit-RGB-Farben. Die meisten modernen Terminals unterstützen dies (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). Bei älteren Terminals mit nur 256-Farben-Unterstützung fällt pi auf die nächste Näherung zurück.

Überprüfen Sie die Truecolor-Unterstützung:

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

Dunkle Terminals: Verwenden Sie helle, gesättigte Farben mit höherem Kontrast.

Helle Terminals: Verwenden Sie dunklere, gedämpfte Farben mit geringerem Kontrast.

Farbharmonie: Beginnen Sie mit einer Basispalette (Nord, Gruvbox, Tokyo Night), definieren Sie sie in vars und referenzieren Sie sie konsistent.

Testen: Überprüfen Sie Ihr Theme mit verschiedenen Nachrichtentypen, Tool-Status, Markdown-Inhalten und langem umbrochenem Text.

VS Code: Setzen Sie terminal.integrated.minimumContrastRatio auf 1 für genaue Farben.

Sehen Sie sich die integrierten Themen an:

• dark.json
• light.json