SkillAgentSearch skills...

poo

Find and safely free the disk space your dev work eats: builds, caches, simulators and agent worktrees. macOS menu bar app, CLI and MCP server.

Install / Use

claude mcp add morajabi -- npx -y github:morajabi/poo

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

79/100

Supported Platforms

Claude Code
Claude Desktop
OpenAI Codex

Our assessment of poo

poo scores 79/100 on our quality scale, 3683rd of 4,705 Development & Engineering skills we index.

Its MCP Server is 13 KB long, well organised into 15 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

It has 50 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
7/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated today, so poo is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

poo compared with similar skills

All 4 of these similar skills score higher than poo; compare them before choosing.

SkillScoreStarsUpdatedFormat
poo (this skill)by morajabi7950todayMCP Server
taste-skillby Leonxlnx100117.0k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.4k9d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.md

Frequently asked questions

How do I install poo?
Run claude mcp add morajabi -- npx -y github:morajabi/poo. The install tabs above show the steps for each supported agent.
Which AI agents does poo work with?
It is written for Claude Code, Claude Desktop and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
Is poo safe to use?
It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is poo still maintained?
The repository was last updated today, so poo is actively maintained.
<p align="center"> <img src="docs/images/icon.png" alt="Poo" width="128"> </p> <h1 align="center">Poo</h1> <p align="center"> Find and safely free the disk space your dev work eats. <br> A menu bar app and CLI for macOS, with an MCP server and skill for your coding agent. </p> <p align="center"> <a href="https://poo.morajabi.com">Website</a> · <a href="https://github.com/morajabi/poo/releases/latest/download/Poo.app.zip">Download</a> · <a href="#install">Install</a> · <a href="docs/mods.md">Rules and mods</a> · <a href="CONTRIBUTING.md">Contributing</a> </p> <p align="center"> <a href="https://github.com/morajabi/poo/releases/latest"><img src="https://img.shields.io/github/v/release/morajabi/poo?sort=semver&label=release" alt="Latest release"></a> <a href="https://github.com/morajabi/poo/actions/workflows/ci.yml"><img src="https://github.com/morajabi/poo/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a> <a href="#install"><img src="https://img.shields.io/badge/macOS-15%2B-black?logo=apple" alt="macOS 15+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a> </p> <p align="center"> <img src="docs/images/overview.png" alt="The Poo window: free space, and what is not in use grouped by what a clean costs you" width="100%"> </p> <p align="center"> <img src="docs/images/menubar-expanded.png" alt="The menu bar panel: free space, one Clean button, the areas behind it" width="49%"> <img src="docs/images/cli-overview.png" alt="The poo terminal UI overview" width="49%"> </p>

Install

App: download Poo.app, unzip it and move it to Applications. macOS 15 or later, Apple silicon or Intel. Signed and notarized by Apple.

CLI:

curl -fsSL poo.morajabi.com/install | sh

Installs poo into ~/.local/bin (sha256-verified). Add POO_APP=1 before sh to install Poo.app too. Already have the app? Use Poo › Install Command-Line Tool instead: it links the app's own CLI, which updates with the app. The CLI also runs on Linux.

<details> <summary>Direct downloads</summary>

These links always point at the latest release.

| | | |---|---| | Poo.app (universal, CLI included) | Poo.app.zip | | CLI, macOS Apple silicon | poo-aarch64-apple-darwin.tar.gz | | CLI, macOS Intel | poo-x86_64-apple-darwin.tar.gz | | CLI, Linux x86_64 | poo-x86_64-unknown-linux-gnu.tar.gz | | CLI, Linux arm64 | poo-aarch64-unknown-linux-gnu.tar.gz | | Checksums | SHA256SUMS |

</details>

Updates are automatic. The app checks daily and installs updates through Sparkle when it's idle (or Poo › Check for Updates). The script-installed CLI updates itself in the background once a day; poo update updates now, and poo config set updates.auto false turns that into a one-line hint.

Quick start

  • App: open Poo. Setup takes about a minute: confirm the folders that hold your projects, optionally grant Full Disk Access, and choose whether to run nightly cleanups. Then press Clean in the menu bar, review the list, and confirm.

  • CLI: run poo setup to pick your dev folders, then poo for the interactive view. Or step by step:

    poo plan stale              # preview what nothing is using
    poo clean --plan stale      # clean it, after you confirm
    
  • Agent: run poo integration install all, then ask your agent to "set up poo for me with poo setup --agent".

Safety and privacy

  • Nothing is deleted until you review and confirm it, or turn on a schedule or hook yourself. Plans never include anything running, anything that needs a look, or anything protected.
  • Worktrees are backed up before removal: small ignored files (.env, Local.xcconfig) are copied aside, uncommitted work is stashed, and detached commits are saved to a branch. poo backups lists and restores them.
  • Full Disk Access is optional. It is one switch in System Settings. Without it, poo skips the folders macOS guards and says so once, instead of prompting folder by folder.
  • No account, no telemetry. The only network calls are update checks to GitHub, and sharing a rule when you ask for it.

