Settings and themes

Invariant has two settings pages. Project settings hold what the repository carries and your team shares. App settings hold what belongs to you and this machine: the theme, what the interface remembers, and the local service.

Where to find them

Page	Open it from	Holds	Stored in
Project settings	The rail's Settings, or `g` `,` (`⇧` `E`)	Project, Agent targets, Plans, Brain, Reviews, Integrations	The project's directory, mostly `invariant.json`
App settings	The context avatar's menu, Settings, from any page	Appearance, Interface, Server & data	This machine, or this browser
Desktop settings	Invariant → Settings… (`⌘` `,`) in the desktop app	Updates, notifications, the local service, the terminal	The desktop app

Project settings read the project's files, so they are in the desktop app and the local workspace, not on the web workspace.

How a settings page works

Both pages are a stack of cards with an index on the left. Each card states its current value while closed ("claude, cursor · 2 of 5" for Agent targets, "Simple reviews only" for Reviews), so you can read the setup without opening anything.

Click a card, or move with J / K and open it with →. ← closes it.
Type in the filter to find a setting by name or keyword.
Some settings save at once, such as the theme or a project's colour. Forms save with Save (⌘ S) or are dropped with Discard (⇧ ⌘ ⌫).
h shows what needs attention. r reviews the cards with unsaved changes.
Each card has its own address, /settings/<card>, so you can link to it. The command palette (⌘ K) finds cards too: typing "theme" in a project leads to App settings.

Screenshot to come/assets/docs/settings-project-stack.webp

Project settings: the cards, each stating its value, with Plans open.

Choose a theme

Open App settings from the context avatar's menu.
Open Appearance.
Under Theme, pick one. The page repaints at once, in every browser pointed at this machine's local service.

Theme	What it is
Indigo	The default. Dark indigo and periwinkle.
Dark Indigo	Indigo after dark: a deep navy page, raised cards and violet-lavender accents.
Graphite	Dark and near-neutral. The hue drains out of the chrome, so status is the only colour on screen.
Paper	Light. White surfaces and ink text, with the status colours darkened to keep their meaning.

The theme applies to every project on this machine. Only the colours change.

Under Display, Show shortcut keys on buttons hides or shows the small key after a button's label. The keys keep working when hidden, and tooltips still name them. This choice is remembered on this device.

Screenshot to come/assets/docs/settings-themes.webp

Appearance: the four themes, each with a live preview.

App settings

Appearance: the theme and the shortcut keys on buttons.
Interface: what the interface remembers on this device. Review footer offers first (Plan changes or Publish), Skills catalogue opens on (Popular or Trending), Play the Projects video on a first visit, and the Page guides list, where Mark every guide unopened (u) brings the guides back. Forget what the interface remembers (f) resets it all.
Server & data: shown when a local service serves the page. It says where the service listens, its process and its versions, with Check for new version (c). Release channel picks Stable (tested releases) or Canary (every new build first) for the CLI and the desktop app. Share anonymous usage data is the telemetry consent; see Telemetry. Stop the daemon stops the local service for every project.

Project settings

Project

Where the project lives and how it appears: its Directory, its Name in the manifest, its Sessions folder, and its branch. Under Identity, rename it on this machine, put it in a Group of the projects screen, and pick its Colour. References sets the Ref prefix in front of every session number.

Agent targets

Which agent harnesses get the activated items: Claude Code, OpenAI Codex, Cursor, Aider and GitHub Copilot. Each row lists the files that target writes.

Switch the targets you want on or off. Changed rows show will add or will remove.
Click Apply. Turning a target on writes its files; turning one off leaves them as they are, since they may have been edited by hand.

Under Sync, Check for drift (c) reports whether the target folders match the canonical store without writing anything, and Sync now (s) rewrites them. What each target writes is on Packages and skills.

Plans

How sessions plan, saved in invariant.json under planning and shared with your team. Changes apply to new sessions.

Human plan: Include a human plan, a readable retelling of the agent's plan shown first to whoever approves it. Plan template shapes it; Preview template (v) shows the result.
Decision checklist: what an interactive session must settle before it plans. The project can Build on the built-in checklist (b) and Add a project aspect (a). Each aspect has a Title, a Settled when sentence and a Required before planning switch; you can reorder, edit, turn off or remove it. Preview checklist (⇧ V) shows the result, and Reset to default goes back to the built-in one.
Interaction behaviour: Answer timeout, how long the agent's commands wait for your answer before printing the line that resumes them; Hide recommendation until answered, so everyone reads the options before seeing the agent's preference; and the Reveal duration.
Build default: the Default build mode that Approve offers first: straight through, step by step or TDD. Step by step and TDD stop after each slice to check in with you; Check in sets how big a slice is. The person approving can still choose for each plan.
Peer approval (Pro): Require peer approval, so a teammate must approve a plan before work starts. Whoever created or imported a session cannot approve its plan. In an organisation, only owners can change it.

Screenshot to come/assets/docs/settings-decision-checklist.webp

Plans: the decision checklist with a project aspect added.

Brain

The templates behind the project brain, shared through the repository: Source document, Product requirements, Architecture decision, which guide the documents agents write, and Knowledge base, which guides the pages people read. See Brain.

Reviews

Where reviews are kept (Review directory), what they compare against (Base branch, detected when empty) and which Editor opens a review's files. Under Fleet, manage the gates of a fleet review: Add gate, Add from preset, reorder or edit them, and Make Fleet the default. See Reviews.

Integrations

GitLab: publish triaged reviews as draft merge-request comments.
Linear: link sessions to issues and sync their spec, with an API key, a default team and an issue template.
Slack: post session and review updates to a channel. See Connect Slack.

Shared settings go in invariant.json; keys and tokens stay on your machine.

Desktop settings

In the desktop app, Invariant → Settings… (⌘ ,) opens a small window:

Updates: Check for updates, and Download updates automatically. With it on, Invariant asks once to restart; off, it tells you a new version exists and waits.
Notifications: Show system notifications while Invariant is in the background. See System notifications.
Local service: Stop the local service when I quit Invariant. Off by default, so agents in your terminals keep using it after the app quits.
Terminal: what invariant ui opens: the app when it is installed, always the app, or always the browser.
Share anonymous usage data: the same consent as in Server & data.

Account

Your account and organisations are in the context avatar's menu: Sign in…, Sign out, Manage members, Invite members… and Add an organisation…. See Teams and organisations.

Usage

The rail's Usage page shows the tokens your agents consumed on this machine, or across your organisation member by member, with an Overview and a Context analysis of what they were given.

Shortcuts

Keys	Action
`g` `,`	Go to project settings
`J` / `K` · `←` / `→`	Move between cards / open or close one
`⌘` `S`	Save the form you are in
`⇧` `⌘` `⌫`	Discard the form's changes
`h`	Show what needs attention
`r`	Review unsaved sections

From the terminal

Most project settings live in invariant.json, which you can edit and commit like any file. invariant target shows or changes the targets, invariant sync writes them, and invariant telemetry enable or disable sets the usage-data consent. See the CLI overview and Account and machine.