@99percentpeople/pi-cursor-effect

A focused Pi extension for selectable visual effects on Pi's main session status cursors.

Pick a preset (Claude Code or Codex) for an authentic busy-row look, or build your own: spinner glyph, animated label effects (wave, shimmer, scan, rainbow), speed, color, and direction — all from /99settings. Runtime metrics add task elapsed time, output tokens, estimated live throughput, and a final summary independently of the selected theme.

Demo

Animated working cursor while the model is busy (Claude Code preset):

Scope

This package changes Pi's main working, retry, compaction, and branchSummary status indicators, including labels such as:

⠦ Working...
⠦ Thinking...
⠦ Analyzing the request
⠦ Responding…
⠦ Compacting context... (escape to cancel)
⠦ Retrying (1/3) in 2s... (escape to cancel)

It does not change assistant Items, reasoning content, tool/bash loaders, widgets, message bodies, model events, or session data. Metrics observe model lifecycle events and optionally send a completion summary via ctx.ui.notify(). Other extensions, such as thinking-fold, provide their status labels as plain text and remain fully functional without this package.

Themes

• default (default): do not override Pi's native loader or label;
• claude-code: the inspected Claude Code 2.1.x platform-specific mark cycle, 120ms glyph timing, ANSI 256 orange, and right-to-left three-character label glimmer;
• codex: the current Codex busy-row bullet and synchronized two-second label shimmer, refreshed every 32ms;
• custom: independently configure Loader and Label effects.

Preset themes intentionally expose no speed or color overrides. Custom keeps Loader and Label controls independent and retains their values while another preset is selected.

Custom Loader effects

Effect	Description
Pi default	Pi's ten-frame Braille spinner
None	Hide the leading indicator
Claude Code	The platform-specific Claude mark sequence
Pulse	· • ● • pulse
Dots	Fixed-width three-dot fill
Bounce	Rising and falling block
Orbit	◐ ◓ ◑ ◒ rotation

Every visible Custom loader supports Slow/Normal/Fast speed and Accent/Text/Muted/Claude color. Frames have a stable display width, so the label does not jump horizontally.

Custom Label effects

Effect	Description
None	Keep the native label styling
Wave	A crest with a softer trailing band
Shimmer	A cosine-smoothed highlight
Scan	A crisp moving highlight band
Pulse	Whole-label brightness breathing
Rainbow	A moving ANSI 256-color spectrum

Animated labels support speed and a loop pause. Moving effects also support left-to-right, right-to-left, and ping-pong directions. Wave, Shimmer, and Scan provide crest width controls; all non-Rainbow effects support Accent, Thinking, and Monochrome palettes. Loader and Label clocks are independent, and label segmentation preserves emoji and combining-character graphemes.

Runtime metrics

All four switches are enabled by default and available under /99settings → Cursor Effect → Runtime metrics in every theme:

Setting	Display
Elapsed time	Total busy interval, including tools, automatic retries and compaction
Output tokens	Completed provider-reported output plus an estimate for the streaming response
Live speed	≈48.2 tok/s while working; Avg 46.1 tok/s using provider-reported output in the completion notification
Completion notification	Notify once with enabled metrics when the task settles; no persistent footer status

Completion notifications follow the elapsed-time, output-token and live-speed switches. There is no separate average-speed switch; legacy averageSpeed values are ignored. Disabling all three metrics suppresses the notification. The default working label is displayed as Working...; custom labels are unchanged.

Illustrative output:

⠦ Responding... 18s ≈860 out ≈47.8 tok/s
⠦ Working... 32s 1,024 out ≈47.8 tok/s

Done 42s 1,280 out Avg 46.1 tok/s

Timing and accuracy: elapsed time uses a monotonic local clock and stops at agent_settled, not the earlier agent_end. Speed measures client-observed model-call throughput from turn_start to assistant message_end, including request preparation and first-output waiting, but excluding subsequent tool execution, retry backoff, compaction and user idle time. It is not a server-side decode-speed measurement. Final speed divides summed output by summed measured model-call durations, rather than averaging individual rates.

During tool execution or the next call's first-output wait, live speed retains the last displayed value; it is not a measurement of that waiting interval. A new task resets the retained value, and speed stays absent until its first valid sample.

Live estimates count streamed text, visible thinking and tool-call JSON using approximately four ASCII characters or one non-ASCII code point per token. They are not tokenizer-exact and cannot measure hidden reasoning; every estimated count/rate has an ≈ prefix. Final counts use usage.output, whose reasoning/tool-token coverage depends on the provider, so final and live rates can differ. No model calls or network requests are added for measurement. Missing usage for a response with visible output (or an error/abort) produces out — / Avg — tok/s rather than a fabricated total. Rates for spans shorter than 500ms are withheld. Errors and cancellation are labelled in the summary.

Retry, compaction and branch-summary rows show only elapsed task time while a task is active; their internal model usage is not included. Standalone manual compaction/branch summarization is not measured. Background tasks surviving the agent's completion are not part of its elapsed time.

Metrics are appended only during rendering: existing labels from thinking-fold remain untouched, and the suffix uses dim styling rather than the label animation. A 250ms refresh keeps metrics moving even with both animations disabled. Timers are stopped with their loaders and cleaned up on session shutdown/reload. Pi's native wrapping/clipping also applies to metrics, including editor-border status placement and narrow terminals. Completion summaries use Pi's notification UI, independently of custom footers. The existing completionSummary config key is preserved for compatibility. There is no history persistence or reconstruction of timings after reload.

Install

pi install npm:@99percentpeople/pi-cursor-effect

For local development, build the npm artifact before installing the package directory:

bun run build:packages
bun run --cwd extensions/cursor-effect build
pi install ./extensions/cursor-effect

Restart Pi or run /reload after installation.

Settings

Run /99settings. All themes expose runtime metrics:

Cursor Effect
Theme            Claude Code
Runtime metrics  4/4 On

Selecting Custom dynamically reveals the two detailed submenus:

Cursor Effect
Theme          Custom
Runtime metrics 4/4 On
Loader effect  Pi default
Label effect   Wave

The shared menu displays only installed @99percentpeople plugins that expose configurable values. Configuration persists in:

~/.pi/agent/99extensions.json

under the cursor-effect namespace:

{
  "cursor-effect": {
    "theme": "default",
    "metrics": {
      "elapsed": true,
      "outputTokens": true,
      "liveSpeed": true,
      "completionSummary": true
    },
    "custom": {
      "loader": {
        "style": "pi-default",
        "speed": "normal",
        "color": "accent"
      },
      "label": {
        "style": "wave",
        "speed": "normal",
        "crestWidth": "soft",
        "palette": "accent",
        "direction": "left-to-right",
        "pause": "none"
      }
    }
  }
}

Compatibility

Pi does not currently expose a renderer hook for its main status indicators. This package therefore installs a guarded patch on Loader.updateDisplay(), Loader.render(), and Loader.stop(), activated only for Pi's four main status kinds: working, retry, compaction, and branchSummary. The stop() wrapper owns the independent Label timer and prevents it from outliving a status row. Tool, bash, and extension loaders do not have those kinds and remain unchanged. The patch checks the expected methods at startup, avoids duplicates, and restores the original prototype during session shutdown. Pre-styled ANSI labels are left unchanged; enabled metrics can still be appended after them.

Streaming label changes preserve the current Label effect phase instead of restarting it for every partial summary or status message. Loader animation remains driven by Pi's normal interval callbacks. Pi rendering and extension callbacks share Node's main event loop, so terminal animation cannot redraw while a synchronous callback is blocking that thread.

License

MIT