# vite-plugin-agent-presence

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

## Install

```sh
pnpm add -D vite-plugin-agent-presence
```

## Vite setup

```ts
// 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:

```sh
pi install npm:vite-plugin-agent-presence
```

For project-local installation, add `-l`:

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

The package declares a Pi manifest:

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

You can also wire it manually:

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

Or customize options:

```ts
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:

```txt
node_modules/.vite/agent-presence.json
```

Example:

```json
{
  "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:

```ts
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.