Quickstart

Take one task from a few lines of text to reviewed work: your agent plans it, you approve the plan, the agent builds it, and a fresh agent reviews it.

Before you start, install the app and have a coding agent ready, such as Claude Code in a terminal.

Add your first project

If you opened a folder on first launch, it is already your project: skip to the next step.

1. On the Projects page, press Add project (a).
2. Choose your repository's folder, or type its path.
3. If the folder is not an Invariant project yet, the dialog asks you to set it up. Under Agents, pick the agents you use (Claude Code is picked for you), then press Set up and add.

Setting up adds invariant.json, a .invariant/ folder and the instruction files your agents read. Those files teach the agent how to read a session and report its progress. Nothing else in your repository changes.

Press the project to open it on its sessions board.

Write the task

1. Press New session (n).
2. Choose how to plan it:
   • Static · Hand it over. The agent plans on its own; you review the plan when it is ready. Good for quick changes.
   • Interactive · Plan it together. The agent studies the code, then asks you questions round by round until every key decision is yours. Good for features and real decisions.
3. Describe what should be built, in a few lines. You can paste an issue as it is, and attach files such as a screenshot.
4. Press Create session.

The session appears on the board, and the app copies its execute line to your clipboard.

Hand it to your agent

Open your agent in the project's folder and paste the line. It looks like this:

INV-001: I'm asking you to plan session-…: no code before I approve; … Run `invariant session next session-…` and follow what it prints; the instructions are in …/.invariant/sessions/session-….md. …

The agent asks the invariant command what to do, claims the session and starts planning. On the board, the session moves to Planning, with your agent's name beside it.

If you lose the line, open the session and press Copy execute line, or press ⇧ ⌘ R.

Answer the interview

An interactive session asks before it plans. While the agent studies the code, the session reads Interview · investigating. When a round of questions is ready, it reads Interview · R1 · waiting on you and a toast tells you. (A static session can ask a few questions too, when its plan depends on them: it then reads Questions · waiting on you.)

1. Open the session. Each question is a card.
2. Answer in your own words, or accept the agent's recommendation. A question you leave unanswered is left to the agent.
3. Press Send answers. The agent reads them and asks its next round, or proposes an agreement: the decisions you made, in one list.
4. Read the agreement and press Confirm agreement, or Request changes with a note.

Only then does the agent write the plan.

Approve the plan

When the plan is ready, the session reads Awaiting approval, and a toast says the agent finished the plan.

1. Open the session and read the plan. A human plan, a one-screen retelling, comes first when there is one.
2. If something is wrong, press Request changes, write a note and press Send back. The agent revises the plan and answers your note.
3. When you agree, press Approve & build. The caret beside it lets you choose how the plan is built (straight through, step by step, or TDD-style, with check-ins) and whether a waiting agent starts building now. In an organisation the button reads Approve by default, because a teammate often reviews first.

The agent waits a few minutes for your decision. If it is still waiting, the approval box says so, and it starts building as soon as you approve. If no agent is waiting, press Copy execute line and paste it into your agent again.

Follow the build

While the agent builds, the session reads Building. Each step of the plan is ticked as the agent finishes it, and the page updates on its own. If you chose step by step or TDD, the agent checks in after each slice: read what it did, then press Continue or Request changes.

When the work is done, the session reads Done and the agent's summary appears on the page: what changed, how it was verified, and what was not tested.

The agent never commits or pushes for you. Read the changes, then stage and commit them yourself.

Open a review

A finished session ends with a What next card.

1. Under Review, press Simple review. The app creates a review session and copies its line.
2. Paste the line into a new agent conversation. A fresh agent has not seen the plan, so it reads the change as evidence, not as confirmation.
3. When the findings arrive, go through them on the review's page: stage (s) the ones that matter, discard (d) the rest.
4. Press Plan changes. The staged findings become the plan of a fix, which you approve and hand to an agent like any other plan.

The reviewer reads the commits of your branch and what is staged. Changes that are only in your working tree are not part of the review.

Keep going

• Start an iteration (i) to carry the work on with the same context.
• Read what your project has learned on the Brain page.
• Install shared instructions for your agents: Packages and skills.
• Learn the whole session page: Sessions and Reviews.
• Work with your team in an organisation.

From the terminal

Every step above has a terminal equivalent. For example, invariant plan "Add keyboard navigation to the project switcher" creates a session and prints its line, invariant session approve <id> approves a plan, and invariant review open --session <id> opens a review. See CLI overview.