Installing Dark Matter
docs/install.md · main
macOS 13 or later, Apple Silicon or Intel. One download covers both.
Download
https://dark-matter.ai/download — the page, with the version, the date it shipped, its size and its checksum. Its button is https://api.dark-matter.ai/download, which is one URL that is always the newest build: it redirects to the DMG in the releases bucket, and the bucket's own address changes during a rollback while this one does not. Link the API URL from anywhere that wants the bytes rather than the page.
Both hosts are live only once DNS moves. See
docs/ops/release.mdfor what is still on the Principal's list.
First launch
Open the DMG, drag Dark Matter to Applications, and open it from Finder. There is no Gatekeeper warning: the app is signed with a Developer ID certificate and notarized by Apple, and the notarization ticket is stapled to the DMG, so a Mac that has never seen it and is offline still opens it without complaint.
The first launch asks one question:
"Choose the repository your agents will work in." Pick a clone of the repository you want sessions to run against. The app cuts worktrees in a sibling directory of that clone — never inside it — so the tree you work in is never the tree an agent is writing to.
A folder that is not a git repository is refused, with the reason, and you are asked again. The
answer is kept in workspace.json (see below) and you are not asked a second time. To point the
app at a different repository, delete that file and reopen the app.
The repository the app is currently using is shown in Settings → This machine → Repository.
If Claude Code is not found
An app opened from Finder inherits launchd's environment, not your terminal's — which is why the
app asks your login shell for its PATH once at startup and uses that for everything it spawns. If
claude still is not found, it is installed somewhere your login shell does not put on PATH
either. Check with:
$SHELL -ilc 'which claude git'
If that finds nothing, the app will not find it either. Install Claude Code, or add its directory to your shell profile.
Where your data lives
| What | Where |
|---|---|
| The repository setting | ~/Library/Application Support/Dark Matter/workspace.json |
| Your model key and this machine's host credential | the same directory, each sealed by the macOS keychain |
| Agent worktrees | a sibling of your repository, never inside it |
| Logs | stdout, when started from a terminal; nothing is written to disk |
Nothing above leaves your machine. Model spend is on your own key or your own Claude Code seat (CLAUDE.md rules 3–5); the app holds no model credential of its own.
Updates
The app checks for an update when it starts and every six hours after that, and downloads a newer one in the background. When one is on disk, Update ready — restart appears on the bottom rail.
It never restarts on its own. Agent sessions are real processes writing to real worktrees, and an app that restarted itself would end one mid-run. Press the control when you are ready, or just quit normally — an update already downloaded installs on the next launch either way.
The updater reads a public static host and carries no credential. No token of any kind ships inside the app.
Uninstalling
Drag the app to the Trash and delete ~/Library/Application Support/Dark Matter. Worktrees the app
created sit beside your repository and are removed when their sessions end; anything left over is
an ordinary directory you can delete.