catppuccin-pi

Soothing pastel themes for the Pi coding agent

Packages

Package details

theme

Install catppuccin-pi from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:catppuccin-pi
Package
catppuccin-pi
Version
0.1.0
Published
Sep 4, 2026
Downloads
162/mo · 25/wk
Author
hnnazm
License
MIT
Types
theme
Size
15.8 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "themes": [
    "./themes/*.json"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Previews

Installation

Local Pi package

Clone this repository, then install its absolute path:

git clone https://github.com/catppuccin/pi.git
cd pi
pi install "$PWD"

Use pi install -l "$PWD" instead to register it only for the current project. Pi may ask you to trust a project before loading project-local resources.

Manual

Copy one or all theme files into Pi's global theme directory:

mkdir -p ~/.pi/agent/themes
cp themes/catppuccin-*.json ~/.pi/agent/themes/

If PI_CODING_AGENT_DIR is set, use $PI_CODING_AGENT_DIR/themes/ instead.

npm

Install the published package with:

pi install npm:catppuccin-pi

Usage

Choose a flavor from /settings, or start one session without changing saved settings:

pi --use-theme catppuccin-mocha

Follow terminal light/dark appearance automatically:

pi --use-theme catppuccin-latte/catppuccin-mocha

Frappé or Macchiato can replace Mocha in that pair. For a file checked out locally without package installation:

pi --theme ./themes/catppuccin-mocha.json --use-theme catppuccin-mocha

Pi hot-reloads the active custom theme when its file changes. A truecolor terminal is recommended; check that $COLORTERM is truecolor or 24bit.

Supported flavors

Flavor Theme name Appearance
Latte catppuccin-latte Light
Frappé catppuccin-frappe Dark
Macchiato catppuccin-macchiato Dark
Mocha catppuccin-mocha Dark

Compatibility

Themes target the Pi 0.84.2 theme contract and include all 55 color tokens known to that release, including optional search, scrollbar, and maximum-thinking colors. New optional Pi tokens retain Pi's documented fallbacks until this port adopts them.

Bash and Readline do not parse theme files. Pi owns shell execution and line editing; this package only sets Pi's bashMode border color. It therefore has no shell-version-specific branches.

Development

Requirements: Node.js 20 or newer and npm.

npm ci
npm run generate       # regenerate themes
npm run previews       # regenerate SVG previews
npm run check          # unit, schema, provenance, contrast, and freshness checks
npm run smoke:pi       # offline load test using the installed pi executable
npm pack --dry-run     # inspect the distributable package

Generated JSON and SVG files are committed and must not be edited manually. See the maintenance guide, validation evidence, and implementation plan.

💝 Thanks to