Under the hood, poo never deletes outside your home and temp folders (or a rule's declared system path), never deletes through a symlink, never touches .ssh, .gnupg, Keychains or iCloud Drive, and never deletes a build folder that contains .git. Right before deleting it re-checks each item against its rule and skips projects where a build or coding agent is running. Worktrees are removed with git worktree remove and keep their branch. Every clean is logged (poo history).

What it finds

Most cleaners stop at global caches. On a developer Mac the real growth is elsewhere:

  • every worktree (yours, Claude Code's, Codex's, Conductor's) gets its own Rust target, SwiftPM .build, Xcode DerivedData, node_modules and dist, duplicated per checkout;
  • agents pass -derivedDataPath and CARGO_TARGET_DIR into folders nobody cleans;
  • merged worktrees, old simulators and runtimes, superseded toolchains and agent CLI versions pile up.

poo walks your dev folders and agent worktree homes, maps DerivedData back to its checkout, checks each worktree for uncommitted work and whether it landed, and labels every item by how much regret cleaning it causes. It also covers the usual ground: app, browser and system caches, logs, temp, installers, Docker and Homebrew.

| | | |---|---| | Browse every item, with why it is there and what cleaning it costs | Elsewhere on This Mac: snapshots, purgeable space and device backups Poo explains but leaves alone | | Cleaning progress with a running total and Stop | After a clean: freed space and what was backed up |

Features

Tiers and plans

Every item gets a tier. Plans (quick, stale shown as "not in use", deep, emergency) clean up to a tier, so you pick how much rebuilding you accept.

| tier | meaning | cleaned by plans | |---|---|---| | junk | nothing to rebuild: logs, temp, crash reports, broken simulators | quick, not in use, deep, emergency | | cold | unused for days, orphaned (project gone), or its worktree's commits already landed | not in use, deep, emergency | | idle | builds of checkouts other than your 2 newest per repo, untouched for hours | not in use, deep, emergency | | warm | in active use: recent, or an agent, editor or shell is open in that checkout | deep, emergency | | hot | a build or the owning app is running, or touched in the last hour | never | | review | needs a human look: unknown ignored folders, worktrees with uncommitted work | never | | protected | data, Docker volumes, projects you protected | never |

Mark projects active, stale or protected with poo projects set. Tune scan.keep_recent_checkouts and scan.idle_hours to how many checkouts you build at once. --include-in-use also cleans things in use (worktrees with uncommitted work are stashed first); --dangerously-include-protected goes further and asks you to confirm.

Routine cleanups

poo schedule add nightly    # 03:30 every night: clean what nothing is using
poo schedule add guard      # below 20 GB free, clean what is not in use until 50 GB are free

A launchd agent wakes poo every 15 minutes. Due schedules rescan first, notify you, and log to poo schedule log.

Agent hooks (opt-in)

poo hooks install all makes Claude Code and Codex clean a worktree's build output when an agent finishes there and its work already landed in main. Nothing is installed by default.

Fast, current numbers

The first scan walks everything (5 to 20 seconds with a warm disk cache). After that poo keeps an index and reads the macOS file-change journal (FSEvents), so only folders that changed are measured again. poo scan --full walks everything; poo watch keeps the report live while the app is open.

CLI

Run bare, poo opens an interactive terminal UI. Piped, every command prints JSON (--text forces tables).

<p align="center"> <img src="docs/images/cli-browse.png" alt="poo terminal UI browse view" width="49%"> <img src="docs/images/cli-clean.png" alt="poo cleaning in the terminal" width="49%"> </p>
poo                         interactive terminal UI (plain overview when piped or with --text)
poo scan [--full]           update the report (incremental unless --full)
poo ls [bucket] [--tier cold] [--project PATH] [--min 1G] [-q text]
poo show <id|path>          why it is there, what it costs to rebuild, what is inside
poo plan stale              preview a plan (quick, stale, deep, emergency)
poo clean <id>... | --plan stale [--dry-run] [--trash] [--yes]
poo free 30G                least-regret items until 30 GB are free
poo growth [--since 7d]     what grew, and when the disk fills at this rate
poo projects | poo worktrees
poo suggest                 big folders no rule explains yet, with draft rules
poo rules explain <path>    which rule matches and why
poo schedule | poo backups | poo history | poo update | poo doctor
<p align="center"> <img src="docs/images/cli-plan.png" alt="poo plan stale: what nothing is using, with size, status and last use" width="100%"> </p>

poo --help lists everything. Errors are {"error":{"kind","message","hint"}} with stable exit codes: 2 usage, 3 not found, 5 needs approval, 6 partial failure, 7 update failed, 8 invalid config or mods, 9 busy.

For coding agents

poo integration install all                  # skill + MCP for Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Windsurf, Claude desktop
npx skills add morajabi/poo --skill poo -g   # skill only, via the open skills CLI

The MCP server (poo mcp) gives agents tools to see the overview, list and inspect items, preview plans, clean (dry run by default), explain paths and configure poo. Agents may clean up to the tier you allow (poo config set agents.auto_clean_max_tier cold, the default); anything above needs your approval.

poo setup --agent prints a brief with your disk, projects, duplication across worktrees and the questions worth asking you, so an agent can tailor poo to your workflow.

Configuration and mods

Settings live in ~/.config/poo/config.toml (poo config keys lists them). Everything poo knows is a built-in mod in the same TOML format you can write: about 650 rules and 96 project stacks, covering

  • Apple: DerivedData (including custom -derivedDataPath folders), simulators and runtimes, device support, previews, SwiftPM, CocoaPods, Carthage, Tuist.
  • JS and Python: npm, pnpm, Yarn, Bun, Deno, Next, Vite, Turbo, Nx, Expo, Playwright; pip, uv, Poetry, conda, pyenv, Jupyter, Hugging Face and torch models.
  • Systems and JVM: Rust, Go, Zig, C/C++, Bazel, Nix, Gradle, Maven, Android SDK and emulators.
  • More: Ruby, PHP, Elixir, Haskell, .NET, Flutter, embedded toolchains and more.
  • Infra: Docker, OrbStack, Colima, Podman, Lima, UTM, Terraform and cloud CLIs.
  • AI: worktrees and caches of Claude Code, Codex, Cursor, Conductor and other agent tools, plus Ollama, LM Studio and other local model stores.
  • macOS: app, browser and

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars50
CategoryDevelopment
Updated14h ago
Forks1

Languages

Rust

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions