pi-teammate-ui

A real-time web monitor for pi-teammate agent teams. This is a companion UI — it reads the team's shared SQLite message bus and visualizes agent relationships, message flows, and task progress in your browser.

What is this?

pi-teammate turns multiple pi sessions into a collaborative peer network where every AI agent can communicate with any other agent. Agents talk through a shared SQLite database at ~/.pi/pi-teammate/<team-name>/team.db using structured events like task_req, task_ack, task_done, broadcast, etc.

While pi-teammate ships with TUI widgets (roster, task tracker, MAMORU log) accessible via Ctrl-t shortcuts, this project provides a full-screen browser UI that lets you:

• See all agents as colored cards with live status (available/busy/inactive)
• Watch every message fly in as it happens (WebSocket push, no polling)
• Click any message to see its full payload, including detail file contents
• Filter by specific agent (as sender / receiver / both) and by event types
• Share filtered views via URL — all filters sync to query params

⚠️ Prerequisites

You must install and run pi-teammate first. This UI is a read-only viewer — it does not create or manage teams.

1. Install pi and pi-teammate

# Install pi (see https://github.com/mariozechner/pi for details)

# Install the teammate extension
pi install npm:pi-teammate

2. Create a team and start agents

Open multiple terminals and spin up your agents. Example with three roles:

# Terminal 1 — create the team
pi --team-channel my-project --agent-name designer --team-new

# Terminal 2 — join as developer
pi --team-channel my-project --agent-name developer

# Terminal 3 — join as tester
pi --team-channel my-project --agent-name tester

Each agent needs a persona.yaml in its working directory defining its name, role, provider, and model. See the pi-teammate docs for details.

3. Give them work

Type a prompt into any agent (e.g. the designer):

Build a dashboard that shows realtime forex quotes.

The agents will autonomously delegate, ask questions, review code, and collaborate via the shared message bus.

4. Install Bun (runtime for this UI)

curl -fsSL https://bun.sh/install | bash

🚀 Run the UI

Once your team is working, open a new terminal and start the monitor:

npx pi-teammate-ui

Then open http://localhost:3456. The UI auto-discovers all teams under ~/.pi/pi-teammate/*/team.db — pick one from the dropdown in the header.

CLI options

npx pi-teammate-ui --port 4000      # custom port
npx pi-teammate-ui --help

Features

Agent roster with live status

Each agent is shown as a colored card with its avatar, full session ID, status dot (🟢 available / 🟡 busy / 🔴 inactive), and model info. The grid adapts from 1 to 5+ columns depending on screen width.

Message timeline

Every message rendered as a directional flow [from] → event → [to], with color-coded arrows by event type (blue = task_req, green = task_ack / task_done, yellow = task_update, red = failures, purple = broadcasts, etc.). New messages fly in from the left with an elastic bounce animation.

Two-column layout on wide screens

On screens ≥1024px, the flow diagram sits on the left and the full message content wraps multi-line on the right. On narrower screens it stacks vertically.

Click any message for full detail

The modal shows:

• Event badge, from → to flow, timestamp, channel
• Task ID, reply-to chain, intent, needs-reply flag
• Full message content (unwrapped)
• Detail file viewer — if the payload has a detail field pointing to a file, click "📄 View File" to load and display its contents inline
• Collapsible raw JSON payload

Filters (with URL persistence)

• Click an agent card to show only messages involving that agent. Two checkboxes appear: → Sender and ← Receiver (both on by default).
• Event type chips — toggle individual event types on/off, or use All/None buttons.
• All filters sync to URL query params (?agent=tom&sender=0&events=task_req,task_done) so bookmarks and hard refreshes work.

Light / dark theme

Toggle via the ☀️/🌙 button in the header. Preference persisted to localStorage.

Live updates via WebSocket

A background poller on the server hashes the DB state every 2 seconds and only pushes to connected browsers when data actually changes — no wasteful repaints, no flashing.

Architecture

• Backend (Bun.serve + WebSocket)

  • Reads team.db via bun:sqlite in read-only mode
  • Background poller diffs a hash of agent statuses + message IDs every 2s
  • Publishes updates to subscribed clients via Bun.pubsub
  • Resolves agent session UUIDs to friendly names before sending to frontend

• Frontend (React 19 + React Router v7)

  • Bundled on-the-fly by Bun's HTML importer (no webpack / vite)
  • WebSocket hook with auto-reconnect
  • All filters and selected team stored in URL via useSearchParams

index.ts                  # Bun server + WebSocket
bin/cli.cjs               # Node launcher (for npx)
src/
├── api/
│   ├── db.ts             # SQLite reader + change-hash
│   └── routes.ts         # /api/teams, /api/team-data, /api/file-content
├── components/
│   ├── App.tsx
│   ├── TeamDiagram.tsx   # Agent roster + message timeline + filters
│   └── MessageModal.tsx  # Click-to-open detail modal
├── hooks/
│   ├── useTeamSocket.ts
│   └── useTheme.ts
├── eventTheme.ts
└── styles/
    ├── global.css        # Light/dark theme variables
    └── flow.css

Development

bun install
bun run dev     # with HMR
bun run start   # production

Related

• pi-teammate — the agent communication framework this UI monitors
• pi — the underlying coding agent harness

License

MIT