pi-jarvis-sphere 🜄

English | 中文

Jarvis particle sphere for the pi agent — a particle-sphere overlay floating in the bottom-right corner of your pi terminal. It shifts color and animation with pi's live state — amber hand-drawn star loop while thinking, yellow clockwise particle ring during tool calls, cyan clockwise orbital particle flow while streaming the answer, and a denser pulse while TTS speaks — like a little assistant that's alive. Sub-agent activity (via pi-subagents) also animates the sphere as the tool state.

Simulated four-state animation (SMIL SVG, generated from the actual render code — flow field / refraction / orbital particle ring)

✨ Features

• Four-state animation, color = state:

  State	Color	Animation
  Idle	green #00e676	curl noise flow field (slow) + center water ripple
  Thinking	amber #ffab00	star shapes (7-shape loop hand-drawn, fixed counter-clockwise)
  Tool call	yellow #ffeb3b	uniform particle ring, clockwise — center hollow, 4 layers × 20 dots (80 particles), differential rotation: inner slower, outer faster
  Working (streaming answer)	cyan #00E5FF	orbital particle flow (clockwise, same as tool)
  Sub-agent	yellow (tool)	sub-agent activity reuses the tool animation via subagents:started / subagents:completed / subagents:failed signals
  Wind-down	keeps current color	1-second ease-out deceleration after thinking/tool/working ends, then back to idle

• TTS sync: when pi-ext-tts-mimo plays speech, the sphere pulses denser and faster, as if talking (idle 10 FPS → 30 FPS while speaking).

• Direction anchor: the flow field rotates clockwise/counter-clockwise; deceleration is eased so direction stays readable.

• Non-intrusive: a nonCapturing overlay — typing and keybindings are completely unaffected.

• Toggleable: /jarvis toggles it on/off, persisted to config.json (on by default).

• Lifecycle-safe: mounts on session_start, cleans up on session_shutdown; sub-agent sessions don't double-mount; /reload doesn't leak listeners.

📦 Installation

Option A — npm (recommended)

pi install npm:@aiwayds/pi-jarvis-sphere

Option B — from source

# 1. Clone into its own directory (same convention as other ~/github pi extensions)
git clone https://github.com/fan56/pi-jarvis-sphere.git ~/github/pi-jarvis-sphere

# 2. Symlink into pi's extension dir (pi auto-discovers ~/.pi/agent/extensions/<name>)
ln -s ~/github/pi-jarvis-sphere ~/.pi/agent/extensions/pi-jarvis-sphere

# 3. /reload inside pi — done

Optional dependency: pi-ext-tts-mimo provides the tts:started / tts:stopped signals so the sphere can react to speech. Without it the sphere still works — just no talking pulse.

🎮 Usage

Command	Effect
/jarvis	Toggle the sphere on/off (state written to ~/.pi/agent/pi-jarvis-sphere.json)

config.json is user-editable in your agent dir (created on first /jarvis toggle):

{ "enabled": true }

Config precedence: ~/.pi/agent/pi-jarvis-sphere.json is read first if it exists; otherwise the package's bundled config.json is used as a read-only default. The package file is never overwritten — pi update won't lose your settings.

🧩 Plugin Architecture

Each animation lives in its own plugin file (closure-owned particle state) behind a unified interface; the scene → animation mapping is driven by config.json — swap animations by editing config, no code changes.

animations/          # animation plugins (new animation = new file + one registry line)
  flow-field.ts      # flow field + water ripple (idle default)
  refract.ts         # refraction particles
  stars.ts           # star shapes (think default; 7-shape loop hand-drawn)
  stars2.ts          # staggered star shapes (think default v2; two shapes overlapping)
  orbital.ts         # orbital particle ring (tool default)
  registry.ts        # id -> factory registry
lib/                 # shared layer: types / grid geometry / braille primitives / noise / scene config
config.json          # your editable "plugin catalog"

The scenes field of config.json controls which animation each scene mounts and its parameters:

{
  "enabled": true,
  "scenes": {
    "idle":    { "animation": "flow-field", "params": { "fieldSpeed": 0.06, "dir": 1, "fieldCount": 120, "fieldScroll": 0.02 } },
    "think":   { "animation": "stars",    "params": { "starSpeed": 0.02, "cycleFrames": 160, "starSize": 0.82, "breathSpeed": 0.04 } },
    "tool":    { "animation": "orbital",  "params": { "spinSpeed": 0.15, "dir": 1 } },
    "working": { "animation": "orbital",  "params": { "spinSpeed": 0.15, "dir": 1 } }
  }
}

Stars — think scene default

The default animation for the think scene: loops through 7 hand-drawn shapes — triangle → square → pentagram → hexagram → heptagram → octagram → enneagram — from simple to complex, each shape drawn edge-by-edge, rotating fixed counter-clockwise.

Seven shapes sampled at the hold-mid frame of each cycle, rendered from the actual render code (center breathing dots included)

Param	Meaning	Default
starSpeed	rotation speed (rad/frame; positive = counter-clockwise)	0.02
cycleFrames	frames per shape cycle — first 40% draws edges one-by-one + scales up, middle 45% full hold, last 15% shrink & hand-off	160
starSize	star circumradius as a fraction of the sphere radius	0.82
starStep	skip-step override (-1 = per-shape table; positive int mod n)	-1
breathSpeed	center breathing speed (0.04 ≈ one breath every 2.6 s)	0.04

Center breathing: a 2×2 dot cluster at the sphere's center pulses with a sine wave (1 → 4 dots lit).

Example — plug the "particle ring" (orbital) into the think scene: change one line of config.json:

"think": { "animation": "orbital", "params": { "spinSpeed": 0.15, "dir": 1 } },

Then /reload in pi. Missing params fall back to each plugin's defaults; dir controls rotation (1 = clockwise / -1 = counter-clockwise).

Note: think and working are independent animation slots — you can mount different animations per scene; the same animation in multiple scenes holds separate particle instances (no interference). working uses the same clockwise orbital particle flow as tool (dir: 1).

Stars2 — think scene default (v2)

The default think animation as of v1.1.0: staggered star shapes — the next shape starts generating when the current one is halfway through its lifecycle, so two shapes are always on screen simultaneously (50% phase offset). Shape order is randomized but never repeats the same shape twice in a row.

Param	Meaning	Default
starSpeed	rotation speed (rad/frame; positive = counter-clockwise)	0.02
cycleFrames	frames per shape cycle (second shape starts at the 50% phase of the first)	160
starSize	star circumradius as a fraction of the sphere radius	0.82
breathSpeed	center breathing speed (0.04 ≈ one breath every 2.6 s)	0.04

🧪 Development & Debugging

• After editing, /reload in pi hot-reloads (jiti runs .ts directly — no build step).
• Syntax check: node -e "…typescript.transpileModule…" (no tsc build).
• To test: dispatch a sleep N sub-agent to observe the sub-agent/tool state (yellow · clockwise vortex); a normal Q&A to observe the think state (amber · star shapes).

🗺️ Roadmap

• V2: standalone external window (extension spins up a local WebSocket + browser, real 3D WebGL particle sphere)
• Think-level color ramp (off→max thermal gradient; once implemented, later superseded by the four-state colors)

📜 Changelog

See CHANGELOG.md for the full version history.