---
slug: "pi-cleanup"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/crayonlu/pi-cleanup@master/README.md"
repo: "https://github.com/crayonlu/pi-cleanup"
source_file: "README.md"
branch: "master"
---
# pi-cleanup

A manual janitor for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) that removes `~/.pi` cruft [`pi-delete-session`](https://github.com/wpbasket/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

From npm (recommended — appears in the [package gallery](https://pi.dev/packages)):

```bash
pi install npm:pi-cleanup
```

Or from git:

```bash
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`:

```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