How do I open a project in a quadrant?

You open a project by pinning its folder. An empty quadrant shows one button at the top: 📁 pin a worktree. Click it, and the standard Mac folder chooser opens. Go to your project folder (or make a new one with New Folder), then click Open. The folder is now pinned: its name shows as a small chip at the top, the agent works inside it, and codus remembers the choice the next time you open the app. The button says "worktree", but any folder on your Mac works; it does not have to be a git worktree. Pin the folder before you start an agent, because the start button only appears once a folder is pinned, and pinning by itself does not launch the agent; you still click start to do that.

The folder chip: change or unpin

Once pinned, the folder's name sits in the quadrant header as a chip with a small ▾ next to it (and the git branch, if the folder is a repo). Hover it to see the full path. Click it for a two-item menu: change folder… swaps in a different project and reopens the same chooser, and unpin empties the quadrant, brings back the 📁 pin a worktree button, and asks for no confirmation. Both are reversible. One catch: change folder… does not tidy the folder you leave, so it keeps the block codus wrote into its CLAUDE.md (below). Only unpin removes that.

One folder, one quadrant

codus will not pin the same folder to two quadrants at once, because both agents would share one task list and tread on each other's work. Pick a folder another quadrant already holds and you get a notice; the folder stays unpinned and the quadrant keeps what it had. The name and quadrant number will match yours:

"my-project" is already open in Q3. Open it in only one quadrant — for a parallel agent on the same project, use a git worktree (ask the Brain) instead.

To run a second agent on one project, give that quadrant its own separate folder (a git worktree). Ask the Brain, codus's coordinator, to make one for you.

Pinning edits CLAUDE.md

When you pin, codus adds a short ## codus integration block to the folder's CLAUDE.md, creating the file if there is none. It sits between codus:begin and codus:end comment markers, tells the agent how to behave inside codus, and leaves anything you wrote untouched. Because CLAUDE.md is a normal project file, the block shows up in git (git status, git diff); that is expected, not a bug. unpin removes it again. If you run Codex instead of Claude, codus writes the same block into AGENTS.md.