Rinco Pi Sakura

A Sakura Macaron theme and animated CyberDeck header for Pi.

Features · Installation · Usage · Customization · Development

简体中文

Rinco Pi Sakura is a lightweight appearance package that combines a soft, dark Sakura Macaron palette with a truecolor Unicode header and a one-shot blink animation. Pi loads the TypeScript extension directly, so no build step is required.

Features

• Complete theme — Styles messages, Markdown, tools, diffs, syntax highlighting, thinking levels, and exported pages.
• Animated header — Renders Unicode artwork with a per-character Sakura-to-Sky 24-bit RGB gradient.
• Startup animation — Plays a blink sequence when a session starts, then leaves the artwork open and static.
• Responsive layout — Clips and centers content by terminal width and adjusts top spacing to the available height.
• Safe fallback — Skips header installation in headless, JSON, and print modes where no UI is available.
• Composable resources — The theme and header can be used independently or alongside extensions that do not replace the header region.

Installation

Install from npm (recommended)

pi install npm:rinco-pi-sakura

The published package is available on npm.

Install from GitHub

pi install git:github.com/Rinisnotarobot/rinco-pi-sakura

Install from a local checkout

git clone https://github.com/Rinisnotarobot/rinco-pi-sakura.git
cd rinco-pi-sakura
pi install "$PWD"

[!IMPORTANT] Pi extensions run with your user permissions. Review the source before installing any third-party extension.

Usage

Restart Pi after installation, or run:

/reload

Open /settings and select the following theme:

sakura-macaron

The header is enabled automatically when a Pi TUI session starts.

[!NOTE] For the best result, use a Truecolor terminal and a font that contains the required Unicode characters. The artwork is clipped automatically in narrow terminals.

Project contents

Path	Purpose
extensions/header/index.ts	Header rendering, responsive layout, and blink animation
themes/sakura-macaron.json	Sakura Macaron theme and complete Pi color palette
docs/theme-and-header.md	Palette, lifecycle, compatibility, and customization reference
docs/CONTRIBUTING.md	Local development, testing guidance, and pull request checklist
docs/README.zh-CN.md	Simplified Chinese README
tests/header.test.ts	Header lifecycle and rendering tests
tests/package.test.ts	Package manifest, resource, and theme schema tests

Customization

The two main customization points are:

• Edit vars in themes/sakura-macaron.json to change the base theme palette.
• Edit ANIME_ART, the telemetry label, and RGB gradients in extensions/header/index.ts to change the header.

Keep every color key required by the Pi theme schema. After changing the artwork, test clipping in both narrow and wide terminals. See the theme and header reference for details.

Development

Prerequisites

• Node.js 22.19 or later
• Pi

Install development dependencies:

npm install

Available commands

Command	Description
npm test	Run the complete Vitest suite once.
npm run test:watch	Run Vitest in watch mode and retest when files change.
npm run check	Run project verification tests; currently equivalent to a full Vitest run.
npm run pack:check	Inspect the publishable package with npm pack --dry-run without publishing it.

Run the test suite:

npm test

Watch for changes:

npm run test:watch

Verify tests and package contents:

npm run check
npm run pack:check

Vitest covers the extension lifecycle, header output, package resource paths, and theme palette. Pi loads the TypeScript source directly, so this project has no separate build command.

Troubleshooting

The header does not appear

1. Confirm that Pi is running in TUI mode rather than headless, JSON, or print mode.
2. Run /reload or restart Pi.
3. Run pi list to confirm that the package is installed.

Colors look incorrect

Make sure your terminal supports Truecolor. The header emits 38;2;r;g;b ANSI sequences, and the theme also depends on 24-bit color support.

The Unicode artwork is misaligned

Unicode cell widths vary between fonts and terminals. Use a monospaced font with broader Unicode coverage, or replace the artwork as described in the customization reference.