First run
docs/first-run.md · main
What happens the first time Dark Matter opens on a Mac, in the order it happens. Everything here is asked once and kept; nothing is asked twice.
Open it from Finder
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.
Choose the repository
Before the window opens, the app 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 Installing for where) 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. It is read-only there on purpose: the repository is a fact about this install, decided once, and the app never again infers it from where its own binary happens to live.
Sign in
The window opens on the sign-in: the war table with four ways in on its plate — GitHub, Google, a code sent to an email address, or a code sent to a phone number. Pick one and finish in your own browser. There is no password anywhere in this: every door is either a provider's own session or a one-time code, and the app never sees either.
Nobody asks you to create a workspace. The first sign-in opens an organization for you, named after you, while the browser round trip is still finishing; you land on the Floor inside it. Sign in with a second way later and it joins the same person, the same organization and the same board — one human, several doors. A second Mac signing in as you lands in the organization you already have.
Signing in on the website is the same person. The site and the app are two applications in one identity tenant, so the account you see in the web console is the account the app is signed into.
The app finds Claude Code
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. What the app looks for, and what it does with it, is on the Claude Code and Codex page.
What is kept, and where
| 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; the app holds no model credential of its own, and no token of any kind ships inside it.
Starting over
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. Reopening the app after that is a first run again.