Install & run

Excellent runs entirely on your own machine. There are two ways to run it, and both keep your operation in one local file you own.

Excellent is in early access. The desktop app is going out to the waitlist in batches — join it here — so exact download steps arrive with your invite. This page describes how starting up works.

The desktop app

The simplest way to run Excellent is the native desktop app. It bundles everything — the shell, the database, and the agent runtime — and starts it all locally when you launch it. No account, no sign-in.

• Requirements: macOS 13 or newer on Apple Silicon. (Windows and Linux are on the way.)
• Install: download the .dmg from your invite, drag Excellent into Applications, and open it.
• First open: early-access builds aren't yet signed by Apple, so macOS may warn about an "unidentified developer." Open System Settings → Privacy & Security and click Open Anyway once — after that it launches normally.
• Updates: the app checks for and installs new builds in the background.

Run from source

Excellent also runs from its source. This is the path for developers and for operating it headless.

pnpm install
pnpm dev

• Prerequisites: Node 20+ and pnpm 9+.
• pnpm dev boots the shell at http://localhost:3000.
• The first launch creates your database and walks you through a short onboarding wizard.

Where your data lives

Everything is a single SQLite file at ~/.excellent/data.db (with its write-ahead-log sidecars), on your machine. Nothing is uploaded. When running from source, restart the app after any change that touches the schema — migrations are idempotent and apply on the first database call.

First run

On first launch Excellent creates your workspace and walks you through onboarding: your info, your workspace, and — optionally — connecting your tools and an agent CLI. Only a couple of steps are required; the rest you can skip and come back to. When you finish, Excellent kicks off one small, real piece of agent work so you can watch the system operate.

Back up and export

• Your database is a plain file — copy the ~/.excellent/ folder to back it up.
• For a portable snapshot, use Settings → Advanced → Data & residency → Download portable export, which writes your whole workspace to a single JSON bundle. The same export is available to agents via the workspace_export tool.

Start fresh

To reset completely, quit Excellent and remove ~/.excellent/. That permanently deletes your local data — there's no copy anywhere else, so export first if you want to keep anything. To experiment against a throwaway database without touching your real one, point the EXCELLENT_DATA_DIR environment variable at a scratch folder.

Next: hand work to agents in the app, or operate the whole thing from your terminal.