Pi Retention

Local retention tracker for Pi skills and extensions.

What this is

Pi Retention counts local usage, surfaces expired items, and quarantines one stale item at a time on startup.

Startup behavior

On each Pi launch, Pi Retention evaluates expired active roots and may prompt for at most one quarantine candidate.

• Ordering: earliest dueAt wins; ties break on oldest lastUsedAt (age).
• Deny: declining the prompt changes nothing; the same candidate is offered on the next launch.
• Excluded: pinned (P), quarantined (Q), self-protected, and not-yet-due roots never appear in the startup prompt.
• Report: /retention:report uses the same ordering and labels the startup candidate explicitly.

See ROADMAP.md for MVP scope and non-goals.

Features

• Tracks usage locally per artifact root
• Reports stale and protected items
• Prompts once per startup for the oldest expired candidate (due date, then age)
• Report rows show A/!/P/Q status and the single startup candidate
• Quarantines approved items before manual purge
• Keeps retention data local

Commands

• retention:init — initialize the manifest for the current project
• retention:report — show all tracked roots
• retention:confirm — quarantine the oldest expired candidate
• retention:restore — restore one quarantined item
• retention:purge — permanently delete one quarantined item
• retention:pin / retention:unpin — protect or release one item

Data files

• .pi/.pi-retention-project.yaml — project manifest (preferred)
• .pi-retention-project.yaml — legacy project manifest (still read when present)
• .pi-retention.yaml — per-root sidecar
• .pi-retention.jsonl — append-only usage log
• .pi-retention-trash/ — quarantine area

Install

Install the published npm package with Pi:

pi install npm:pi-retention

Pin a specific version when you want reproducible installs:

pi install npm:pi-retention@0.1.7

Install into the current project instead of your user Pi settings:

pi install npm:pi-retention -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-retention

Try it without permanently installing:

pi -e npm:pi-retention

Quick start

Try this package locally from a clone:

pi -e .

Then run:

/retention:report

On startup, Pi Retention checks the single oldest expired candidate and asks once before quarantine. Declining the prompt leaves the item active for the next launch.

Package contents

Published tarball includes:

Path	Purpose
extensions/	Pi TypeScript extension entrypoints
lib/	Shared TypeScript helpers
docs/	Supporting docs (examples.md, release.md)
README.md	Project entrypoint
ROADMAP.md	MVP scope and non-goals
CHANGELOG.md	Release history
LICENSE	MIT license

Development

npm install
npm run ci

npm run ci runs typecheck, tests, and npm run pack:check (npm pack --dry-run) to verify the published tarball contents before release.

Release

Before tagging, confirm package readiness:

npm run ci
npm run pack:check

Then bump and push:

npm version patch
git push

See docs/release.md for Trusted Publishing setup.

Docs

• docs/examples.md
• docs/release.md

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-retention
• GitHub: https://github.com/eiei114/pi-retention
• Issues: https://github.com/eiei114/pi-retention/issues
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md

License

MIT