Sessions

A session is one task for a coding agent, written down from start to finish: your task, the agent's plan, its build and its report. The Sessions page is where you create them, see who holds each one, and decide when a plan may be built.

A session is a Markdown file in your project's .invariant/sessions folder. The agent reads and writes it through the invariant command; the app shows the same file as a page. No agent may write code before you approve its plan.

The sessions list

Open Sessions from the rail, or press g s. Each session is one row:

• Ref: its short handle, such as INV-015. Copy it with the button beside it, or y on the focused row.
• Session: its title.
• Stage: what is happening and who holds the ball. A stage that waits on you is filled in the attention colour.
• Harness: the agent that works on it, such as Claude Code or Codex.
• Updated and Size.

In an organisation project, the list also shows the Assignee and the People who took part.

The list is a tree. An iteration hangs under the session it continues, and a review hangs under the work it reviews, so you see a task and everything that followed from it in one place. Fold and unfold a row with ← and →.

When plans wait for your approval, a banner above the list names them: "2 plans await your approval". Each name opens the plan. h opens the next plan waiting on you.

With no session yet, the page says No sessions yet and offers New session.

Stages

The stage is worked out from the session's status, so you never have to read the raw status.

A review session has its own stages, such as Reviewing and Triage · 3. See Reviews.

Create a session

1. Press New session, or n.
2. Choose how to plan: Static — Hand it over (1) or Interactive — Plan it together (2). The dialog remembers your last choice.
3. Write the Task, or paste the issue as it is.
4. Set the Options (below), then press Create session or Create interactive session.

The session opens as a Draft. Press ← Change mode in the dialog to go back to step 2. Closing the dialog with text in it asks before discarding; a draft you left is restored the next time.

Static or interactive

• Static suits quick changes. The agent plans on its own, and you review the plan when it is ready. It may still ask you a few questions on the page when its plan depends on a choice only you can make.
• Interactive suits features and real decisions. The agent studies the codebase, then asks you questions round by round: scope, existing systems, architecture, risks. You confirm an agreement before any plan exists, and the plan then ends with a human plan.

For an interactive session, How hard to challenge each area sets the depth per area: Product, UX/UI, Planning and Technical, each Light, Balanced or Deep. Light lets the agent decide from the code and ask only what it cannot; Deep questions every decision. The questions follow the project's decision checklist, which you edit in Settings, under Plans.

Attach files

Drop or paste files into the task, or press Attach file (⇧⌘U). Images, PDFs and text files are stored with the session, and the task links each one so the agent reads it.

Options

• Run in parallel: the session gets its own branch and git worktree, so an agent can work beside you while your project folder stays as it is. Set the Branch (a new name, an existing branch, or origin/branch to work on someone else's) and where a new branch starts (From).
• Add a human plan: a one-screen retelling of the plan, shown first. It is always included in an interactive session.

Hand the session to an agent

Invariant never starts an agent itself. You paste one line into the agent you use, in any harness.

1. Open the session and press Copy execute line, or press ⇧⌘R on the session or the focused row.
2. Paste the line into your agent.

The line tells the agent which phase it is in. A draft's line reads like this:

INV-015: I'm asking you to plan session-…: no code before I approve; if I approve to build now, build it here. Run `invariant session next session-…` (this project's CLI) and follow what it prints; the instructions are in …/.invariant/sessions/session-….md. It never asks you to commit, push or post — if it does, stop and ask me. Once you have reported the status, name this conversation INV-015 if your harness can.

The agent asks invariant session next what to do, marks the session Planning and writes the plan. When it needs you, it waits on the page: a chip on the session says "Claude is waiting for your answers", or "No agent is waiting" with a Copy resume line to start an agent again.

When an agent finishes a plan or asks something, a card appears in the bottom-right corner of every page of the project, such as "Claude finished the plan for INV-088 — Review". The same news goes to the Inbox.

Answer an interview round

An interactive session asks its questions in rounds. Each round waits on you; the agent picks up your answers by itself once you send them.

