@leo-alvarenga/pi-status-broadcaster

A pi extension that broadcasts session status to a shared JSON file for external tools to consume

Packages

Package details

extension

Install @leo-alvarenga/pi-status-broadcaster from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:@leo-alvarenga/pi-status-broadcaster
Package
@leo-alvarenga/pi-status-broadcaster
Version
0.3.5
Published
Sep 21, 2026
Downloads
342/mo · 14/wk
Author
leo-alvarenga
License
MIT
Types
extension
Size
11.2 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@leo-alvarenga/pi-status-broadcaster

A pi extension that broadcasts the status of every active session to a shared JSON file at /tmp/pi-status-broadcaster/status.json.

External tools (scripts, status bars, dashboards) can poll this file to inspect running pi sessions without any IPC.

Features

  • Writes session status (IDLE / BUSY) on every agent turn boundary
  • Auto-generates a human-readable session name on first start (docker-style adjective-noun)
  • Name is persisted in the report file and recovered on resume — even after the session finishes
  • /rename-session <name> command to set a custom name at any time
  • Atomic writes via temp-file rename — safe for concurrent readers
  • Session ID is stable across resumes (uses pi's own session ID)

Install

pi install npm:@leo-alvarenga/pi-status-broadcaster

Or add the npm spec to your .pi/settings.json packages and run /reload.

Commands

Command Description
/rename-session <name> Rename the current session. The name is saved to the report file immediately and persisted across resumes.

Report schema

type ReportSchema = Record<string, SessionEntry | FinishedEntry>;

type SessionEntry = {
  id: string;
  cwd: string;
  name?: string;         // human-readable name (auto-generated or set via /rename-session)
  createdAt: string;
  resumedAt?: string;
  lastUpdatedAt: string;
  currentModel: string;
  tokens: { total: number; input: number; output: number };
  todos: { done: number; created: number; inProgress: number };
  status: "IDLE" | "BUSY";
};

type FinishedEntry = {
  finished: true;
  name?: string;         // preserved so resume can recover the original name
  createdAt: string;
  finishedAt: string;
};
  • IDLE — session is waiting for user input
  • BUSY — agent is actively generating a response
  • A FinishedEntry is written on session shutdown; it is overwritten with a fresh SessionEntry on resume

File safety

Writes go through an atomic writeFileSync + renameSync on a .pid.tmp sidecar, so readers never see a partial file.

License

MIT