pi-cleanup

Manual janitor for ~/.pi cruft: DS_Store, dead context-mode stats-pid files, empty session dirs, idle sessions, and stale subagent run-N artifacts. Complements pi-delete-session.

Packages

Package details

extension

Install pi-cleanup from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-cleanup
Package
pi-cleanup
Version
0.1.0
Published
Jul 18, 2026
Downloads
125/mo · 125/wk
Author
crayoooon
License
MIT
Types
extension
Size
17 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/cleanup.ts"
  ]
}

Security note

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

README

pi-cleanup

A manual janitor for the Pi coding agent that removes ~/.pi cruft pi-delete-session does not cover.

/cleanup scans, shows a categorized dry-run report, and deletes only after you confirm.

What it cleans

Category Rule
.DS_Store All under ~/.pi (regenerable)
context-mode dead stats-pid-*.json PID no longer alive — ESRCH only, never EPERM (so PID 1 and foreign-owner PIDs are kept)
empty session dirs Top-level ~/.pi/agent/sessions/<project>/ with zero entries
idle sessions Session .jsonl + sibling artifact dir whose last activity (mtime) is older than 14 days
stale subagent run-N/ run-N dirs older than 7 days, excluding those under idle sessions (removed with the session)

What it never touches

  • npm/node_modules, .git, git-installed packages
  • the intercom broker (broker.pid / broker.sock)
  • the current session and its sibling artifact dir
  • context-mode FTS5 *.db / *.db-wal / *.db-shm — use ctx_purge for those
  • run-history.jsonl

Install

pi install git:github.com/crayonlu/pi-cleanup

Then /reload in Pi, and run:

/cleanup

Safety

  • Dry-run first. /cleanup builds a report and asks for confirmation before deleting anything.
  • Self-test on every run. Asserts the liveness probe semantics (ESRCH = dead, EPERM = alive) before scanning, so PID reuse and unsignalable system PIDs can't cause false deletions.
  • Non-interactive = report only. When there's no TUI (print/JSON mode), it prints the report and deletes nothing.

Configuration

Age thresholds are constants at the top of extensions/cleanup.ts:

const IDLE_AGE_MS = 14 * DAY_MS;   // sessions idle longer than this are flagged
const STALE_AGE_MS = 7 * DAY_MS;   // subagent run-N dirs older than this are flagged

License

MIT