Hub and projects

The hub is the list of your projects and the first thing the app shows. It tells you, project by project, what is in flight and what waits on you, so you know where to go next.

Open it from the brand mark at the top of the rail, or with ⇧⌘H from any project page.

What you see

The header says Projects and how many there are: "3 projects on this machine", or "3 projects in Acme" in an organisation. The hub lists only the projects of the context the window shows.

Each project is one row:

• a coloured rule and monogram, in the project's own colour;
• its name and its path;
• the current git branch;
• four counts: in flight, awaiting you, unread and open comments;
• the last activity.

A count of zero is a dot, so the only numbers on a quiet hub are work that waits. Inside each group, the most recently opened project comes first.

Some rows cannot be opened, and say why where the counts would be:

• missing: the project's folder no longer exists. The row is dimmed.
• not initialized: the folder has no invariant.json. The row offers Set up.
• Not set up on this machine: an organisation project that a teammate added from another machine. It is marked Not usable yet and offers Set up on this machine…. See Set up an organisation project here.

When you are signed out of an organisation, its hub shows a banner: "You're signed out of Acme. Projects still open locally; Pro and groups come back when you sign in." Press Sign in again.

Open a project

Click a row, or move to it with J / K and press ↵. The project opens on its Sessions page. ⌘-click opens it in a new tab.

From any page, ⌘P opens the command palette on your projects, filed under their groups. You can also click the project chip on the rail.

Type / to filter the hub. The filter matches names, paths and group names, and opens every group while it is active.

Add a project

1. Press Add project (a).
2. Press Choose folder… to pick the folder in your system's folder dialog, or type its path (~ works).
3. In an organisation, or when you have groups, choose a Group.
4. Press Add project.

If the folder is not an Invariant project yet, the dialog moves to a set-up step. It says what will be added: the project's configuration and your agents' files. Nothing else changes. Pick the Agents you use (Claude Code is ticked by default), then press Set up and add. You can change the agents later in the project's Settings, under Targets.

The project is added to the context the window shows: This machine, or the organisation you are in.

Rename a project

The name on the hub is a label for this machine only. It does not change invariant.json, so your teammates keep their own names.

1. Focus the row and press r or F2, or press Rename on the row.
2. Type the new name and press ↵. Esc cancels.

A renamed project shows its original name beneath the new one. To go back to it, clear the name. If you add a folder whose name is already on the hub, its row opens straight into rename.

Remove a project

Press Remove on the row, or ⌘⌫ on the focused row, then confirm.

• On This machine, this only removes the project from the list. Nothing in its folder is touched, and adding the path again brings everything back.
• In an organisation, the project is removed from the organisation: here, on your other machines and on the web. Nothing on disk is touched.

Project groups

Groups are collapsible sections of the hub. A group header shows its name, its colour, how many projects it holds and the sum of their counts, so a collapsed group still tells you that something waits inside.

The hub shows no group headers until you create a group. Once a group exists, the projects outside every group are listed under Ungrouped, last.

Create a group

1. Press New group (g).
2. Type a Name and pick a Colour (1 to 8).
3. Press Create group.

Rename, recolour or delete a group

Hover the group header and use its actions, or focus the header and press r to rename and recolour it. Deleting a group keeps its projects: they move back to Ungrouped.

Collapse and expand a group with its header, or with H / L (or ← / →) while it is focused.

Move a project to a group

1. Press Move to… on the row, or m on the focused row.
2. The command palette opens on your groups. Pick one.

The last entry of that list, New group…, creates a group and moves the project into it in one step.

Groups in an organisation

An organisation's hub (Pro) works the same way. Its groups belong to the organisation: their names, colours and the projects in them are the same for every member, on every machine and on the web. Which groups you fold, and their order, follow your account.

Move a project between contexts

A project can move between This machine and an organisation. Its files stay where they are.

1. Press Move… on the row. It shows only when there is somewhere to go.
2. Under To, pick the destination: This machine, or an organisation you are signed in to.
3. Moving into an organisation, choose the Project in that organisation: New project, or Join a project that other clones of the same repository already use. Then pick a Group.
4. Press Move to <destination>.

When a project moves into an organisation, its sessions are shared with the organisation. A report then says how many sessions were uploaded from this clone, how many were downloaded, and which were renumbered because their number was already taken. It also reminds you to commit invariant.json: it now names the organisation's project, and it is how the other clones join it.

Some moves are refused, with the reason in the dialog:

• A project goes from one organisation to another in two steps: move it to This machine first.
• A project with a session in progress moves once the work is done.
• A project that belongs to an organisation stays there. Only its creator can remove it from the organisation, for everyone.

To move a whole group, use Move group to… on its header, or ⇧M on the focused header. Every project that can move goes with it, into a group of the same name. The dialog lists the projects that stayed and why.

The first sign-in

The first time you sign in to an organisation while This machine holds projects, the organisation's window asks: Move your 3 local projects into Acme? Choose Move all, Choose… to pick projects and their groups one by one, or Keep them local. The question does not come back once you answer it.

Set up an organisation project here

An organisation project that a teammate added from another machine is listed on your hub, but you cannot open it until this machine has a clone of its repository.

1. Clone the project's repository with git. A teammate who works on it can tell you where it is.
2. On the hub, press Set up on this machine… on the project's row, or u on the focused row.
3. Choose the Folder of your clone.
4. Press Link this folder.

The folder must contain the project's committed invariant.json. If the folder is already listed on This machine, it moves into the organisation and its sessions sync with the project's.

The empty hub

With no project yet, the hub shows the ways in as cards:

• Create a local project: pick a folder on this machine. Invariant sets it up if it is not a project yet.
• Create an online team: create an organisation to share projects, groups and Pro with your team.
• Join an existing online team: sign in with the email a teammate invited.

In an organisation with no project, the hub says "No projects in Acme yet". Add a project folder, or move one in from This machine with Move….

Shortcuts

From the terminal

invariant init claude codex                          # set up the current folder as a project, for these agents
invariant projects list                              # the projects on the hub
invariant projects add ~/code/api                    # add a folder to the hub
invariant projects group ~/code/api Backend          # file it under a group, creating the group if needed
invariant projects move ~/code/api --to <organisation>   # move it to an organisation (--to local brings it back)

See the CLI overview for the rest.