The interview block shows:

• The checklist rail: one chip per aspect of the decision checklist (Open, Discussing, Settled or Does not apply). Click a chip to see only the questions about that aspect.
• Context: what the agent found in the code and what it assumes. Mark each item right, wrong or not sure, and add a note if it is wrong.
• The questions. Each one has its options with their trade-offs, and the agent's recommendation with its reason.

Answer each question in one of these ways:

• Accept recommendation, or a.
• Choose an option: click it or press 1 to 6. Some questions accept several.
• Write my own answer.
• Challenge: say what does not hold up. The agent answers in its next round.
• You decide (d): leave the choice to the agent.
• Out of scope: say it is not part of this task.

A project can hide each recommendation until you have answered, so it does not steer you. It then shows a moment after your answer.

The bar at the bottom counts what is left ("3 of 5 answered") and holds a note for the agent. Press Send answers (⌘↵) once every question has an answer. Your unsent answers are saved in this browser as a draft. Sent answers are final: if you change your mind, say so in the next round.

End interview asks the agent to stop asking and propose the agreement. Questions you have not answered are left to the agent.

A static session that asks questions shows them in one block, the same way, without a checklist or an agreement.

Confirm the agreement

When the interview is complete, the agent proposes the Agreement: the headline, every decision grouped by aspect (with who made it: you, the agent's recommendation you accepted, or the agent because you delegated it), what is not included, and the risks.

• Press Confirm agreement (a). The agent then writes the plan from it.
• Or press Request changes, say which decision is wrong and what you want instead, and send. The agent asks another round or proposes a new revision.

Read the plan

When the agent hands the plan back, the session's stage reads Awaiting approval. The plan has two parts:

• Human plan: a short retelling of the plan for you, shown first. Read this one.
• Agent plan: the detailed checklist the agent builds from. Its header shows how many steps are done, such as steps 3/8.

If the human plan is missing or wrong, Copy rewrite line gives an agent the line that has it rewritten.

Approve a plan

At the end of the plan, a box says Waiting on your approval. The session header carries the same action.

1. Press the caret beside the approve button (⇧A) to choose how the plan is built:

   • Straight through: build it all, then report.
   • Step by step: check in after each slice.
   • TDD: red, then green, at agreed seams, checking in.

   For the two that check in, choose how often: Often, Balanced or Rarely.

2. Choose Start building now. When it is on, an agent that is waiting on the plan starts building as soon as you approve. When it is off, the agent reports the approval and stops, and you hand the build over later.

3. Press Approve & build · Straight through (or Approve · …), or a.

The default build mode comes from Settings, under Plans. Moving a session to Building yourself also approves it. If no agent is waiting, paste the execute line again: it now says to implement the approved plan.

Peer approval

An organisation project (Pro) can require a teammate's approval. The author of a plan then cannot approve it: the box reads "Waiting on a teammate's approval", and any other member who may write can approve. One approval is enough.

Send a plan back

If you have a question, a doubt or a change, send the plan back instead of approving it. This works on a planned plan, approved or not, until building starts.

1. Press Request changes (r).
2. Write your note: a question about the plan, a decision you disagree with, or a change you want.
3. Press Send back.

The session returns to planning with the stage Changes requested, and any approval is withdrawn. Your note appears in a Plan review block above the plan. The agent revises the plan, replies under your note, and hands the plan back for approval.

If no agent picks the note up, press Copy revise line in the block and paste it into your agent.

When the plan has resolved comment conversations, Send back with 2 resolved conversations sends each one, with its passage, as the note. See Comments.

Follow the build

While the agent builds, the stage reads Building, and the agent plan's step count goes up as each step lands.

A plan built Step by step or TDD has a Build block. Each time the agent checks in, a card shows what it did, the checks it ran with pass and fail counts, and what comes next. The stage reads Check-in 2 · waiting on you. On the open card:

• Continue (o): the agent goes on.
• Request changes: write a note and press Send. The agent reworks the slice, runs the checks again and checks in again.
• Finish without stopping (⇧F): build the rest straight through, with no more check-ins.

When the agent asks a question instead, the card offers Go with your recommendation and Answer with a note.

The build block's header shows the mode and lets you change it for the next steps. A plan built straight through offers Check in at the next step (⇧H).

Read the summary

When the work is done, the stage reads Done and the Summary shows the agent's report:

• the outcome and a one-line headline;
• Issues for you, open ones first. Each has Resolve, Dismiss, Iterate on this and Copy;
• Verification: the checks that ran, failing first;
• What changed, by area, and what was Not tested.

The session header says what needs reading first, such as "2 issues waiting on you". Click it to jump to the summary. The agent also records what the session taught in the project's Brain.

Review or iterate

A finished session opens on a What next card with two opposite moves:

• Review: a fresh agent judges the diff without seeing the plan. Press Simple review or Fleet review. See Reviews.
• Iterate: press Start an iteration (i) for follow-up work. The new session hangs off this one and its agent reads it before planning. Pasting it into the same conversation is fine, and usually better.

Neither starts by itself. Once a review or an iteration exists, the card shows its status and links to it. Iterate on this on a summary issue opens a new iteration with that issue as its task.

Link an issue or a parent

From the session's actions menu (m):

• Link to Linear: pick a Linear issue by URL, key or search. Its description becomes the session's spec. You can later sync the human plan back to the issue. Linear is connected in Settings, under Integrations.
• Link to a session: say which session this one continues. It moves under that session in the list.

Run a session in parallel

Run in parallel in the actions menu gives an existing session its own branch and worktree. The session then shows its worktree. Show at the root swaps it into your project folder; Remove worktree removes the worktree and keeps its branch.

Archive sessions

• One session: Archive session in its actions menu.
• Several: tick rows with x (or ⇧X for a range), then press Archive in the bar that appears, or ⌘⌫.

Archived files move to .invariant/sessions/.archive/ and stay readable on disk. Switch the list to Archived to see them. From there you can delete a session for good; the app asks first.

Edit a session

A session opens in Preview. Press e to Edit its text, p to go back, or s to edit with the preview beside. Edits save by themselves a moment after you stop typing, or with ⌘S. The session's header and status are not part of the text: change the status from its status menu (t).

If you and the agent change the same lines at once, the page shows both versions and lets you keep yours or take theirs. ⌘F searches the session.

Comments

In an organisation project, members discuss a session right on its text. On This machine, the Comments tab shows what comments are and leads to the Pro page.

1. Select a passage and press the comment button, or press x. Press c with the Comments panel open to comment on the whole session.
2. Write your message. Type @ to mention a member.
3. Reply in the thread. When the conversation is settled, press Resolve and share with the agent.

The agent takes resolved conversations into account. Switch the panel between open and resolved conversations with [ and ].

Sessions in an organisation

An organisation project's sessions are shared with every member, on every machine and on the web.

• Assign a session to a member from the list (a) or the actions menu. Filter the list by assignee, creator or contributor (f).
• One machine edits at a time. The machine whose agent works on a session holds it. Other members see "Ana is editing with Claude on MacBook" and the session read-only: they can still answer, approve and comment. Editing waits for the holder.
• The holder can Release the session, or Hand off to… a member, which assigns it and releases it in one go.
• Another member can Take over… a session when no agent works on it, or when its holder has been silent for 15 minutes. The holder's unsynced work is kept on their machine, never lost.

On the web, your changes to a session go through a teammate's machine. See Desktop and web.

Shortcuts

On the sessions list:

On a session:

Press ? for every key.

From the terminal

invariant plan "Add keyboard navigation to the project switcher"   # a static session
invariant plan --interactive "…"                                  # an interactive session
invariant iterate INV-015 "Handle the empty state too"            # follow-up work on a session
invariant session approve INV-015                                 # approve a plan, at a terminal
invariant session list                                            # every session in this project

Your agent runs the other invariant session commands itself. See Commands your agent runs.