pi-agentarium

Ambient multi-agent observability for Pi — a terminal habitat for your coding agents.

pi-agentarium turns agent activity into a small living terminal habitat: a professional visualization layer for observing coding agents while they work.

When Pi thinks, runs tools, or finishes a turn, the meadow blooms and the pond ripples. When several Pi sessions are running, each one becomes a plant, fish, star, or stone in the shared habitat.

Demo

The demo shows the ambient overlay cycling through flowers, pond, constellation, and sand modes.

Features

• Ambient widget below the editor while agents are active; hidden at startup and idle
• Wildflower meadow where agent usage grows healthier plants and attracts wildlife
• Persistent garden memory across Pi sessions via ~/.pi/agent/agentarium/garden-events.jsonl
• Koi pond overlay with bubbles, ripples, and living agent fish
• Constellation dashboard for multi-agent workflows
• Sand view for a minimal ambient display
• Multi-agent heartbeat via ~/.pi/agent/agentarium/agents/*.json
• Low resource usage: small timers and dependency-minimal design
• Passive display: the widget does not capture keyboard input; overlay is opened manually

Install

Install from GitHub:

pi install git:github.com/damngamerz/pi-agentarium

Or try it for one Pi run without installing:

pi -e git:github.com/damngamerz/pi-agentarium

Once published to npm, install with:

pi install npm:pi-agentarium

After installing globally, run /reload in Pi or restart Pi.

Local development

npm ci
npm run typecheck
pi -e ./src/index.ts

Commands

Command	Description
/agentarium	Open the default overlay
/agentarium flowers	Open wildflower meadow view
/agentarium jungle	Alias for flowers, with terminal-friendly wildlife
/agentarium pond	Open koi pond view
/agentarium constellation	Open multi-agent constellation
/agentarium dashboard	Alias for constellation/dashboard view
/agentarium sand	Open sand view
/agentarium demo	Open with simulated agent activity
/agentarium mode flowers	Set the bottom widget mode without opening overlay
/agentarium mode pond	Set the bottom widget to pond
/agentarium mode constellation	Set the bottom widget to constellation / sky
/agentarium mode sand	Set the bottom widget to sand
/agentarium on	Enable ambient widget
/agentarium off	Disable ambient widget
/agentarium above	Put widget above editor
/agentarium below	Put widget below editor
/agentarium status	Show current status
/agentarium stats	Show lifetime Agentarium counters

Shortcut:

Ctrl+Alt+Z   open Agentarium overlay

Overlay controls:

Tab          cycle modes
1 / f        flowers
2 / p        pond
3 / c        constellation / sky
4 / s        sand
Space        create bloom/ripple
D            toggle demo agents
R            refresh heartbeats
Q / Esc      close overlay

CLI flags

pi --agentarium=false
pi --agentarium-view constellation

Views: flowers, pond, constellation, sand.

To set the ambient bottom widget without opening the overlay:

/agentarium mode flowers
/agentarium mode pond
/agentarium mode constellation
/agentarium mode sand

Mode, widget placement, and widget enabled state are saved across Pi sessions.

Design notes

Agentarium focuses on ambient observability:

• passive widget while agents are active
• manual overlay for focused inspection
• terminal-friendly glyphs and colors
• lightweight timers and file-based heartbeat sharing
• useful activity signals without requiring attention

The goal is to make agent work easier to follow while preserving the terminal workflow.

Persistence

Agentarium has three layers of local state:

• Live agent presence is stored in ~/.pi/agent/agentarium/agents/*.json and expires/removes when agents stop.
• Meadow health is stored permanently in ~/.pi/agent/agentarium/garden-events.jsonl.
• Display preferences are stored in ~/.pi/agent/agentarium/config.json.

That means the meadow can keep getting healthier across Pi sessions, projects, reloads, and restarts. Tool calls, turns, completions, user bash activity, and errors are appended as tiny JSONL events.

What the visuals mean

State	Visual
Idle	resting stem/fish/star/stone
Thinking	blue bud / gentle pulse
Tool running	golden flowers, bees, pollen, activity
Completed turn	green bloom/ripple
More agent usage	healthier meadow, more wildflowers and wildlife
Error	muted rose bloom/thorn/ripple
Multiple agents	multiple plants/fish/stars/stones

Package shape

pi-agentarium/
  package.json
  src/
    index.ts
    state.ts
    heartbeat.ts
    garden-memory.ts
    config-memory.ts
    types.ts
    ui/components.ts

License

MIT