Troubleshooting

Most issues fall into a few buckets. If yours isn't here, everything Excellent does is a row in a file you own — so nothing is ever truly stuck.

The app won't open on macOS ("unidentified developer")

Early-access desktop builds aren't yet signed by Apple. Open System Settings → Privacy & Security, find the blocked-app notice near the bottom, and click Open Anyway. You only do this once.

The workspace won't load / port 3000 is busy

Running from source, the shell serves on http://localhost:3000. If another process already holds that port, stop it (or free the port) and run pnpm dev again.

Changes to the schema don't show up

Migrations run once, on the first database call, and are idempotent. After a change that touches the schema, restart the app so they apply. If a source build behaves oddly right after an update, clear the Next build cache (.next) and restart the dev server.

An agent seems stuck

Every agent runs under a budget and a per-role lock, so at most one worker per role runs at a time. Check the fleet with:

excellent-mcp agent status

Claims left behind by a session that ended are released automatically after a while; to clear them now, run excellent-mcp agent reap-claims.

Start completely fresh

Your entire workspace is the folder ~/.excellent/. To reset, quit Excellent and remove it:

rm -rf ~/.excellent

This permanently deletes your local database — there's no copy anywhere else, so export first if you want to keep anything. To experiment without touching your real data, set EXCELLENT_DATA_DIR to a scratch folder instead.