diriThis page takes you from a fresh install to a working agent in a few minutes. If you have never used a coding agent before, the slower walkthrough in Your first agent explains each step.
1. Install diri
Install with Homebrew or the DMG. You need macOS 15 or newer. See Install for Linux and details.
brew install --cask cristicretu/diri/diri2. Add an agent
diri runs the agent CLIs already on your machine. On first launch it checks which ones are installed.
- If none are found, the welcome screen says "Install a coding agent to get started." and lists a few agents with an Install button.
- Click Install. diri shows the agent's official install command in a confirmation sheet. Click Install again and it runs in a new terminal tab you can watch.
- Sign in once. Start the agent and follow its own sign-in steps. diri never handles agent passwords.
The one-click install covers Claude Code, Codex, Gemini CLI and OpenCode. More agents… opens Settings → Agents, which lists every supported agent. If you install an agent while diri is open, click Refresh there. If one still is not detected, use Add… on its row to choose the executable.
3. Pick a folder
An agent works inside one folder and can change files there.
- On the welcome screen, click Choose a folder….
- Or open New Agent at the top of the sidebar, click the folder row at the bottom (the Where panel), and choose a recent folder or Choose Folder….
diri remembers every folder you use, so next time it is one click. A folder that is a git repository can also give each agent its own worktree; see Worktrees and review.
4. Start a session
| Way to start | What it does |
|---|---|
| New Agent in the sidebar | Pick an agent from the ones installed |
| ⌘T | Start the default agent right away |
| ⌘N | Open the launcher: pick project and agent, type the first prompt |
| ⌥⌘T | Start a plain terminal |
Set the agent ⌘T uses in Settings → General → Default agent. The new session opens on the right with the agent's own screen, and a row appears in the sidebar. Type your task and press Return.
5. Read the sidebar
The mark on the left of each row shows what the session is doing. The agent's logo is on the right.
| Mark | Meaning |
|---|---|
| Spinning | Working. Leave it alone. |
| Amber | Needs you: a question or a permission prompt |
| Green | Done, and you have not looked yet |
| Grey | Idle, or done and already seen |
| Moon | Hibernated to save memory. Open it to wake it. |
Sessions covers the full status model.
6. Answer when it asks
When an agent needs you, its row turns amber and diri sends a notification.
- Press ⇧⌘J to jump to the next session that needs you, or click the row.
- Answer in the agent's screen. Permission prompts usually take the arrow keys and Return.
- For a plain question, you can reply from the macOS notification with Reply.
The bell (⇧⌘I) collects every "needs you" and "finished" moment.
7. Quit without losing anything
Each session runs in its own background process, not inside the window. Quit diri (⌘Q) and reopen it later: agents that were working are still working, with their full screen history. The same holds when diri updates its background Engine.
A restart of your Mac does stop agents. Their sessions then offer Resume, which continues the same conversation for agents that support it. Never lose your work explains what survives and what does not.
Next steps
- Sessions: status, sidebar, history, resume and terminal features.
- Worktrees and review: parallel agents on separate branches, and reviewing their changes.
- Keyboard shortcuts: every binding.
- Run several agents at once and Let agents work as a team.