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