agex
Docs menuAgents running elsewhere

Workspace

Agents running elsewhere

How agex finds agents you started outside it, which project they belong to, and what it can tell about them.

agex also shows agents you started outside it: in Terminal, iTerm2, Ghostty, an editor's terminal or extension, tmux, the Claude app, and so on. You don't have to move your work into agex to see what every agent is doing.

To stop showing them, turn off agents.detect_external in settings.

Which project claims an agent

An agent running elsewhere belongs to the repository it runs in. A worktree counts as its main checkout. A folder that merely holds repositories, like your home folder, doesn't claim them.

When that repository isn't a project yet, it gets a dashed tile in the project rail and a group in the top bar's agent list. Click either one to add the repository as a project, and its agents move under it.

Outside any repository, the agent belongs to the deepest project that contains its folder.

Where they show up

Agents running elsewhere are listed in their project's sidebar, after agex's own agents. They also count in the top bar's agent counts, on the rail's dots and in the menu bar icon's list.

Each one shows the app it runs in and the ports of the servers it started. Click one to switch to that app; in Terminal and iTerm2, agex switches to its exact tab.

Their sub-agents and threads are listed under them, as for agex's own agents (see Sub-agents and threads), and the status bar's other-agents list includes them (see Context and cache).

While they run, their sessions are left out of History.

Background sessions

A Claude Code background session, started with claude --bg and run by claude daemon, has no app. agex shows it as running in the background.

Click it to open a tab here that runs claude attach on it, or to bring back the tab that's already attached to it. That tab isn't counted as a second agent, and neither is a shell where you typed claude attach yourself.

How agex reads their state

agex can't read the screen of an agent running in another app, so it goes by what the agent writes down:

AgentWhat agex reads
Claude CodeIts session file and transcript give its state (working or idle), its task and its last action.
CodexIts records give its first prompt.
Other agentsCPU use counts as working.

An agent that stops working while its app isn't in front turns done, until you click it.

What doesn't count

  • One-shot runs, such as claude -p and codex exec.
  • Servers.

Right-click an agent

Right-click an agent running elsewhere to:

  • Switch to it.
  • Open a terminal where it works.
  • Add its project.
  • Copy its path, its resume command (its attach command, for a background session), its session ID or its process ID.