Projects & sessions

Click + next to Projects or press ⇧⌘N. Give the project a name and choose an existing folder.

Hover over a project to reveal its menu and collapse control. Use the menu to edit the project’s display name, move it, or remove it. Renaming a project does not rename its folder.

Choose Edit Project… to give the project an emoji and a description of up to 500 characters. The emoji replaces the folder icon in the sidebar and marks the project’s space in Arc Mode. The description appears when you hover over the project name. You can also add a description when you create the project.

Open the + menu on a project row and choose Session, or press ⌘N. The Default Agent is listed first. Orchestra starts its CLI through your login shell, in auto mode when the agent supports it.

You can create several sessions in the same project and use different agents. Each session has its own process and terminal state.

Create a new worktree is checked by default. The session starts on a new branch from the current commit, in its own checkout:

• Folder: ~/.orchestra/worktrees/<repository>/<id>
• Branch: orchestra/<agent>-<id>

Uncommitted changes stay in the original folder. Clear the checkbox to start the session in the project folder instead. Worktrees require a Git repository with at least one commit.

Press ⇧⌘B, click Changes in the status bar, or choose Show Changes in the command bar to open the Changes pane beside the selected session. It stays open as you move between sessions.

• For a session in a worktree, it shows the commits and uncommitted changes since the worktree started.
• For a session in the project folder, it shows uncommitted changes compared with HEAD. Other sessions in that folder share these changes.

Each file shows whether it was added, modified, deleted, or renamed; expand it to read the changes with line numbers. New files that Git does not ignore count as added. The pane refreshes when an agent finishes its turn, or click Refresh Changes. Drag its edge, or use the arrow keys on it, to resize it. Binary files and very large changes are not shown.

Choose + → Terminal, or New Terminal in the command bar, to open your login shell in the project folder. Terminals have no activity dot and are not used for Work on, Review, or messaging.

When a terminal’s shell exits, choose Start New Shell. After a restart, selecting a terminal starts a fresh shell.

Projects start without a Scratchpad. Open a project row’s + menu and choose Scratchpad to add and open its notes page. Write in Markdown in Edit mode, and switch to Read mode to see it rendered, or press ⌘E to toggle. Orchestra saves it automatically with the project and restores it when the app reopens.

Agents can use the Scratchpad too. From a session inside the app, orchestra scratchpad read, write and append read and change the project’s notes, and the open editor picks up their changes while keeping your unsaved edits.

Select a session in the sidebar to show its terminal. Switching views keeps the other session processes and terminal scrollback alive while the app remains open.

Each project remembers its last selected session. The activity dot at the end of each row shows which agents are working or waiting; see activity indicators.

• Edit Session…: change its display name.
• Resume Session: reopen an ended conversation when its agent ID was captured.
• Messages…: inspect the inbox, send requests, or read replies.
• Copy Session ID: copy the address used by the Orchestra messaging CLI.
• Move Up / Move Down: reorder without dragging.
• Close Session…: stop the process and remove the session from the project.

When a worktree session closes, Remove the worktree is checked by default. Orchestra never discards work: a checkout with uncommitted changes stays open, and a branch with unmerged commits is kept. Clear the checkbox to keep the worktree.

To understand what survives an app restart, read Saved workspace & resume.