DreamCleanr

Install

Three install methods, pick what fits your setup:

Curl one-liner (recommended)

curl -fsSL https://dreamcleanr.jonlynchfinancial.com/install.sh | bash

macOS .pkg — double-click installer

open https://github.com/jlsport18/DreamCleanr/releases/latest

pipx + GitHub release

pipx install https://github.com/jlsport18/DreamCleanr/releases/download/v0.3.5/dreamcleanr-0.3.5-py3-none-any.whl

First run

The default operation is scan: read-only inspection that produces a report without changing anything on disk.

dreamcleanr scan

To preview a clean (still no changes — dry-run is the default for clean):

dreamcleanr clean

To actually apply cleanup:

dreamcleanr clean --apply

Reports render as HTML at ~/Library/Logs/DreamCleanr/reports/.

Scheduled cleanup (LaunchAgent)

DreamCleanr can run as a daily background job via macOS launchd:

dreamcleanr schedule install
# verify
launchctl list | grep dreamcleanr

By default the LaunchAgent runs daily at 3:30am with --mode=balanced. To remove:

dreamcleanr schedule uninstall

To customize cadence, edit ~/Library/LaunchAgents/com.jlfg.dreamcleanr.plist and reload with launchctl unload + launchctl load.

Scope & mode flags

--scope picks which subsystems to inspect:

• --scope=all — processes + storage (default)
• --scope=processes — only running-process triage
• --scope=storage — only disk / cache analysis

--mode controls how aggressive cleanup gets:

• --mode=safe — caches only, never user data
• --mode=balanced — caches + Docker leftovers + DerivedData (default)
• --mode=max — also clears HuggingFace + Ollama models (irreversible re-download)

MCP server

DreamCleanr ships an MCP (Model Context Protocol) server so AI agents — Claude Desktop, Codex, VS Code Copilot, Cline — can scan and preview cleanup without exposing destructive operations.

The MCP server is preview-first: tools that read state are exposed by default; tools that apply changes require explicit consent in your client config.

Start it manually to verify it imports correctly:

python3 -m dreamcleanr.mcp_server

If that command starts the server without errors, the client configs below have the right shape.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dreamcleanr": {
      "command": "python3",
      "args": ["-m", "dreamcleanr.mcp_server"]
    }
  }
}

Restart Claude Desktop. Verify by asking Claude: "Can you run a DreamCleanr scan?"

Codex (OpenAI Codex CLI)

Edit ~/.codex/config.toml:

[mcp_servers.dreamcleanr]
command = "python3"
args = ["-m", "dreamcleanr.mcp_server"]

VS Code (Cline / Copilot Chat)

Open the Cline / Copilot MCP settings UI and add:

{
  "mcpServers": {
    "dreamcleanr": {
      "command": "python3",
      "args": ["-m", "dreamcleanr.mcp_server"]
    }
  }
}

Safety model

DreamCleanr is designed to be hard to misuse. Three safety layers:

1. Dry-run by default. clean without --apply only reports what would happen.
2. Protected paths refuse to be touched regardless of mode — Documents, Desktop, Photos, Music libraries, mail stores, application bundles, system frameworks.
3. MCP exposes read-only tools by default — even an AI agent that's been given DreamCleanr access cannot apply changes without user-level consent in client config.

If a path matters to you and isn't in PROTECTED_PATHS, file an issue at github.com/jlsport18/DreamCleanr/issues and we'll add it.

Troubleshooting

• command not found: dreamcleanr — the curl install puts the binary in ~/.local/bin; ensure that's in your PATH. Run echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc.
• FileNotFoundError on Docker — fixed in v0.3.5. dreamcleanr --version should print 0.3.5 or later. If not, re-run the curl install.
• LaunchAgent not running — check ~/Library/Logs/DreamCleanr/launchd.log. Common cause: outdated path to dreamcleanr binary; re-install + re-schedule.
• MCP client says server failed to start — run python3 -m dreamcleanr.mcp_server in your terminal first; you'll see the import error directly. Usually means Python < 3.10 or stale install.