Your first project

Add a project

Open Sirio and click the + at the top right of the sidebar, on the Projects tab. It offers Open Project…, Clone Repository… and Create Project…. Pick a git repository and Sirio reads its worktrees, the checkout itself and any you created with git worktree add, and lists each one as a card under the project’s name, titled with its branch.

A folder with no git repository asks whether to Initialize Git, Add without Git or Cancel, so a plain folder can be a project too. The project’s header counts its worktrees, and its own + creates a new worktree from a branch name.

Open a worktree

Click a worktree’s card. The centre of the window starts with one pane. A worktree you open for the first time holds no tabs yet, so that pane shows two tiles, Terminal and Chat. A second pane opens on its right when you put something in it, and the Open view of the right panel lists what you can open there: Terminal, Chat, Browser, Changes, Open File and Project Settings.

A worktree stays mounted once you open it: its terminals, its chats and the processes in them keep running when you select another card, and come back when you return.

Launch an agent

Click Chat and a menu opens under the tiles with the agents that can start a chat here: OpenCode and Oh-My-Pi when their CLI is on your PATH, and Claude Code, Codex, Pi or OpenCode once you install its adapter in Settings → Agents. Pick one and its chat opens in that pane. Other agents… at the end of the menu opens Settings → Agents, and when no agent is available the menu says “No supported agent found on PATH”. A chat opened from the Open view lands in the right pane.

Once a tab is open, the + in the tab strip offers New Terminal and New Chat with the same list of agents, and right-clicking a worktree’s card in the sidebar offers them too. To run an agent in a terminal instead, open a Terminal and type the agent’s own command, such as claude. A chat and a terminal are two ways to run the same agent, described in Agent chats. A terminal or a chat can also move to the other pane: right-click its tab and choose Move to Right Pane or Move to Left Pane.

A chat reports its own progress to Sirio, so it needs no setup. For an agent you start by hand in a terminal, Sirio reads its state from the terminal’s title, its output and its process. Settings → General → Install Hooks adds Sirio’s hooks to the user-level configuration of Claude Code, Codex and OpenCode, in places such as ~/.claude and ~/.codex, so an agent you start that way reports its state directly. Sirio writes to those files only when you press that button; see Hooks and sirioctl notify.

Read the sidebar

Each worktree card shows the state of its agents with a mark beside its title:

• Running: a green bloom that keeps moving. The agent is working.
• Needs input: a still amber bloom. The agent asked a question or is waiting for a permission.
• Done: a still green bloom. The agent finished.
• Error: a still red bloom. The agent stopped on a failure.
• Idle: no bloom. The card reads idle, or a count such as “3 agents” when the worktree holds several terminals or chats.

A worktree you switch away from keeps its mark for as long as its agent works, and each card shows only its own agents. Inside each project, a worktree with an error rises to the top, then one that needs input, and the rest keep the order you gave them. The same states drive the tray roster and desktop notifications; see Activity states.

The Sessions tab, beside Projects at the top of the sidebar, lists every agent session across all your projects in one place, most recently active first. It keeps the chats you closed under Closed, so you can reopen one. While Projects is showing, the Sessions tab carries a small dot when a session needs input or has hit an error. Sidebar and Sessions covers both tabs in full.