pi-animations

Animated thinking, working, and tool-execution indicators for pi coding agent.

Replace pi's default spinner with 21 terminal animations — from demoscene fire to Matrix rain to Pac-Man — all rendered inline with ANSI true color and Nerd Font glyphs.

Demo

Install

From npm (recommended)

pi install npm:pi-animations

From GitHub

pi install git:github.com/arpagon/pi-animations

Try without installing

pi -e npm:pi-animations

Manual

git clone https://github.com/arpagon/pi-animations.git
pi -e ./pi-animations/animations.ts

Or add to ~/.pi/agent/agent.json:

{
  "extensions": [
    "npm:pi-animations"
  ]
}

Or via git:

{
  "extensions": [
    "git:github.com/arpagon/pi-animations"
  ]
}

Usage

Everything is under the /animation command:

/animation                          Show status, list all animations, and help
/animation showcase                 Interactive browser (←/→ to navigate, Enter to select)
/animation <name>                   Set animation for all states
/animation working:<name>           Set working animation only
/animation thinking:<name>          Set thinking animation only
/animation tool:<name>              Set tool execution animation only
/animation width full               Full terminal width (default)
/animation width default            50 columns
/animation width <number>           Custom column count
/animation random                   Random animation each time
/animation on                       Enable animations
/animation off                      Disable animations

Example config

/animation thinking:aurora
/animation working:matrix3
/animation tool:fire3
/animation width full

Animations

1-line

Name	Category	Description
neural-pulse	thinking	Energy pulses along neural pathway
glitch-text	both	Cyberpunk glitch effect
plasma-wave	thinking	Colorful plasma band
pacman	working	Pac-Man eating dots
matrix	both	Matrix rain
pipeline	working	CI/CD pipeline with nerd font icons
starfield	thinking	Horizontal parallax stars
fire	working	Demoscene fire
icon-morph	both	Morphing nerd font icons
brainstorm	thinking	Weather icon brainstorm
dev-constellation	thinking	Dev language icons with pulses
crush	both	Crush-style character scrambler
pi-pulse	both	Pi logo with gradient pulse
shimmer	thinking	Rainbow shimmer text
typewriter	both	Themed typewriter messages
orbit-dots	thinking	Pulsing orbit dots
neon-bounce	working	Neon ball bouncing between walls

3-line

Name	Category	Description
fire3	working	🔥 Demoscene fire
matrix3	both	🟢 Matrix rain
starfield3	thinking	✦ Deep starfield
aurora	thinking	🌌 Aurora borealis

Categories

• thinking — shown while the model is reasoning (extended thinking phase)
• working — shown while the model generates a response
• tool — shown while tools execute (file reads, bash commands, etc.)
• both — suitable for any state

How it works

Three animation states

pi has three distinct phases during a request:

1. Thinking — The model reasons internally (e.g., Claude's extended thinking, OpenAI's chain-of-thought). The extension detects thinking_start/thinking_end stream events.

2. Working — The model generates visible text output. Detected via agent_start/agent_end events.

3. Tool — A tool is executing (bash, file read/write, etc.). Detected via tool_execution_start/tool_execution_end events.

Priority: thinking > tool > working. If the model is thinking while a tool runs, the thinking animation takes precedence.

Rendering

• 1-line animations use ctx.ui.setWorkingMessage() to replace the Loader's text inline alongside pi's braille spinner.
• 3-line animations use ctx.ui.setWidget() to render a multi-line widget.
• Thinking label patches AssistantMessageComponent.updateContent() to animate the collapsed "Thinking..." text in the message body.

Phase-aware text

Animations that display text (glitch-text, crush, shimmer, orbit-dots) automatically adapt their label:

• Thinking state → "Thinking..."
• Working state → "Working..."
• Tool state → "Running..."

Full-width rendering

Visual animations (fire, plasma, matrix, starfield, aurora, neon-bounce) scale to fill the terminal width. Structural animations (pacman, pipeline, neural-pulse) keep a fixed size.

Configurable via /animation width.

Persistence

All settings are saved to ~/.pi/agent/extensions/pi-tui-animations.json and restored on startup:

{
  "workingAnim": "matrix3",
  "thinkingAnim": "aurora",
  "toolAnim": "fire3",
  "width": "full",
  "randomMode": false,
  "enabled": true
}

Requirements

• pi coding agent v0.60+
• Terminal with true color (24-bit ANSI) support
• Nerd Font (for icon-based animations: pipeline, dev-constellation, icon-morph, pi-pulse, brainstorm)

Development

Standalone animation demos

Each animation has a standalone demo in explorations/:

bun run explorations/12-fire.ts
bun run explorations/20-crush-scramble.ts

Run all demos in tmux:

bash tmux-demo.sh
tmux attach -t pi-anims
# Ctrl-b n/p to navigate between windows

Project structure

pi-animations/
├── animations.ts         Extension: 21 animations + /animation command
├── package.json
├── explorations/         Standalone animation demos (bun run)
├── tmux-demo.sh          Launch all demos in tmux
├── AGENTS.md             Agent context
└── README.md

Adding a new animation

1. Add a renderer function in animations.ts:

export const myAnimation: AnimationFn = (frame, width, phase?) => {
    const label = PHASE_LABELS[phase || "thinking"];
    // ... render logic using frame counter and width
    return "single line result";    // or ["line1", "line2", "line3"] for 3-line
};

2. Register it in the ANIMATIONS array:

{ name: "my-anim", fn: myAnimation, category: "both", description: "My animation", lines: 1 },

3. Done — it appears in /animation showcase and /animation my-anim.

License

MIT