Getting started
This walkthrough takes you from a fresh installation to an agent session you can leave working and return to when it needs you.
Before you start
- A Mac with Apple silicon running macOS 26 (Tahoe) or newer.
- Homebrew for installing Saggar.
- A local project directory. A Git repository works, but isn't required.
- A supported agent CLI, already signed in and ready to use.
Saggar runs your normal shells in your project directories. It doesn't replace the agent or install one without asking.
Install Saggar
brew install --cask mcclowes/saggar/saggar
Open Saggar from Applications and complete the welcome screens. Select the agent CLIs you use and choose whether to install their optional Saggar integrations. You can revisit both choices in Settings ▸ Providers.
Open a project
Press ⌘⇧O and choose a project directory. It appears in the Project menu, with its sessions nested beneath it.
If Saggar has already discovered the repository, press ⌘K, type its
name, and select it. You can also install the saggar shell command from
Settings ▸ CLI, then run saggar . inside a project.
Start an agent
Press ＋ on the project's row in the Project menu and select your agent. In the Initial task field, enter a small read-only request:
Describe this project in five bullets. Don't change any files.
Start the session. Saggar opens it in the project directory, launches the provider, and sends the task once the agent is ready.
Starting the CLI yourself in a plain terminal works too, but the initial-task field is the shortest path for a new session.
Watch the session change state
The session gains an agent label and reports one of five states:
- Working means the agent is active. Leave it alone.
- Needs you means a prompt or question is waiting.
- Idle means the agent is ready for another instruction.
- Finished means the process ended successfully.
- Failed means the process ended with an error.
If the agent changes files and then becomes idle, Saggar may show Ready for review. That is a reading of the session and its worktree, not another process state. Status and triage explains the full model.
Respond when the agent needs you
If the agent asks a question or requests permission, the session turns amber and an attention card shows the prompt. Select an answer on the card, or open the session and respond in the terminal.
Press ⌘J to move to the next session with a claim on you. With one session this simply returns you to the waiting agent; later, the same command walks a queue across every project.
Provider integrations make status and prompt detection more exact. If the session isn't updating, install or refresh the integration in Settings ▸ Providers, then follow Troubleshooting if needed.
Finish the loop
Read the agent's answer, then send one short follow-up. When it returns to Idle, you have completed the basic Saggar loop:
- Give one task to one session.
- Leave it while it is Working.
- Return when it Needs you or finishes.
- Review the result before closing the session.
Next, open another independent task and follow Run parallel agents well. For a guided piece of real work, choose one of the workflow recipes.