agex
Docs menuAgents

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, Running npm 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 :5173 to open it in the browser.
  • A small meter for its context window, like ▬ 34%. See Context and cache.

States

StateRingWhen
WorkingA blue arc sweeps around the tokenIt's at work.
DoneGreenIt went quiet with output you haven't looked at. Looking at it makes it idle.
WaitingAmberIt's waiting for your answer: there's a question on screen.
FailedRedIt failed.
IdleNo ringIt's quiet, and you've seen everything it printed.
ExitedThe token fadesThe 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:

SettingDefaultWhat it does
notifications.enabledtrueTurns 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_finishtrueNotify when an agent finishes a task you gave it.
notifications.on_questiontrueNotify when an agent asks for permission or a choice.
notifications.popupstruePopups in the corner of the window.
notifications.systemtruemacOS notifications while agex is in the background.
notifications.dock_badgetrueThe number of agents waiting on you, on the Dock icon.
notifications.dock_bouncetrueBounce 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.

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 dev or cargo watch, and for how long.
  • The folder and branch, when they differ from the project's.
  • The ports its processes listen on. Click :5173 to 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.