How it fits together

Invariant has four parts: the app you look at, a local service on your computer, the invariant command your agent calls, and, for teams, the organisation backend.

The parts

Part	What it does	Where it runs
The app	Shows your projects, sessions, reviews, Brain and packages; it is where you approve plans and triage reviews	The desktop app, a browser tab on your machine, or the web workspace
The local service	Serves the workspace, watches each project's files and keeps every open page up to date	One per computer, at `http://127.0.0.1:4200`
The `invariant` command	What your agent calls to read a session and report on it; it also installs packages and runs the local service	Your terminal, on the same computer
The organisation backend	Accounts, organisations, members, project groups and the shared copy of a team's work	Online, behind app.invariant.guru

The CLI reference calls the local service the daemon (invariant daemon).

The desktop app is a window over the workspace that the local service serves. It holds no data and no sign-in of its own: it reads everything from the local service and the invariant command, which it installs and keeps up to date. If you have no desktop app, invariant ui opens the same workspace in your browser.

The web workspace at app.invariant.guru shows the same screens for an organisation's projects (Pro). It never talks to a computer directly and cannot read project files. When you answer, approve or comment there, the change waits as "Sent — waiting for a teammate's machine" until the local service of a member's computer applies it.

The local service

The local service is started by the app or by invariant ui, and keeps running when you close the app. One service serves every project on the computer: adding a second project registers it with the service already running.

It watches each project's .invariant/ folder. When an agent reports a status or ticks a step, the service records it and every open page updates at once. Agents' commands also work when the service is stopped: they write the session file, and the service catches up when it starts again.

The workspace ships inside the invariant command, so the pages and the service always have the same version. When the command updates, open pages reload on their own.

The command your agent calls

Invariant never starts an agent and never calls a language model. You start your agent in its own harness, and paste the line the app copied. The line tells the agent to run invariant session next, which says what to do in the session's current phase and which command to run next.

The command is also the guard. It refuses to let an agent start building before a person has approved the plan, and refuses a report that does not fit the session's current state. See Commands your agent runs.

This machine and organisations

Every project belongs to one context:

This machine. Free, no account. The project and its work stay on this computer.
An organisation (Pro). The project is shared with the organisation's members, on their machines and on the web.

A window shows one context at a time. Its avatar at the bottom of the rail says which: a machine glyph for This machine, or the organisation's monogram. When you use more than one context, a column of tiles on the far left switches between them (⌃ 1 to ⌃ 9). Switching only changes what the window shows; nothing on the computer changes.

An agent always acts in the context of the project it works in. An agent in an organisation's repository acts for that organisation, whatever a window shows.

You move a project between This machine and an organisation from its menu in the hub, with Move…. A move is confirmed first, and is refused while one of the project's sessions is in progress. To go from one organisation to another, a project goes through This machine first.

Signing in adds an organisation to the machine: the app, the local service and the invariant command are all signed in. Each organisation has its own sign-in. Signing out of one keeps its projects listed under it, signed out; your files are not touched. See Teams and organisations.

In an organisation project, the backend keeps the shared copy of each session, and every member's machine keeps a working copy in the repository. One machine writes a session at a time: the machine whose agent claimed it. Others see who holds it, with which agent, on which machine.

When a teammate answers a question, approves the plan or sends it back from another machine or the web, the answer goes to the holder's machine, which applies it. A teammate can take a session over after confirming. The previous holder's copy is kept aside, never lost.

What lives where

	What	Where
In your repository	`invariant.json`: the project's settings, such as its session prefix (`INV`), review gates and, in an organisation, the project's id	Committed with your code
	Your agents' instruction files (`CLAUDE.md`, `AGENTS.md`, …) and the `.agents/` folder with your packages' items	Committed with your code
	`.invariant/sessions/`: session files and their attachments	Your repository's `.invariant/` folder
	`.invariant/reviews/`: review documents	Never committed
	`.invariant/brain/`: the Brain draft for the branch you are on, and the published copy	Never committed
	`.invariant/codegraph/`, `.invariant/worktrees/`: the code index and the worktrees of parallel sessions	Your repository's `.invariant/` folder
	`.invariant/integrations.local.json`: tokens for GitLab, Linear and other integrations	Never committed
On your machine	`~/.invariant/`: the installed versions, the list of your projects (names, groups, contexts), your sign-ins, preferences, logs and the telemetry queue	Your home folder, never shared
Online (organisation)	Accounts, members, project groups, the shared copy of sessions and their attachments, the inbox of each person, comments and conversations, the published Brain	The organisation backend

Pushing your code is still your job: Invariant never commits, pushes or opens a merge request for you.

From the terminal

The same parts from a terminal:

invariant ui              # start the local service and open the workspace
invariant daemon status   # is the local service running, and which projects it serves
invariant whoami          # the organisations this machine is signed in to
invariant self status     # how invariant is installed, and which copy your PATH runs

See CLI overview and Account and machine.