Projects & sessions
How projects, sessions and restarts work.
Projects
A project is a folder on your Mac. Add one with Open project folder (⌘O), the + in the sidebar, or by dropping a folder on the window. Rename or remove projects from the … menu next to each one. Removing a project from CodeHerd never touches its files.
Drag projects in the sidebar to put them in the order you like, or use Move Up and Move Down in a project's … menu (it opens with the keyboard too). The order is remembered.
Switch projects with the sidebar or ⌃⌘↑ / ⌃⌘↓. Agents in other projects keep running in the background.
Sessions
Each pane runs one session: one agent, in the project folder (or its own git worktree). The pane header shows the agent, its status and, for worktree sessions, the branch.
Every session is also an agent with a name: Ada, Bo, Cleo and so on, given in order when the session starts, each with its own colour. The name shows in the pane header, the sidebar, notifications (“Ada (Claude Code) is waiting for you”), search and Herd HQ, so you can tell your agents apart everywhere. Rename an agent from Rename… in its sidebar menu.
To name what a session is working on, double-click its title in the pane header (or choose Session → Rename Session…), type a name and press ↩. Esc cancels, and an empty name goes back to the agent's name. The name also shows in the sidebar and is kept across restarts.
| Status | Meaning |
|---|---|
| Running | The agent is running. |
| Exited | The agent finished on its own (with its exit code). |
| Crashed | The agent was ended by a signal it did not expect. |
| Stopped | You stopped it, closed its window, or quit CodeHerd. |
| Interrupted | CodeHerd quit unexpectedly while it was running. |
Files
Show Files (⇧⌘E, or the folder button in a session's title bar) opens the folder the active session works in beside your panes. Click a file to view it, change it, and press ⌘S to save; ⌘F searches it. The plus button makes a new file in the folder you last picked, which is handy for a .env you'd rather fill in yourself than give to an agent.
If an agent changes a file you have open, it reloads by itself; if you have unsaved edits, CodeHerd asks whether to keep yours or theirs instead. For a session in a git worktree, the switch at the top shows the project's own folder instead: a worktree has its own copies of your .env files.
Restarting
Every ended session has a Restart button, and ⇧⌘R restarts the active one. When you reopen CodeHerd, your layouts are restored and each session waits for you to restart it. Nothing is relaunched behind your back.
Closing
Closing a pane (⌘W) stops its session and everything it started: child processes, background jobs, dev servers. If a session is still running, CodeHerd asks first.