Projects

A project is a folder you add, with a button of its own in the header, in the order you give them. A session belongs to the project you added that holds its folder, wherever it works there: in the folder, a subfolder, or a worktree of the folder’s repository, wherever the worktree is. Where two projects hold it, the one deeper in the folders wins. A session in a folder no project holds belongs to that folder alone, which you can add as a project later, its sessions with it.

Sessions and the board are in Sessions and the board.

• Add project opens a dialog: choose the Folder, give it a Name, the folder’s own name until you type another, up to 80 characters, and, in a git repository, the Files to copy into new worktrees (see Worktrees). Add adds it, last in your order. Under the folder, the dialog says why it can’t be added: it’s your home folder, it’s a project already, or it isn’t a folder. With no agent signed in or set to check at start yet, Add project opens Profile on its Providers tab instead (see Signing in). Where Codex is installed and your organisation’s managed Codex settings give new projects a folder, Choose folder… opens there.
• Click a project’s name to focus it: the transcript panel closes, the project’s button lights up whole, its name and the part beside it as one, and the buttons at the window’s right edge open its folder’s Files, Git and Terminal (see The layout). Click a card to focus its session again. Click the focused project’s name again to let it go: its view closes and nothing is in focus, and the next click opens that view again. A restart lets a project’s focus go too: Moontors opens on the board with nothing in focus. While a session is focused, its project’s button glows more softly, its name and the part beside it in the focus colour.
• The part beside a project’s name starts a session in its folder (see Starting a session in a project).
• Right-click a project’s button, or press the menu key or Shift+F10 on it, for its menu:
  • Edit project… opens the same dialog, to rename the project, change its files to copy, or move it to another folder. It can’t move while it has sessions that aren’t archived, and the dialog says how many.
  • Reveal in Finder (Reveal in File Explorer on Windows, Open Containing Folder on Linux) shows the project’s folder.
  • Remove project…, there only while no session that isn’t archived belongs to the project, asks first. Its button goes; the folder and its files stay on disk.
• A project whose folder isn’t there any more shows a warning mark on its button and has no chevron. Its menu offers Edit project…, to point it at the folder’s new place, and Remove project… alone.
• Drag a project’s button to put it in another place among them. With the keyboard: Space picks it up, the arrow keys move it, Space drops it, and Escape puts it back; Enter focuses the project, or lets it go while it’s focused. The order is kept when Moontors restarts.

Starting a session in a project

The part of a project’s button beside its name starts a session in the project’s folder:

• With no agent signed in or set to check at start, it opens Profile on its Providers tab (see Signing in).
• A + starts the session at once, or asks the new branch’s name first where that one way is a new branch. It’s there with one such agent, where the folder isn’t a git repository or has no commits yet, or where the one quick action you keep shown can always happen.
• Otherwise a chevron opens the project’s menu. With several such agents, it lists them first: the signed-in ones in your order from Settings, then those that check at start, each saying so under its name; each opens the ways to start. With one, the ways to start are listed at once.
• A project whose folder is gone has neither.

The menu lists the quick actions you keep shown in Settings, in your order, each only where it can happen now, and each says under its name, across its row and in three lines at most, what it will do and what stays as it is:

• Here: in the folder as it is. It names the folder’s branch, or its commit where it’s detached, how far it is ahead (↑) and behind (↓) its upstream, and its uncommitted changes, these last two smaller and dimmer than the name, as on every item.
• Check out the default branch, then here, named by the branch, where the folder is on another branch or detached: it checks the default branch out in the folder, its uncommitted changes coming along, then starts there. Where another worktree has the default branch checked out, it’s greyed and says which.
• Pull the default branch, then here, named by the branch, where the default branch is behind the remote’s and not ahead: it pulls the default branch first, only ever fast-forwarding, then checks it out and starts there. If the pull is refused, nothing changes, and Start here without pulling checks it out as it is.
• Pull, then here, where the folder’s branch is behind the remote’s and not ahead: it pulls first, only ever fast-forwarding. If the pull is refused, nothing starts, and Start here without pulling starts the session in the folder as it is.
• New branch here… asks the branch’s name, then makes it at the folder’s commit and switches the folder to it, its changes coming along.
• New worktree · default branch, named by the branch: a worktree of its own (see Worktrees) at the remote’s default branch, fetched first, whatever your own copy of it holds, or at your own where there’s no remote. If the fetch fails, it starts at the commit fetched last, and the session says how old that is.
• New worktree · current branch, named by the folder’s branch or commit where that isn’t the default branch: a worktree at the folder’s commit. Where the branch is behind the remote’s, it asks which: yours, or the remote’s.
• New worktree with my changes, where the folder has uncommitted changes: a worktree at the folder’s commit, with a copy of them.
• New branch in worktree… asks the branch’s name and where it starts, From: the default branch’s newest commit first, marked so, then the folder’s own commit and every branch and remote branch, on the repository’s own remotes, found as you type. Starting from the folder’s commit, where it has uncommitted changes, Copy my uncommitted changes brings them along.
• Branch lists your other local branches, ten at a time in a list that scrolls, each starting a worktree on it, and what you type searches them and the remote’s too. One behind the remote’s asks whether to take it as it is, fast-forward it first, or start from the remote’s; one that has diverged from it, as it is or from the remote’s. One checked out in another worktree joins it there, the session starting in that worktree. A branch only on the remote, found by a search, starts a worktree on a new branch of yours that tracks it. Escape clears the search, then goes back.

Under the list, the menu says how long ago the remote was fetched. Where that’s long ago, Moontors fetches it in the background, and the menu follows. Edit project… ends the menu.

A new branch’s name is checked as you type, and the dialog says why one can’t be used. Enter creates it, and Escape cancels.

A pull, a checkout or a new branch here changes the files under any other session working in the folder, so it asks first, in Before it starts: Start anyway starts it. A checkout that leaves a detached commit no branch holds asks first too, as the Git view does. A branch checked out in another worktree offers Start in its worktree. Anything else that stops the session says why, in The session didn’t start.

The session starts with its agent’s defaults from Settings, and opens. A default the agent no longer offers falls back to the agent’s own, and a line under the header says so, naming the session, until you dismiss it.