Ballast

Not legal advice. Not affiliated with, or endorsed by, any AI provider. Read SAFETY.md first.

Ballast is a set of plain-text instructions that your AI coding agent follows to find and clear the disk and memory leftovers that AI tools leave behind: Claude Code and Claude desktop (chat and Cowork), Codex, Gemini, Antigravity, local models (their files on disk, and the GPU memory (VRAM) they keep loaded), MCP servers, headless browsers, and the scratch projects agents create.

There is no program to install or run. The instructions are Markdown. The repo also holds one static dashboard page (HTML that runs only in your browser, makes no network requests, and cannot delete anything), a logo, the plugin's icon (a PNG picture), and the four small JSON files that let Claude Code and Codex install it as a plugin. Beyond that there are only repository settings files (issue forms, a pull request template, the release workflow, Dependabot and editor settings), none of which you run. Your own agent reads the instructions, runs read-only checks through its own tools, and asks you before every deletion.

What it does

1. Scans, read-only. Measures known AI leftovers, your Temp folder and the Recycle Bin, browser and Office caches, and finds large unknown folders. (It shows the Windows Installer cache so you can see where space goes, but never offers it.) For local AI it also reads GPU memory (dedicated VRAM, and the shared memory integrated graphics borrow from RAM) and which process holds it (catalog/gpu-memory.md). Nothing is changed.
2. Runs eight checks before judging (last used, in use now, is it a program, anything depends on it, unsaved work, cloud or shared, protected name, how to get it back). A folder is never classified from its name or date.
3. Sorts everything into tiers (below) and gives you a link to a dashboard by default, again after any cleanup, with the numbers: space freed, items cleared, skipped and failed. (A plugin install shows the same as a table in the chat: see Quick start.)
4. You choose Keep, Clear or Check first per item, then paste a message with your choices to your agent.
5. Asks again, per item, with the full path, before anything is deleted. Your choice selects; your approval authorises.
6. Deletes only what you approved, to the Recycle Bin or Trash where that really works, and logs what happened.
7. Never just says "I can't." If something is locked or needs admin rights, the agent explains why, asks for the permission it needs, and shows the workaround. See permissions.md.
8. Tells you how to stop it coming back.

The rule above all others: if the agent is unsure about anything, it asks you. It never decides for you.

What it never does

• Deletes personal files, anything named backup, credentials, browser profile data, git history, or AI memory files. These are the Red tier and cannot be selected. See catalog/_protected.md.
• Ships or runs installers, binaries or scripts.
• Sends file contents anywhere, or collects any data. See PRIVACY.md.
• Works around your agent's permission system, your operating system's protections, or your security software.
• Promises that your computer will be faster or that a deletion is "safe". Items are classified, and you decide.

Tiers

Tier	Meaning	Examples	In the dashboard
Green	Regenerable cache, no data loss	App caches, temp files, update downloads	Keep by default; you can choose Clear
Yellow	Regenerable at a cost, or an app is affected	Chat transcripts, node_modules, .venv, VM images, model files	Keep by default; the cost is shown
Grey	In use, unknown, or evidence incomplete	An item a server is running from	Keep or Check first, never Clear
Red	Personal or irreplaceable	Documents, backups, credentials, memory files, browser profiles	Shown, locked

Quick start

Pick one way in. Either way, pin a release: do not let an agent fetch and follow instructions from a live URL.

A. Claude Code plugin (one install, pinned to a release tag)

/plugin marketplace add chittychat-studio/Ballast#v0.1.4
/plugin install ballast@ballast

Then run /ballast:ballast. Leave plugin auto-update off and update on purpose. A plugin install does not run the checksum check below, so if you want that, use B.

The same folder is a Codex plugin: codex plugin marketplace add chittychat-studio/Ballast --ref v0.1.4, then open /plugins in Codex and install Ballast (notes).

The plugin is the plugin folder: the instructions and the catalog, and nothing else. It does not include the dashboard page, because Claude's plugin directory accepts only text and pictures from publishers it has not verified. A plugin install shows the same results as a table in the chat. For the page, use B.

B. Clone (works with any agent)

git clone --branch v0.1.4 https://github.com/chittychat-studio/Ballast.git

Each release has a checksum file and a build attestation, so you can check what you downloaded (how). Open your agent in the cloned folder and say: "Read AGENTS.md and run cleanup.md."

Then, either way:

1. Read cleanup.md and permissions.md yourself. They are short.
2. For a recurring check, say: "Run weekly.md." (Stay present: it never runs unattended.)

Example prompts

With the plugin installed, or with your agent open in the cloned folder, any of these starts Ballast. Each one begins with the version check and the two consent questions, and the scan is read-only.

This is the beginning of the README. Read the rest at the original. Read the full README ↗