Using Catalyst.

Getting started

Install it, then ask for a checkup. Doctor only reads, so this is safe on any machine.

Type catalyst on its own for the list, or kit for short: the installer adds it as a second name, unless something else on your machine is already called kit. The first time, it asks what to call you and offers the helpers worth having. After that it greets you by name, with your health score and a dot that breathes in its colour.

The list and its keys

The list opens on your terminal's separate screen, the way less and vim do, so nothing piles up in your scrollback, and leaving puts your terminal back as it was. There is nothing to type: arrows move and Enter opens.

Every result is something you can act on. Rows you can rest on get a highlight, and the keys at the bottom change with the row. These are the ones you will see:

↑ ↓

Move between rows. On a long result, the arrows move the cursor and the view follows.

⏎

Open what is highlighted: a command, the guide for a finding, the details of a port, the inside of a folder.

Esc

Back to the screen you came from. If what you did there changed something, that screen measures again.

o

Show it in Finder, or open its folder on Linux.

y

Copy it: a path, a command, a public key.

e

Open the file in your editor, at the right line when VS Code is there.

f

Let Catalyst make the change. It is shown first and waits for your yes.

r

Measure again.

l

Keep measuring, every two seconds, on Status and Battery.

Ctrl-C twice

Leave. The first press only warns.

Doctor and its guides

Doctor runs every check at once and usually finishes in a second or two. Before that, it asks your shell what a new terminal actually sees, since the environment a program starts in is rarely the same.

Your shell

Syntax errors in startup files, new-shell time and what is causing it, dead, repeated or relative PATH folders, Apple's tools ahead of Homebrew's.

Your tools

Anything that resolves but fails to run, Command Line Tools or a compiler, git identity, pip3 and python3 disagreeing, Apple's own Python, npm hiding from nvm, npm owned by root, a broken JAVA_HOME, Intel Homebrew on Apple silicon.

Keys and secrets

Private keys other users can read, found by content and not by name, weak keys, API keys in shell history, the firewall.

This machine

Disk space and inodes, heavy swapping, leftover Docker containers and images, startup items whose program is gone, failed systemd units, a restart waiting, oversized logs and caches.

The score runs from 0 to 100 and falls with each issue, more for serious ones. It is saved once a day, which is how it can say "up 3 since Tuesday". Skipped checks do not count. A check that could not run says so, and is never counted as a pass.

Guides. In the list, move to any finding and press Enter. The guide says why it matters, where it lives on your machine (the real file and line), and the steps. When Homebrew is behind Apple's tools, it traces a new shell and names the exact line that put it there. Keys let you edit that line, copy the command, open the right Settings page, or let Catalyst fix it.

Fixes. catalyst doctor --fix goes through what it can change, one at a time. Each shows the exact change and waits for your yes. A startup file is copied first, zsh checks the result, and Undo puts it back. When something needs admin rights, sudo asks for your password on your terminal: Catalyst never sees it.

Sweep

Sweep looks through your project folders for build artifacts and developer caches. It does not clean the system or other apps. A folder has to pass four tests before it is offered:

1. A marker proves what it is. A target needs a Cargo.toml or pom.xml beside it. A venv needs a pyvenv.cfg inside it.
2. It is a real folder, and not a symlink to somewhere else.
3. Git clears it. Inside a repository, git must say the folder is ignored and that it tracks nothing in it. If git cannot answer, the folder is left alone. Common names like build and dist always need this.
4. You are not working on it. The project must have been idle for 14 days, going by git and by your source files, including edits you never staged.

Only what rebuilds by itself starts ticked. Anything needing a reinstall is your choice, and the menu says how to get it back. With --yes, only what rebuilds by itself is taken unless you also pass --all.

Clean

Clean takes app caches and old logs, which apps make again when they need them. An app's cache is only offered while the app is closed, and Apple's own caches are left to macOS. Each row shows its path, o opens it in Finder, and everything goes to the Trash first.

Moving to the Trash frees nothing until it is emptied, so Clean offers to empty just what it moved, as a last step that says plainly it is final.

Space and System Data

Space shows where your storage goes, biggest first, with what macOS counts as itself. Press Enter on any folder to look inside it, and on macOS for what each of its parts is.

macOS in your storage settings is the sealed system, the boot files, recovery, and swap with the sleep image. None of it can be cleared, and no tool should try. Swap shrinks by itself when you quit big apps or restart.

System Data is mostly your own apps' data: caches, virtual machines, models and logs. catalyst system shows each area with a warning first, and lets you choose only what has a supported way out:

• To the Trash, where Undo can bring it back, such as Xcode's build data or an old macOS installer.
• The app's own command, such as colima delete, shown first and run as you.
• The right Settings page, such as Wallpaper for downloaded aerials, where you make the change.
• A system command, such as removing Time Machine's local snapshots, which sudo asks you to approve with your password.

The system's own areas, its logs, temporary files and downloaded assets are measured, explained and locked. --admin measures the folders only an admin can read, again through sudo's own prompt.

Helpers

Helpers are well-known tools that let Catalyst see more. None is required. The first run offers them once, a no is remembered, and they wait under More, Helpers. Uninstalling Catalyst never removes them.

Homebrew

Installs the other helpers. Its own installer from brew.sh, shown in full and run only on your yes. It asks for your password itself.

smartmontools

Lets Disk show drive wear, total read and written, spare cells, temperature and power-on hours.

Undo and log

Every change goes in a journal. catalyst undo reverses the last group of changes, moving folders back out of the Trash, restoring permissions, and putting an edited startup file back as it was. It will not overwrite anything new at the old location. Some changes, like pruning Docker images, cannot be undone: those say so before they run, and appear in catalyst log all the same.

Command reference

Scripts and CI

doctor, sweep, clean, space, system, status, disk, battery, ports, startup and ssh all take --json. Without a person at a terminal, questions are answered no, unless you pass --yes.

Exit 0

Fine.

Exit 1

Issues found. Notes do not count.

Exit 2

Usage error.

Exit 3

A check could not run.

Kit and settings

Kit and colour are only for a person at a terminal. They switch off by themselves in pipes, in CI, with NO_COLOR and in narrow windows.

Settings in the list (under More) change your name, Kit, and animations: Kit's wag and the health dot's breathing. The same from a shell:

Catalyst keeps its history in ~/.local/state/catalyst and its settings in ~/.config/catalyst.

Privacy and safety

• Nothing is sent anywhere. No telemetry, no accounts, no backend. Network calls happen only when you ask: catalyst net, a speed test, your public IP, and catalyst update.
• Your password stays yours. When something needs admin rights, sudo asks for it on your terminal. Catalyst never reads it, never keeps it, and if your password changes, sudo simply asks again.
• Secrets are counted, never shown. The history check says how many lines, and --json follows the same rule.
• Removals go to the Trash, by rename only. Nothing is copied or deleted, so a failure leaves the original where it was.
• No downloaded code. Nothing it runs or writes comes from the internet, except Homebrew's own installer, shown in full and run only on your yes from Helpers.

The full text: privacy and terms. Found a security problem? Report it privately.

The old Mac app

Catalyst used to be a macOS app. It is retired and no longer maintained, and this tool replaces it. The doctor and sweeper carried over, rebuilt to be safer. The pip, Homebrew and virtual environment screens did not, because those tools already do that job well, and Catalyst now diagnoses them instead. It also runs on Linux now.

If you used the app, this shows what it left behind (its shell line, the password it saved in your Keychain, its helper tool) and removes each one only when you say yes:

The app's policies are still here: privacy and terms.