I build NestMux, a desktop app that runs Claude Code, Codex, Gemini CLI, Copilot and OpenCode in a grid of real terminals, each with its own account and its own git worktree. This is how it works inside, including the parts that are heuristics wearing a confident UI and the parts that do not survive a restart.
If you are building something similar, most of this transfers. If you are deciding whether to use it, this is the honest version of what it does.
Thirty-five seconds of it running, so the rest of this has something to attach to:
The unit is a pane, and a pane is smaller than you would think
Every cell in the grid is described by a plain object. Simplified, and this really is most of it:
interface PaneNode {
id: string
aiType: 'claude' | 'codex' | 'gemini' | 'copilot' | 'opencode' | 'terminal' | 'custom'
accountName: string
accountDir: string // becomes HOME for this pane's processes
cmd: string // '' means a plain shell
repoPath?: string // cwd override: the worktree this pane works in
shellId?: string // which shell to spawn on Windows
borderColor: string
}
There is no AI-specific code behind any of it. A pane spawns a shell with node-pty, redirects HOME to accountDir, sets the cwd to repoPath, and types cmd into it. Claude Code is a pane whose cmd is claude. A plain terminal is a pane whose cmd is empty. Adding support for a new agent CLI is a row in a list, which is why custom CLIs are a user-facing feature rather than a release.
The reason it is worth saying out loud: everything below is about the environment around the process, not about the agent. We do not parse the agent's output, we do not wrap its API, and we do not know what it is doing. It is a program in a terminal.
The two things that make it more than five terminals are what accountDir and repoPath are pointed at.
accountDir is an isolated HOME, so two panes can be signed into two different Claude accounts at once, and ~/.claude means something different in each. repoPath is a git worktree, so four agents editing the same repository do not overwrite each other. I wrote up the Windows specifics of both separately, because that part is genuinely fiddly and not interesting here.
Broadcast is four lines and that is the good part
Sending one prompt to every pane sounds like it needs a protocol. It does not. The terminal emulator already hands you every keystroke:
term.onData((data) => {
const targets = broadcastMode ? panes.map(p => p.id) : [pane.id]
targets.forEach(id => window.pty.write(id, data))
})
That is the whole feature. Because it operates on raw input rather than on a message, it works with anything that reads a terminal: agents with their own TUI, a REPL, git rebase -i. Nothing had to be taught about it.
The cost of that simplicity is real and worth stating. It broadcasts everything, including Ctrl+C and arrow keys. It does not check whether a pane is ready, so if one agent is still booting it gets your prompt as input to whatever prompt it happens to be showing. There is no "wait for all panes to be idle". That is a design position, not an oversight: the moment you add readiness detection you are parsing agent output, and then every CLI update can break you.
Attribution is the part that is actually hard
Showing CPU, memory and open ports per pane sounds like bookkeeping. It is the hardest thing in the app.
The problem is that the pane's own process is a shell, and nobody cares about the shell. The agent is its child. The dev server the agent started is a grandchild, or worse, has been reparented and is nobody's child at all. If you measure the PID you spawned, every pane reads about 77 MB and looks idle.
So you resolve the whole tree per pane, per polling cycle. On Windows that means one Get-CimInstance Win32_Process snapshot for the entire machine, cached for a second and a half and shared by everything that needs it in that cycle, then walked in memory. (Why not pidtree is its own story.)
And when the parent link is gone, which on Windows it frequently is, the fallback is the filesystem:
const prefix = rootPath.toLowerCase().replace(/\\/g, '/').replace(/\/+$/, '') + '/'
for (const [pid, path] of snap.pathByPid) {
if (path.toLowerCase().replace(/\\/g, '/').startsWith(prefix)) out.add(pid)
}
If a process's executable path or command line points inside a worktree, that process belongs to that worktree's pane. For processes that do not carry the path either, there is a third pass that reads each process's current directory, which on Windows means going through ntdll because there is no API for it.
Be clear about what this is: a heuristic. It attributes correctly for the common cases and it misses elevated processes and processes from other users, because OpenProcess refuses them. The resource bar is a good signal and it is not accounting.
Reviewing is a git command and a parser
Four agents produce four diffs, and the first version of this app made you read them with git diff in a fifth pane. The diff viewer is deliberately thin:
execFile('git', ['-C', worktreePath, 'diff', '--no-color', '--unified=3', base])
Then parse the unified diff into files and hunks in about a hundred lines. No library, no server, no LSP.
Two decisions in there that matter more than the parsing. Files over 10,000 lines get marked oversized and are not rendered, because one regenerated lockfile will otherwise freeze the renderer while it builds a hundred thousand DOM rows. And base defaults to HEAD, which means what you see is uncommitted work. That is the right default for reviewing an agent that just finished, and it is the wrong one if the agent committed as it went, which several of them now do by default. You can pass another base. Most people do not know that, which is a UI failure rather than an engine one.
What survives a restart, and what does not
session.json holds the pane descriptors. Types, account names, colors, repo paths, layout, tab structure. It is written atomically, serialize first, write to a temp sibling, rename over the real file, because a crash mid-write used to leave truncated JSON that failed to parse and took the whole workspace with it.
What it does not hold is any terminal state. Scrollback lives in memory in the main process and dies with the PTY. Reopening the app respawns the panes and re-runs the CLIs. Your grid comes back, your agents restart, and the conversation on screen is gone.
In practice that hurts less than it should, because the agents keep their own histories and most of them can resume a session. But it is a real limit and the app does not pretend otherwise: the panes are containers for processes, not a saved document.
What I would fix first
The thing the app is worst at is the thing this whole design makes hardest. Every pane is an opaque process, which is why adding a new agent is trivial. It is also why there is no unified log: no single timeline with timestamps and exit codes across panes, telling you which agent touched which file and in what order. There is a per-pane transcript you can export and that is all.
That gap is the price of not parsing agent output, and I have not found a way to close it that does not involve becoming a wrapper around each CLI. Filesystem watching per worktree is the obvious idea and it tells you what changed without telling you who did it. If you have a better one, that is the comment I want.
NestMux runs on Windows 10 and up, macOS 13 and up, and Linux, same build on all three, local-first with no telemetry. It is at nestmux.com, free during launch.
