Desktop and web

Invariant is one app that you open in three places: the desktop app, a browser tab on your own machine, and the hosted web workspace of your organisation. The screens and the flows are the same everywhere. What changes is where the project's files are.

Three ways to open it

The desktop app and the browser tab show the same thing. The app holds no data of its own: your sessions, reviews and settings live in your project folders, and the local service reads them.

The desktop app

The desktop app is a window around the local workspace. It installs and keeps up to date the invariant command, starts the local service, and opens your projects. It is published for macOS on Apple silicon; on other systems, open the same workspace in your browser. See Install the app for the download.

The first run

1. On Welcome to Invariant, keep Add the invariant command to my terminal ticked if you also want to use the command in a terminal. Your agents need it.
2. Press Get started. The app gets the local service ready.
3. On Open a folder, press Open folder… and pick a project.
4. If the folder is not an Invariant project yet, the app asks Set up Invariant in <folder>? It adds invariant.json, a .invariant/ folder and agent instruction files (AGENTS.md, CLAUDE.md). Nothing else changes. Press Set up, Choose another folder or Skip.

Later, open more projects with File › Open Folder… (⌘O), or from the hub with Add project. See Hub and projects.

The menus

• Invariant: Settings… (⌘,), Check for Updates…, Restart to Update once an update is ready, Install ‘invariant’ Command… (or Uninstall), and your sign-ins: Sign In…, Add an Organisation…, Sign Out of <organisation>….
• View: Workbench (⌘1) brings you back to the last page you had open, Reload (⌘R) and zoom.
• Help: Documentation, What's New, Show Logs and Report an Issue….

In the browser on Windows or Linux, read Ctrl for ⌘.

Desktop settings

Invariant › Settings… opens the app's own settings:

• Notifications: Show system notifications (on by default). While the app is in the background, something that waits on you also goes to the system's notification centre: a plan to approve, questions, a check-in, a mention or an assignment. Click it to bring the app forward. The item waits, unread, in the Inbox.
• Local service: Stop the local service when I quit Invariant is off by default, so agents in your terminals keep working after you quit the app.
• Terminal: what invariant ui opens: the app when it is installed, always the app, or always the browser.
• Updates: the version, Check for updates and Download updates automatically.
• Privacy: Share anonymous usage data. See Telemetry.

The workspace's own settings, such as themes and project options, are in the app itself. See Settings and themes.

Updates

The app, the invariant command and the workspace share one version and update together. The app checks shortly after it starts, then every 15 minutes.

• With Download updates automatically on, a new version downloads in the background. A card in the bottom-right corner of the window shows the download's progress, then says Restart to update, with Later and Restart now. If you close it, the update installs the next time you quit.
• With it off, the card says Update available, with Download. You choose when to restart.
• After the restart, a short note offers What's new.

The update card stays until you answer it. Its × hides that update until the next launch or until you check for updates yourself.

The local workspace in a browser

Run invariant ui in a terminal to start the local service and open the workspace. When the desktop app is installed, the command opens the app; otherwise it opens a browser tab at http://127.0.0.1:4200. Add --browser to get a tab even with the app installed.

The browser tab works exactly like the app. You can keep both open. Quitting the browser leaves the local service running; invariant ui stop stops it.

The web workspace

An organisation also has a hosted workspace at app.invariant.guru. You sign in there with your account, and it opens your organisation's hub: the same groups and projects you see on your machine. It is useful when you are away from the machine that holds the project, or for a teammate who only reads, answers and approves.

On the web, a project has no folder behind it. Its sessions, reviews, brain and inbox come from the organisation's servers, so some things work differently:

• Your changes go through a teammate's machine. When you answer a question, approve a plan or send it back on the web, the page shows Sent — waiting for a teammate's machine until a member's local service applies it. Assigning a session is instant.
• What needs the files is not there. The Packages and Settings pages, the brain's code map, worktrees, requesting a review and copying a line for an agent need the project's files. The web hides them.
• Notifications are yours. The Inbox of an organisation project is per person, on every machine and on the web.

For organisations, members and sign-in, see Teams and organisations.

How the app is laid out

The rail

The rail runs down the left edge. At the top, the brand mark leads to All projects, the hub. Under it, the project chip shows which project you are in; click it to switch. Then come the project's pages:

• Inbox: what waits on you. See Inbox and notifications.
• Sessions: the work, from task to summary. See Sessions.
• Reviews: independent reviews of a branch. See Reviews.
• Brain: the project's documentation and knowledge. See Brain.
• Packages: the skills and instructions installed for your agents. See Packages and skills.
• Usage: token usage of your agents.
• Settings: the project's settings. See Settings and themes.

A page that has something waiting on you shows a mark on its rail item. At the foot of the rail you find the page's guide, Report a problem, the command palette, your context avatar and a small dot that says whether the page is live.

Tabs

The strip across the top holds your tabs. A tab can show any page of any project, so one tab can hold a session of one project and the next the Reviews of another. Each tab keeps its own history: the ‹ and › before the strip go back and forward in that tab only.

• Press + at the end of the strip, or ⌥T, for a new tab on the sessions of the project you are in.
• ⌘-click or middle-click a row to open it in a new tab in the background.
• Drag a tab to reorder it. ⌥W closes a tab and ⌥⇧T reopens the last one you closed.
• ⌥[ and ⌥] move to the previous and next tab; ⌥1 to ⌥9 jump to a tab (9 is the last).

Your tabs survive a reload. Each window keeps its own set.

The page header

Every project page opens with the same header. On the left: the project switcher, the page title and the project path, which you can copy. On the right: the page's filter or search, its buttons, and its main action last, such as New session.

In an organisation project, the header also says when changes made on this machine are still waiting to sync, or when the organisation did not answer the last sync (Offline).

Contexts: this machine and organisations

A window shows one context at a time:

• This machine: your local projects. Free, no account.
• An organisation: its projects, groups and Pro features, after you sign in.

The avatar at the foot of the rail shows the context you are in: a machine glyph for This machine, or the organisation's initials. Press it to open its menu, switch context, add an organisation or sign out. Before you have signed in anywhere, it opens the sign-in screen, where Continue locally takes you back.

When you use two or more contexts, a narrow column appears to the left of the rail with one tile per context. Press a tile, or ⌃1 to ⌃9, to switch. A badge on a tile counts what waits on you there.

Switching context changes only what the window shows. An agent working in a terminal keeps working in its own project's context. See Teams and organisations.

The command palette

Press ⌘K to open the command palette. Type to search sessions, reviews and actions: new session, go to a page, request a review, approve a plan, copy the execute line, start an iteration, switch tab, and every settings section.

• ⌘P opens the palette on your projects, grouped as on the hub. Type a group's name to see its projects.
• Some actions open a narrower list, such as Switch project… or Move to a group…. ⌫ on an empty query goes back out; Esc closes the palette.
• Use ↑ ↓ to move and ↵ to run. ⌘↵ opens a page in a new tab.

Keyboard shortcuts

Every button that has a shortcut shows its key on the button. Press ? to open the shortcut sheet. It lists the keys of the page you are on first, then the keys that work everywhere, then every other page.

Keys that work on every project page:

Themes

The app comes in four themes: Indigo, Dark Indigo, Graphite and Paper. Choose one in Settings and themes.

From the terminal

invariant ui              # start the local service and open the app, or a browser tab
invariant ui --browser    # open a browser tab even when the app is installed
invariant ui status       # the local service and the projects it serves
invariant ui stop         # stop the local service

See the CLI overview for every command.