AgentLayer▸docs
Workstation

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.

PiecePickWhy
TerminalGhosttyNative, fast, a single readable config, 25MB scrollback
MultiplexercmuxOne workspace per agent, notifications that say who is waiting
IsolationWorktreesParallel agents on one repo, no collisions
EditorVS CodeA viewer and tweaker; the terminal is the cockpit
Brain readercmux sidebar (Mac) · Obsidian (any OS)The sidebar keeps projects, reports and goals beside your terminals; Obsidian adds wikilinks, backlinks and the graph view
DocumentsMarkEditMarkdown to styled PDF
Git reviewTowerReviewing 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 siblings

The 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.

On this page