pi-openspec-status

A pi coding agent extension that displays the active OpenSpec change status as a persistent TUI widget above the editor, with an interactive dialog for detailed views.

Features

• Persistent TUI widget — always visible above the editor in interactive mode, automatically suppressed in non-interactive modes (-p, --json, headless RPC)
• Single-change detailed view — when one active change exists, shows the change name, schema, per-artifact status (proposal, design, specs, tasks), and a task progress bar with apply dependency hints
• Multi-change overview — when multiple active changes exist, shows a header with the active count followed by one condensed line per change with aligned change names, artifact labels, task counters, and blocked-dependency hints
• Artifact status indicators — uses filled circle (●) for done, open circle (○) for ready, and dotted circle (◌) for blocked, each colored with theme-aware success/muted/warning colors
• Interactive dialog — press Ctrl+Alt+O to open a scrollable dialog with full change details, task breakdowns, and dependency info
• Automatic data refresh — event-driven refreshes fetch from the openspec CLI on session start, after each agent turn/end (debounced 500ms), and when tools write to openspec/ (with either path separator) or Bash/PowerShell commands reference openspec; a bounded fallback safety poll starts at 30 seconds and backs off to at most 120 seconds when unchanged
• Error resilience — gracefully shows "CLI not found" when openspec is unavailable, silently no-ops when not in an OpenSpec project, and retains last-known state with a muted error indicator on CLI failures

Screenshots

Widget showing a single active change with artifact status and task progress

Interactive overlay dialog showing detailed change breakdown and dependencies

Install

From npm (recommended)

pi install npm:pi-openspec-status

Or with a specific version:

pi install npm:pi-openspec-status@0.8.1

From GitHub

pi install git:github.com/mattoopie/pi-openspec-status

Or with a specific version:

pi install git:github.com/mattoopie/pi-openspec-status@v0.8.1

Usage

Once installed, the widget appears automatically when you're in a project that has an openspec/changes/ directory with active change subdirectories.

Interactive dialog

Press Ctrl+Alt+O in interactive mode to open a scrollable dialog displaying the full OpenSpec change status. The dialog shows:

• All active changes with their artifact completion status
• Task breakdowns with completed/total counts per change
• Dependency information for blocked artifacts

This is useful when the compact widget above the editor doesn't show enough detail, or when you want to browse through changes in a larger view.

Note: The dialog is only available in interactive mode (it is suppressed in -p, --json, and headless RPC sessions).

Requirements

On Windows, the extension first tries Pi's normal command execution. If that fails, it retries through cross-spawn to support npm's Windows launchers. A successful fallback is cached per Pi API instance and reused for availability checks and list/status commands. Both launchers resolve openspec from the inherited environment; the extension does not locate a JavaScript entry point or explicitly run OpenSpec through Node.

• A project using OpenSpec with changes in openspec/changes/
• Each change directory may contain:
  • .openspec.yaml — with a schema field (optional, defaults to "spec-driven")
  • proposal.md, design.md, tasks.md — artifacts tracked as "done" when present
  • specs/ — directory tracked as "done" when non-empty

Display

The widget renders different layouts depending on the number of active changes and available terminal width.

No active changes

No active OpenSpec changes

Single active change (3-line detailed view)

◷ add-auth (spec-driven)
Artifacts: proposal ● design ○ specs ○ tasks ○
Tasks: ████░░░░░░ 3/7

• Line 1: Status icon (✓ when fully complete, ◷ in-progress, ✗ blocked/error), change name, and schema name in parentheses
• Line 2: Each artifact (proposal, design, specs, tasks) with a status icon — ● done (success), ○ ready (muted), ◌ blocked (warning)
• Line 3: Task progress bar with completed/total count

Multiple active changes (header + condensed lines)

OpenSpec (2 active)
◷ add-auth  P ● D ○ S ○ T ○  3/7
✗ bugfix    P ● D ◌ S ○ T ○  0/0  (blocked: design)

• Header: "OpenSpec (N active)" in accent color
• Per change (one line): Status icon, truncated change name in a compact padded column (sized to the longest displayed name, capped at 35% of the width), artifact labels (P=proposal, D=design, S=specs, T=tasks) each with a status icon, task counter (completed/total), and a blocked-dependency hint when applicable. Full artifact names are used when they fit on every row; otherwise all rows use initials.

When stdout does not report a usable terminal width, the widget uses PI_OPENSPEC_STATUS_WIDTH if set to a positive integer, or defaults to 120 columns. Set the environment variable to the target width when running pi behind a web/RPC client; the extension does not receive the browser viewport width automatically.

Error states

Development

# Clone and install dependencies
git clone https://github.com/mattoopie/pi-openspec-status.git
cd pi-openspec-status
npm install

# Test locally with pi
pi -e ./extension/index.ts

License

MIT