agex
Docs menuProjects

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:

DotMeaning
OrangeAn agent is waiting for your answer.
BlueAn agent is working.
GreenAn 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:

  1. Icons the project declares: <link rel="icon"> and apple-touch-icon in index.html, web and extension manifests, package.json (icon, build.icon), Expo app.json, tauri.conf.json, and Flutter pubspec.yaml.
  2. App icon sets: Xcode AppIcon.appiconset, Android launcher icons, and macOS .icns files.
  3. Framework conventions, such as app/icon.svg, public/apple-touch-icon.png, static/favicon.svg and src-tauri/icons/icon.png, including inside monorepo apps/* and packages/* folders.
  4. Files named logo, icon or after the project, and anything in a logo or brand folder.

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/project

To 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.json scripts, 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.