Install the app

Install the desktop app to work on your own computer, free and without an account. Sign in to the web workspace when your team works in an organisation.

Choose how to work

You also need:

• A coding agent, such as Claude Code, Codex or Cursor. It does the work in its own harness; Invariant never launches it. See Agents and harnesses.
• Git on your PATH, for your repositories and for packages installed from GitHub.

Install the desktop app

Download it from invariant.guru/download. It is a .dmg for macOS on Apple silicon. Windows, Intel Macs and Linux are not published yet: on those, install only the command line and open the workspace in your browser.

Open the .dmg and drag Invariant to your Applications folder.

First launch

The first time you open the app:

1. Welcome to Invariant. Leave Add the invariant command to my terminal ticked so your agents can call it, then press Get started. If an invariant command is already installed, the app says which one and keeps its own up-to-date copy.
2. Getting Invariant ready. The app installs the command and starts the local service. Each step shows a mark when it is done. If a step fails, Try again runs it again.
3. Open a folder. Pick the project you want to work on, with Open folder…, or Skip and add projects later.
4. Set up Invariant in your folder? If the folder is not an Invariant project yet, the app offers to set it up. This adds invariant.json, a .invariant/ folder and agent instruction files such as CLAUDE.md. Nothing else in your repository changes. Press Set up, or Choose another folder.

The app then opens your project. You can open more folders at any time from File › Open Folder… (⌘ O) or from the hub's Add project. See Hub and projects.

This machine

Everything you do without an account lives under This machine: your projects, their sessions, reviews, Brain and packages. The avatar at the bottom of the left rail shows a machine glyph and reads "This machine · Free".

Your work stays in your files. Quitting the app leaves the local service running, so agents in your terminals keep reporting. To stop it when you quit, open Invariant › Settings… (⌘ ,) and tick Stop the local service when I quit Invariant.

Sign in to an organisation

An organisation shares projects with your team. To sign in from the app:

1. Press the avatar at the bottom of the rail, or choose Invariant › Sign In….
2. Choose Sign in, or Create an account. Your browser opens on Invariant's sign-in page; the app waits with "Finish signing in in your browser".
3. Approve in the browser. The app opens your organisation.

If This machine already holds projects, the app asks whether to move them into the organisation: Move all, Choose… or Keep them local. You can move a project later from its menu in the hub.

Signing in signs in the whole machine: the app, the local service and the invariant command. Each organisation has its own sign-in, so you can belong to several. See Teams and organisations.

Use the web workspace

Members of an organisation can also work from a browser:

1. Go to app.invariant.guru and sign in. To join a team, sign in with the email a teammate invited.
2. Open the workspace. It shows your organisation's groups and projects, the same hub as in the app.
3. Open a project to read its sessions and reviews, answer an agent's questions, approve a plan or comment.

The web workspace has no access to your project's files. When you change something there, it shows "Sent — waiting for a teammate's machine" until the local service of a member's computer applies it. Anything that needs the files, such as handing a session to an agent, happens in the desktop app.

Install only the command line

Install the invariant command without the app on a server, a machine the app does not support yet, or if you prefer the terminal. It gives you the same local service and the same workspace, in your browser.

The install script

Native builds are published for macOS on Apple silicon first. On another system the script stops with "no build for … yet"; use npm until that platform is published.

On macOS or Linux:

curl -fsSL https://invariant.guru/install.sh | sh

On Windows, in PowerShell:

irm https://invariant.guru/install.ps1 | iex

The script finds your platform, downloads the matching build, checks its SHA-256 against the release manifest, and hands over to invariant self install. It needs no Node.js and never asks for administrator rights.

Options, for the shell script:

curl -fsSL https://invariant.guru/install.sh | sh -s -- --channel canary
curl -fsSL https://invariant.guru/install.sh | sh -s -- --version 0.10.1
curl -fsSL https://invariant.guru/install.sh | sh -s -- --no-path

• --channel canary installs the latest canary build and keeps following the canary channel: every new build, before it reaches stable.
• --version installs one exact version.
• --no-path leaves your PATH and shell startup files alone; the command is then at ~/.invariant/current/invariant.

In PowerShell, the same options are -Channel canary, -Version 0.10.1 and -NoPath:

& ([scriptblock]::Create((irm https://invariant.guru/install.ps1))) -Channel canary

npm

With Node.js 26 or later:

npm i -g @invariant.guru/cli

The package installs invariant in your npm global directory. If your terminal cannot find it, check that this directory is on your PATH and open a new terminal.

Open the workspace

In your project folder:

invariant init
invariant ui

init sets the project up for Claude Code. To set it up for other agents, name them: invariant init codex cursor. invariant ui starts the local service, or uses the one already running, and opens the project: in the desktop app when it is installed, in your browser otherwise (--browser forces the browser).

What gets installed where

The desktop app and the install script share one install, in your home directory:

~/.invariant/
├── current        → versions/0.10.1   the version in use
├── versions/      the installed versions: the current one and up to two previous
├── install.json   how it was installed, and the release channel
└── …              your project list, sign-ins, preferences and logs, which updates never touch

• macOS and Linux: ~/.local/bin/invariant points to ~/.invariant/current/invariant. If ~/.local/bin is not on your PATH, the installer adds one line, marked # added by invariant, to your shell's startup file.
• Windows: %USERPROFILE%\.invariant\current is added to your user PATH.

Set INVARIANT_HOME to keep everything somewhere else.

Your projects are not in ~/.invariant: each project keeps its own files in its repository, under .invariant/. See How it fits together.

You can keep the npm package next to an app or script install. They share ~/.invariant and one local service, which runs the newer of the two. Your terminal runs whichever invariant comes first on your PATH. To see which one that is:

invariant self status

Updates

The app, the invariant command and the workspace share one version number, and update together.

The desktop app

The app checks for a new version shortly after it opens, then every 15 minutes. With Download updates automatically on (the default, in Invariant › Settings…), it downloads the new version in the background, then shows Update ready with Restart now. If you do not restart, the update installs the next time you quit. With the setting off, it shows Update available and waits for you to press Download update.

To check now: Invariant › Check for Updates…. Release notes are in Help › What's New.

After the restart, the new command and the new workspace are in place, and open pages reload on their own.

The command line

A script install updates itself: at most once a day, after a command you typed, it checks for a new version in the background, verifies its signature and checksum, and switches to it. It never does this in CI or when an agent runs the command. An npm install shows a one-line notice when a new version is out.

To check or update now:

invariant update --check
invariant update

To go back to the version you had before (app and script installs):

invariant update --rollback

To follow canary releases, or return to stable:

invariant update --channel canary
invariant update --channel stable

The same choice is in the workspace: Settings › Server & data › Release channel. The desktop app follows it. Canary needs the app or the install script: npm only gets stable releases.

To turn automatic updates off: invariant update --auto off. They are also off when INVARIANT_DISABLE_AUTOUPDATE=1 is set.

Uninstall

The desktop app

Quit Invariant and drag it from Applications to the Trash. The invariant command stays, so agents keep working. To remove it too, choose Invariant › Uninstall ‘invariant’ Command… before you remove the app. It asks first, then quits; your projects, settings and sign-ins stay.

The command line

For an app or script install:

invariant self uninstall

This removes the command, the installed versions and the PATH changes. Your project list, sign-ins and logs stay. To remove those too:

invariant self uninstall --purge

It asks for confirmation (or pass --yes). Your repositories are never touched: each project's files stay in its own .invariant/ folder.

For an npm install: npm uninstall -g @invariant.guru/cli.

Continue with the Quickstart to create your first session.