Start
Quickstart
Add a project, start your first agent, follow its state, answer its questions and resume a past session.
This walkthrough takes you from an empty window to an agent at work, and back to it after it finishes. It assumes you've installed agex and have at least one agent CLI, such as Claude Code or Codex, installed.
Run your first agent
-
Add a project. Do any of these:
- Drop a folder from Finder onto the agex window or its Dock icon. Finder's Open With works too.
- Press ⌘O and choose a folder.
- In a terminal,
cdinto the folder and runagex ..
The folder gets a tile in the project rail, with the project's own icon when it has one.
-
Start an agent. In the sessions sidebar, click New Claude Code. The button starts your default agent, which is the first one agex finds unless you set
agents.default, so it may name a different agent. Click ▾ beside it to pick another, or press ⇧⌘T.The agent starts in a tab of the project.
-
Give it a task. Type into the agent as you would in any terminal. ⇧↵ adds a newline to your prompt instead of sending it.
-
Read its state. The agent's row in the sidebar shows its logo on a round token. The ring around it tells you what it's doing:
Ring Meaning Blue arc sweeping around Working Green Done: it went quiet with output you haven't looked at Amber Waiting for your answer Red Failed No ring Idle: quiet, and you've seen everything it printed The row also shows the task it reports, what it's doing right now (Editing
api-lobby.ts, Runningnpm test), for how long, and the lines it has changed (+48 −12). -
Answer a question from the sidebar. When the agent asks for permission or a choice, the question and its options appear right in the sidebar. Click an option to answer without switching tabs. This works for the numbered prompts of Claude Code, Codex and Gemini CLI.
-
Jump to whoever needs you. Press ⌘J to go to the agent that has waited longest for your answer, in any project. With nobody waiting, it goes to agents that are done. The Dock icon shows how many agents are waiting on you.
-
Let notifications find you. When an agent you aren't looking at finishes a task you gave it, or stops to ask you something, agex plays a sound and shows a popup in the corner of the window. Click the popup to jump to the agent. While agex is in the background, you also get a macOS notification. See Notifications to change what notifies you.
-
Resume a past session. At the bottom of the sidebar, History lists the project's past sessions, newest first. Click its heading to unfold it, then click a session to resume it in a new tab. See History.
Start an agent from a terminal
You can do steps 1 and 2 from any terminal:
cd ~/code/app
agex .
agex new claude "fix the failing test"agex new prints the agent's id. agex wait <id> then waits until its task ends. See Command line.
Where to go next
- Agents explains everything in an agent's row, sub-agents, threads and the menu bar icon.
- Agents running elsewhere covers agents you started in Terminal, iTerm2, tmux or an editor.
- Context and cache shows how full each agent's context window is.
- Notes gives each project a to-do list your agents can read and update.