{"id":50434544,"url":"https://github.com/forjd/pi-clean","last_synced_at":"2026-05-31T16:04:19.339Z","repository":{"id":352377766,"uuid":"1214918707","full_name":"forjd/pi-clean","owner":"forjd","description":"A cautious cleanup script for removing pi data, project-local .pi directories, and pi-managed global npm packages.","archived":false,"fork":false,"pushed_at":"2026-04-19T08:51:29.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T10:26:29.296Z","etag":null,"topics":["bash","cleanup","cli","developer-tools","pi"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forjd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T08:21:00.000Z","updated_at":"2026-04-19T08:51:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forjd/pi-clean","commit_stats":null,"previous_names":["forjd/pi-clean"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/forjd/pi-clean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fpi-clean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fpi-clean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fpi-clean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fpi-clean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forjd","download_url":"https://codeload.github.com/forjd/pi-clean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fpi-clean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33737717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","cleanup","cli","developer-tools","pi"],"created_at":"2026-05-31T16:04:18.614Z","updated_at":"2026-05-31T16:04:19.330Z","avatar_url":"https://github.com/forjd.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-clean\n\n[![CI](https://github.com/forjd/pi-clean/actions/workflows/ci.yml/badge.svg)](https://github.com/forjd/pi-clean/actions/workflows/ci.yml)\n[![Release Please](https://github.com/forjd/pi-clean/actions/workflows/release-please.yml/badge.svg)](https://github.com/forjd/pi-clean/actions/workflows/release-please.yml)\n[![Latest Release](https://img.shields.io/github/v/release/forjd/pi-clean)](https://github.com/forjd/pi-clean/releases)\n[![License: MIT](https://img.shields.io/github/license/forjd/pi-clean)](LICENSE)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196.svg)](https://www.conventionalcommits.org/en/v1.0.0/)\n\nA cautious cleanup script for removing pi data, project-local `.pi` directories, and pi-managed global npm packages.\n\n\u003e [!WARNING]\n\u003e This tool deletes files and uninstalls packages. Always run `--dry-run` first and review the plan before running it for real.\n\n## What it does\n\n`pi-clean.sh` can:\n\n- remove the active pi agent directory\n  - `PI_CODING_AGENT_DIR` if set\n  - otherwise `~/.pi/agent`\n- remove project-local `.pi` directories\n- remove custom `sessionDir` paths referenced by pi settings\n- uninstall global npm packages referenced by pi global settings\n- optionally uninstall the package that currently provides the `pi` executable\n\n## Safety model\n\nThe script is designed to remove **pi-managed data** without wandering into unrelated files.\n\nIt intentionally:\n\n- does **not** touch `~/.agents`\n- skips any path inside `.agents`\n- does **not** delete arbitrary local package source repos referenced from pi settings\n- skips git and URL package sources for npm uninstall discovery\n- prints a full plan before making changes\n\n## What it does not remove\n\nBy design, this script does **not** delete:\n\n- `~/.agents`\n- arbitrary local directories referenced as pi package sources\n- arbitrary git clones outside pi-managed directories\n- shell config entries like API keys in `~/.zshrc` or `~/.bashrc`\n\nIf you exported provider API keys in shell startup files, remove those manually.\n\n## Requirements\n\n- Bash\n- Python 3\n- Optional, for uninstalling global packages:\n  - `npm`, `pnpm`, or `yarn`\n\nThe scripts are tested against macOS' default Bash 3.2 and modern Linux Bash.\n\n## Install\n\n### One-line install\n\nInstall the latest release to `~/.local/bin/pi-clean`:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/pi-clean/main/install.sh | bash\n```\n\nWith `wget`:\n\n```bash\nwget -qO- https://raw.githubusercontent.com/forjd/pi-clean/main/install.sh | bash\n```\n\nInstall from `main` instead of the latest release:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/pi-clean/main/install.sh | bash -s -- --main\n```\n\nInstall a specific version:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/pi-clean/main/install.sh | bash -s -- --version v1.0.0\n```\n\n### Homebrew\n\n```bash\nbrew install forjd/tap/pi-clean\n```\n\nThe Homebrew tap is updated automatically when a new GitHub release is published.\n\n### After installing\n\n```bash\npi-clean --dry-run\n```\n\n## Uninstall the command\n\nIf you installed with the one-line installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/pi-clean/main/uninstall.sh | bash\n```\n\nOr with `wget`:\n\n```bash\nwget -qO- https://raw.githubusercontent.com/forjd/pi-clean/main/uninstall.sh | bash\n```\n\nIf you installed with Homebrew:\n\n```bash\nbrew uninstall pi-clean\n```\n\n## Usage\n\n```bash\n./pi-clean.sh --dry-run\n./pi-clean.sh --yes\n./pi-clean.sh --yes --uninstall-cli\n```\n\n### Options\n\n```text\n--uninstall-cli      Also uninstall any global package that provides the 'pi' executable\n--scan-root DIR      Also scan DIR for project-local .pi directories (repeatable)\n--no-default-scan    Do not automatically scan ~/Projects\n--agent-dir DIR      Override the pi agent dir to clean\n--dry-run            Show what would be removed, then exit\n--yes                Do not prompt for confirmation\n--verbose            Show extra details\n-h, --help           Show help\n```\n\n## Recommended workflow\n\n### 1. Preview everything\n\n```bash\n./pi-clean.sh --dry-run\n```\n\n### 2. Clean pi data and packages discovered from pi settings\n\n```bash\n./pi-clean.sh --yes\n```\n\n### 3. Also remove the `pi` CLI package\n\n```bash\n./pi-clean.sh --yes --uninstall-cli\n```\n\n## Examples\n\n### Scan extra roots\n\n```bash\n./pi-clean.sh --dry-run --scan-root ~/work --scan-root ~/src\n```\n\n### Clean a custom agent dir\n\n```bash\n./pi-clean.sh --yes --agent-dir ~/custom/pi-agent\n```\n\n### Use only explicit scan roots\n\n```bash\n./pi-clean.sh --dry-run --no-default-scan --scan-root ~/code\n```\n\n## How global package discovery works\n\n### Packages from pi settings\n\nThe script reads the active pi global settings file and extracts npm package names from the `packages` array.\n\nIt will consider entries like:\n\n- `npm:@scope/pkg@1.2.3` → `@scope/pkg`\n- `plain-package-name` → `plain-package-name`\n\nIt skips entries that are clearly not global npm packages, such as:\n\n- `git:...`\n- `https://...`\n- `ssh://...`\n- local paths like `./something` or `/abs/path`\n\n### CLI package detection\n\nWith `--uninstall-cli`, the script scans global package roots and looks for a package whose `package.json` exposes a `bin.pi` entry.\n\nThat avoids hardcoding a single package name.\n\n## Conventional commits\n\nThis repo enforces Conventional Commits in pull requests:\n\n- commit messages are linted with `commitlint`\n- pull request titles must also be semantic\n\nExamples:\n\n- `feat: add npmCommand-aware uninstall detection`\n- `fix: preserve .agents paths during cleanup`\n- `docs: clarify what local package sources are skipped`\n- `chore: update CI workflow`\n\nIf you use squash merges, make sure the PR title is also a valid conventional commit, since that title often becomes the final commit message on `main`.\n\n## Releases\n\nThis repo uses Release Please.\n\nOn pushes to `main`, Release Please will:\n\n- inspect conventional commits\n- open or update a release PR\n- generate changelog entries\n- create a GitHub release after the release PR is merged\n\nSeparate workflows then:\n\n- upload these release assets:\n  - `pi-clean.sh`\n  - `install.sh`\n  - `uninstall.sh`\n  - `SHA256SUMS`\n- update the Homebrew formula in `forjd/homebrew-tap`\n\nIn practice:\n\n- `feat:` usually triggers a minor release\n- `fix:` usually triggers a patch release\n- `feat!:` or a `BREAKING CHANGE:` footer triggers a major release\n\n## Development\n\n### Lint\n\n```bash\nmake lint\n```\n\n### Test\n\n```bash\nmake test\n```\n\n### Full local check\n\n```bash\nmake check\n```\n\n## CI\n\nGitHub Actions runs:\n\n- `bash -n`\n- `shellcheck`\n- integration tests with Bats\n- conventional commit checks for pull requests\n- Release Please on `main`\n\non both:\n\n- Ubuntu\n- macOS\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fpi-clean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforjd%2Fpi-clean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fpi-clean/lists"}