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

Kevin 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	Obsidian	Wikilinks, backlinks, graph view over the home
Documents	MarkEdit	Markdown to styled PDF
Git review	Tower	Reviewing what three agents did across three worktrees

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
├── Kevin/                       #   the personal agent: knowledge + projects, no code
│   ├── knowledge/  projects/  reports/
│   ├── SOUL.md / IDENTITY.md / USER.md
│   └── .git  →  gitdir pointer (internals live in the code tree)
└── 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
└── agent-acme-data.git          #   the brain's git internals, out of the vault

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 git internals sit outside the vault via git init --separate-git-dir, so the vault keeps a one-line .git pointer and sync tools only ever see markdown.

Wake an agent by launching your host from ~/Documents/Agents/<Name>. Point it at code through additionalDirectories, not by launching from the repo. See Onboarding.

The rig

Folder structure

On this page