Workspace
Projects
The project rail, how agex finds each project's icon, opening a project in another app, and running its scripts.
A project in agex is a folder. Each one gets a tile in the project rail, its own sessions sidebar, and its own notes.
Add a project
- Drop a folder from Finder onto the agex window or its Dock icon, or use Finder's Open With.
- Press ⌘O and choose a folder.
- Run
agex .in a terminal to add the folder you're in. See Command line.
Files work too: a file dropped onto the window or the Dock icon opens in a tab of the project that holds it. Dropping files onto a terminal types their paths instead.
The project rail
The rail holds one tile per project. A tile shows the project's own icon when it has one (see Project icons), and your home folder gets a house on a graphite tile. To show each project's initial instead, turn off project_icons in settings.
Click a tile to switch to that project, or use ⌘1–⌘9 or ⌥⌘↑ / ⌥⌘↓. Drag tiles to reorder them.
Dots
A dot on a tile tells you about the agents in that project:
| Dot | Meaning |
|---|---|
| Orange | An agent is waiting for your answer. |
| Blue | An agent is working. |
| Green | An agent is done, with news you haven't looked at. |
Hover a tile with agents to see them listed beside it, as in the top bar's agent list: each one's task, what it's doing and for how long. Move into the list and click an agent to jump to it.
Right-click a tile
- Choose icon… picks a different icon for the tile.
- Reveal the project folder in Finder.
- Remove the project.
Dashed tiles
When an agent you started outside agex works in a repository that isn't a project yet, that repository gets a dashed tile in the rail. Click it to add the repository as a project; its agents move under it. See Agents running elsewhere.
Project icons
agex looks for the icon a project already uses, in this order:
- Icons the project declares:
<link rel="icon">andapple-touch-iconinindex.html, web and extension manifests,package.json(icon,build.icon), Expoapp.json,tauri.conf.json, and Flutterpubspec.yaml. - App icon sets: Xcode
AppIcon.appiconset, Android launcher icons, and macOS.icnsfiles. - Framework conventions, such as
app/icon.svg,public/apple-touch-icon.png,static/favicon.svgandsrc-tauri/icons/icon.png, including inside monorepoapps/*andpackages/*folders. - Files named
logo,iconor after the project, and anything in alogoorbrandfolder.
Candidates are scored by source, resolution and shape, so a 512px app icon beats a 16px favicon.ico. Wide banners and template images (vite.svg, next.svg, …) are skipped.
The winner becomes a 144px tile, cached in ~/Library/Caches/agex/icons:
- Icons that fill their square, like app icons, are used edge to edge.
- Transparent logos are trimmed, centered and placed on whichever background keeps them most legible: light, dark, or a deep tint of the logo's own color.
To see why an icon was picked, run:
agex --icon-report path/to/projectTo use a different icon, right-click the tile and choose Choose icon….
Open in
The split button in the top bar opens the project in Finder or in any editor or IDE found in your Applications folder, such as VS Code, Cursor, Zed, Xcode, JetBrains IDEs or Sublime Text. Each app shows its own icon.
It remembers your last choice. You can also open the project in an editor from the command palette (⇧⌘P).
Scripts
The ▶ button in the top bar lists the commands your project defines:
package.jsonscripts, run with bun, pnpm, yarn or npm, chosen from the lockfile.- Makefile targets, with their
##comments. - justfile recipes.
- Deno and Composer scripts.
- The usual Cargo and Go commands.
Click a script to run it in a new tab, or to jump back to its tab while it runs. Clicking ▶ on its own reruns the last script. When there's more than one source, each group folds to its heading.
While scripts run, the ▶ turns green and shows how many. A finished script's tab stays open so you can read its output.
To choose the package manager yourself, set scripts.package_manager to npm, pnpm, yarn or bun. Left empty, agex goes by the project's packageManager field or its lockfile.