OpenSpec Tracker

A small footer that keeps your next OpenSpec task visible in Pi.

OpenSpec Tracker is a read-only Pi extension. It reads openspec/changes/*/tasks.md, identifies the most relevant change, and shows its progress and next open task in the footer — without editing the specification or creating another task system.

Why use it?

• Immediate context: see task progress and the active task title in Pi's footer.
• Smart selection: uses the current branch, the last successful openspec apply, or the most recently modified tasks.md.
• Automatic updates: changes to task files appear while Pi is idle.
• Persistent state: the selected change and task survive session reloads.
• Safe by design: the extension only reads tasks and watches files; it never modifies OpenSpec.

Installation

After the package is published to npm:

pi install npm:@danielsuhett/pi-openspec-tracker

Or install it directly from this public repository:

pi install git:github.com/DanielSuhett/pi-openspec-tracker

To test a local checkout during development:

pi -e ./extensions/openspec-tracker.ts

Restart Pi or run /reload after installation.

Usage

In a project containing openspec/changes:

/openspec-track

The command opens a selector to enable or disable the tracker. It also accepts:

/openspec-track on
/openspec-track off
/openspec-track another-change#1.1
/openspec-track clear

The expected change layout is:

openspec/
└── changes/
    └── my-change/
        └── tasks.md

Tasks must use the standard OpenSpec format:

- [ ] 1.1 Implement the change
- [x] 1.2 Validate the result

Changes in openspec/changes/archive and openspec/changes/specs are ignored.

How is the change selected?

The extension resolves the scope in this order:

1. Manually selected or session-persisted change;
2. Current branch (my-change or spec/my-change);
3. Change from the last successful openspec apply;
4. Most recently modified tasks.md.

Manual selection always takes priority and can switch the current change without modifying any project files.

Development

Requirements: Node.js >=22.6.0, npm, and a compatible Pi version.

npm ci
npm run verify

Individual checks:

npm test
npm run typecheck
npm run pack:check

The extension does not need to be compiled: Pi loads TypeScript directly, and the package manifest in package.json registers extensions/ as a Pi resource.

Project structure

extensions/openspec-tracker.ts  Pi lifecycle and UI integration
src/core.ts                      task parser, selection, and progress summary
test/                            unit tests and extension smoke tests
.github/workflows/ci.yml         tests, typecheck, packaging, and installation

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing.

License

MIT © 2026 Suhett.