The rig
Optional. Running agents well is less about the model and more about the terminal, the keybindings, the worktrees, and where the brain lives.
Optional and opinionated
Your agent runs anywhere its host does. This section is the setup the author actually uses on a Mac, offered as a starting point. Linux and Windows have equivalents for most of it.
| Piece | Pick | Why |
|---|---|---|
| Terminal | Ghostty | Native, fast, a single readable config, 25MB scrollback |
| Multiplexer | cmux | One workspace per agent, notifications that say who is waiting |
| Isolation | Worktrees | Parallel agents on one repo, no collisions |
| Editor | VS Code | A viewer and tweaker; the terminal is the cockpit |
| Brain reader | cmux sidebar (Mac) · Obsidian (any OS) | The sidebar keeps projects, reports and goals beside your terminals; Obsidian adds wikilinks, backlinks and the graph view |
| Documents | MarkEdit | Markdown to styled PDF |
| Git review | Tower | Reviewing what three agents did across three worktrees |
The everyday view is the AgentLayer sidebar in cmux. It keeps every running session, and your agent's projects, reports and goals, beside your terminals.
Folder structure
Agent brains are standalone vaults under ~/Documents/Agents/. Code lives flat under ~/Developer/. Never nest one inside the other.
~/Documents/Agents/ # every agent brain lives here
├── Oppi/ # the personal agent: knowledge + projects, no code
│ ├── knowledge/ projects/ reports/
│ ├── SOUL.md / IDENTITY.md / USER.md
│ └── .git # its version history, or a one-line link to it
└── Acme/ # a forked company agent, same shape
~/Developer/Acme/ # that company's code root: flat, no brain
├── repo-one/ # main checkout
└── repo-one-my-feature/ # worktrees as siblingsThe brain opens cleanly as an Obsidian vault with no source tree to index, many brains can run against one code tree, and ~/Documents sync never drags repos along.
The brain's version history is set up for you by the history skill. It sits in .git inside the home, or, when the home is in a synced folder, on this computer under ~/.local/state/agentlayer/ with a one-line .git link left in the home, so a sync service never touches it. See History.
Wake an agent by launching your host from ~/Documents/Agents/<Name>. Point it at code through additionalDirectories, not by launching from the repo. See the one convention.