Workspace
Agents
The agents in the sessions sidebar, what their rings and rows tell you, and how agex gets your attention when one needs you.
The sessions sidebar lists the project's agents first, then its terminals, with History pinned to the bottom.
Start an agent
Click New Claude Code in the sidebar to start your default agent in one click. The button is named after that agent, which is the first one agex finds unless you set agents.default. Click ▾ beside it to pick another agent, or press ⇧⌘T to start the default one.
The New agent menu (▾) lists the agent CLIs found on your Mac, through your login shell's PATH and common install folders. Only installed agents show up. After installing a new one, choose Rescan for agents in the menu. See Supported agents for the full list.
You can also start any detected agent from the command palette (⇧⌘P), or from a terminal with agex new.
Read an agent's state
The agent's row
Each agent's row shows:
- Its official logo on a round token, with a ring for its state (below).
- The task it reports.
- What it's doing right now, read from its screen: Editing
api-lobby.ts, Runningnpm test, or its last message. - How long it has been working, waiting, done or idle.
- The lines it has changed since it started, like
+48 −12. Click them to review the changes in Source control. - Its branch, when that differs from the project's.
- The ports of the servers it started. Click
:5173to open it in the browser. - A small meter for its context window, like
▬ 34%. See Context and cache.
States
| State | Ring | When |
|---|---|---|
| Working | A blue arc sweeps around the token | It's at work. |
| Done | Green | It went quiet with output you haven't looked at. Looking at it makes it idle. |
| Waiting | Amber | It's waiting for your answer: there's a question on screen. |
| Failed | Red | It failed. |
| Idle | No ring | It's quiet, and you've seen everything it printed. |
| Exited | The token fades | The agent has exited. |
The top bar's agent button
The agent button in the top bar counts agents across every project, as colored numbers: running (blue), done (green), idle (gray) and waiting for your answer (amber). A state with no agents is left out, and the button hides while no agent runs.
Click a count, or ▾, for the list. It has a tab per state, with agents grouped by project under each project's icon and name. Click a project to fold its group, and click an agent to jump to it. Hover a working agent to interrupt it (Esc).
Sub-agents and threads
Sub-agents
When an agent sends sub-agents to work, they're listed under it on a thin guide line: a spinner, what each was asked to do, and for how long. Hover one to see its kind and what it's doing (Reading auth.rs). Past three, the rest fold into +N more sub-agents.
A sub-agent leaves the list when it finishes, or when its record has been quiet for half an hour.
This works for Claude Code (its Task and Agent tool), OpenCode and Kilo Code, both for agex's agents and for agents running elsewhere.
Threads
Conversations branched off an agent's session are listed under it too, latest first: a branch glyph (a spinner while the thread is at work), its title, and how long ago it last changed. Past three, the rest fold into +N more threads.
Hover a thread to see when it branched off. Click it to switch to the agent that has it open, or to resume it in a new tab.
This works for Claude Code (/branch, /fork and --fork-session), Codex, OpenCode, Kilo Code and Pi, both for agex's agents and for agents running elsewhere.
When an agent needs you
Questions
When an 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.
The Dock icon shows how many agents are waiting on you. ⌘J jumps to the one that has waited longest, in any project, and then to agents that are done.
Notifications
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.
The notifications settings (⌘,) control all of this:
| Setting | Default | What it does |
|---|---|---|
notifications.enabled | true | Turns notifications on. Off turns everything below off. |
notifications.sound | "Glass" | A sound from /System/Library/Sounds, such as Glass, Ping, Hero or Submarine. "" is silent. |
notifications.on_finish | true | Notify when an agent finishes a task you gave it. |
notifications.on_question | true | Notify when an agent asks for permission or a choice. |
notifications.popups | true | Popups in the corner of the window. |
notifications.system | true | macOS notifications while agex is in the background. |
notifications.dock_badge | true | The number of agents waiting on you, on the Dock icon. |
notifications.dock_bounce | true | Bounce the Dock icon when an agent starts waiting on you. |
Your own scripts can notify you too: agex notify "Build finished" shows a popup with a sound. See Command line.
Menu bar icon
The agex mark sits in the macOS menu bar, with the number of agents waiting on you next to it. Its menu lists every running agent, in agex or outside it, with the ones waiting on you first. Each has a colored dot, its project, its state and for how long. Click one to jump to it.
The menu also opens or hides agex, starts a new agent, toggles keep awake and opens settings.
- To hide the icon, use its own menu, choose Agex › Hide Menu Bar Icon, or
⌘-drag it out of the menu bar. - To bring it back, choose Agex › Show Menu Bar Icon, run agex: Show Menu Bar Icon in ⇧⌘P, or turn on
menu_bar.visible. - To hide the count next to it, turn off
menu_bar.waiting_count.
Interrupted agents
When agex quits, or crashes, while agents are still running, it lists those agents under their project the next time it opens. Each shows its title, how long ago it was cut off, and what it was doing then: Stopped mid-task, Was waiting for your answer or Was ready for a task.
- Click one to resume its session in a new tab, in the folder it ran in.
- Hover one to dismiss it instead.
- Click Resume all in the heading to reopen every one.
Only agents cut off this way are listed, not all of History, and they leave History while they're listed. An agent you closed, or that ended on its own, isn't interrupted.
This works for the agents History can resume: Claude Code, Codex, Copilot CLI, Kiro CLI, OpenCode, Crush, Kilo Code and Pi. They stay listed until you resume or dismiss them, for up to a week. agex keeps them in ~/.config/agex/agents.json.
From a terminal, agex interrupted lists them, with resume-all and dismiss <n>. See Command line.
Terminals
Below the agents, the sidebar lists the project's terminals. Press ⌘T for a new one. Each row shows:
- What's actually running, like
npm run devorcargo watch, and for how long. - The folder and branch, when they differ from the project's.
- The ports its processes listen on. Click
:5173to open it in the browser.
A terminal whose session ended shows its exit code.
Reorder and right-click
Drag agents and terminals to reorder them.
Right-click an agent or terminal to:
- Open its ports.
- Interrupt or restart it.
- Open a terminal in its folder.
- Copy its path or command.
- Reveal it in Finder.