[ docs · guides ]

The desktop app

The desktop app is the supervision surface for Grist: every thread you run, in one window — what it's doing, what it changed, what it cost, and what it needs from you. Download it for macOS from the landing page; it updates itself after that.

Threads sidebar

Sessions are threads, grouped by project, newest activity first. Each row shows the thread's status — running, succeeded, failed, interrupted — with an unread marker when a thread finished while you were looking elsewhere, a badge when it's waiting on you, a marker for threads running in a worktree, and the thread's total cost. Running threads sort to the top, so the work that needs eyes finds you.

Worktree per thread

A new thread can run in its own git worktree, on a branch named for the task (grist/<task-slug>-<id>). Parallel threads then edit in parallel without fighting over the same files, and merging one branch leaves the others untouched. When every thread in a worktree has been archived, the worktree is cleaned up — but a dirty worktree is never force-removed; it's reported and left for you.

Review pane

Every change is reviewable before it lands. The pane shows diffs three ways — working tree, branch, or a single turn — and turns line comments into steering messages the thread acts on. Accept or revert individual hunks, then commit from the pane when the change reads right.

Automations

Recurring work runs as scheduled threads. Two ship built in: a daily failure-mining digest and a weekly memory-curation run. Automations behave like any other thread — same worktree isolation, same cost tracking — with one rule that has no exceptions: nothing an automation produces merges itself. Its output lands in the review queue for a human to accept.

Review queue — “Needs review”

Under the sidebar sits the queue: threads waiting on an approval, threads that failed, threads that were interrupted, and threads that simply finished unreviewed — in that order. Automation runs are labeled with the automation that spawned them, so machine-started work is never mistaken for yours.

Memory and code map, on Home

Home also carries the two Grist surfaces: a memory browser — search what Grist remembers about the current project and forget any record — and a code-map card showing the project's graph size and its most-connected landmarks.

Settings, deliberately small

Settings offers Grist account sign-in — the website device flow, or paste an API key — and that's the whole account surface. There are no provider pickers and no model pickers: the gate decides the rung, and your provider key is attached once, at the gateway.