vite-plugin-agent-presence

Dev-only Vite overlay that shows when a Pi coding agent is active in your project.

Install

pnpm add -D vite-plugin-agent-presence

Vite setup

// vite.config.ts
import { defineConfig } from "vite";
import agentPresence from "vite-plugin-agent-presence";

export default defineConfig({
  plugins: [agentPresence()],
});

The plugin only applies during vite serve. It registers JSON endpoints under /__agent_presence, keeps active agents in memory, broadcasts updates through Vite HMR (server.ws.send), and injects a small browser overlay.

Pi extension setup

Install the extension as a Pi package from npm:

pi install npm:vite-plugin-agent-presence

For project-local installation, add -l:

pi install -l npm:vite-plugin-agent-presence

The package declares a Pi manifest:

{
  "pi": {
    "extensions": ["./dist/pi/index.js"]
  }
}

You can also wire it manually:

// .pi/extensions/agent-presence.ts
export { default } from "vite-plugin-agent-presence/pi";

Or customize options:

import { piAgentPresence } from "vite-plugin-agent-presence/pi";
export default piAgentPresence({ heartbeatMs: 5000, ttlMs: 15000 });

The extension uses Pi lifecycle hooks. It sends start on agent start, update for turns/tool calls/edits, periodic heartbeat, and done on agent end or session shutdown. The LLM never needs to call a tool.

Discovery

When Vite starts, the plugin writes:

node_modules/.vite/agent-presence.json

Example:

{
  "url": "http://localhost:5173/__agent_presence",
  "projectRoot": "/absolute/path/to/project",
  "pid": 12345,
  "token": "random-dev-token"
}

Pi discovery order:

1. VITE_AGENT_PRESENCE_URL environment variable (VITE_AGENT_PRESENCE_TOKEN optional)
2. node_modules/.vite/agent-presence.json in the current workspace
3. fallback scan of localhost ports 5173-5183

If no Vite dev server is running, the extension fails silently.

HTTP protocol

Payload:

export type AgentPresence = {
  id: string;
  name?: string;
  tool?: string;
  task?: string;
  status?: "working" | "thinking" | "editing" | "done";
  startedAt?: number;
  updatedAt?: number;
  ttlMs?: number;
};

Endpoints:

• POST /__agent_presence/start
• POST /__agent_presence/update
• POST /__agent_presence/heartbeat
• POST /__agent_presence/done
• GET /__agent_presence/state

Pi sends IDs like pi:<sessionId> and { "name": "Pi", "tool": "pi-agent" }.

Security

This is dev-only and localhost-oriented. POST endpoints require the random token from the discovery file when available. Do not expose your Vite dev server publicly.