NTM (Named Tmux Manager): Running Claude, Codex and Gemini Agents in Labelled Tmux Swarms

The gap NTM targets: tmux panes without a control plane

Plain tmux solves the display problem. It gives you panes, and it does not care what runs inside them. Once you are running three or four coding agents at once, the display problem is the easy part. The hard part is remembering which pane holds which agent, which agent owns which files, what you asked each one to do, and what the state looked like before the last round of edits. The README states the problem directly: tmux gives you panes but not durable coordination, work selection, safety policy, approvals, history, or a shared control model that both humans and agents can use.

NTM is aimed at the operator who already accepts that workflow. It is a single Go binary that treats a tmux session as a named unit with labelled agent panes plus a user pane, and then layers coordination on top. The intended audience is narrow but specific: developers running Claude Code, Codex, Antigravity CLI or Grok Build side by side on the same repository, who want the swarm to be inspectable and scriptable rather than a pile of terminals. If you run one agent at a time, the coordination layer has nothing to coordinate.

How the named session, agent labels and dispatch model fit together

The core object is a named tmux session. ntm quick scaffolds a project directory from a template, and ntm spawn creates the session with a requested count of each agent type. Agent types are addressed by short flags: --cc for Claude Code, --cod for Codex, --agy for Antigravity CLI, --grok for Grok Build. The README notes Gemini CLI is supported as legacy. Panes get labels, so a single project directory can host several coordinated swarms, for example a backend label and a frontend label, and ntm add extends an existing labelled group.

Dispatch is pane-directed rather than conversational. ntm send takes a session and an agent selector plus a prompt, which means the operator decides who works on what instead of broadcasting. Around that sit the coordination pieces: Agent Mail for human overseer messages and inbox views, file reservations so agents declare ownership of files or areas, and worktrees for filesystem isolation. The README is explicit that reservations and worktrees are complementary rather than redundant. Reservations communicate intent and produce an auditable ownership record; worktrees provide the separate checkout boundary, one ntm/<session>/<agent> branch per agent, so destructive Git operations stay contained until you merge deliberately.

The automation surface is the part that distinguishes NTM from a shell script full of tmux commands. The README lists robot JSON output via flags such as --robot-snapshot, a REST API started with ntm serve, SSE and WebSocket streams, and OpenAPI generation. That means a script or another agent can query session state without parsing terminal output. The repository layout backs this up: go.mod pulls in go-chi/chi and gorilla/websocket for the server side, modernc.org/sqlite for local storage, and the Charm stack (bubbletea, bubbles, lipgloss, huh) for the TUI dashboard and command palette. The package.json confirms a separate web front end under web/ with its own dev, build and test scripts.

Install and a first real session

The README gives a one-line installer that pipes a script from the repository into bash. It passes --easy-mode, and the URL includes a cache-busting timestamp so you do not get a stale copy.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode

Piping a remote script into a shell is a choice you should make deliberately. The alternative the repository supports is building from source: the Makefile defines build and install targets, and the Dockerfile builds the binary with CGO_ENABLED=0 and installs tmux, bash and zsh into an Alpine runtime image. The Dockerfile also appends the shell integration line to ~/.bashrc and ~/.zshrc, which tells you the shell hook is expected in normal use.

After install, enable shell integration and check what is actually present on the machine. ntm deps -v is the sanity check the README recommends, and it matters because NTM is a pure Go project with an integration-heavy runtime: tmux is required, and the agent CLIs are only useful if they are installed and authenticated.

eval "$(ntm shell zsh)"
ntm deps -v

From there, scaffold a project and launch a mixed swarm. The template flag picks the project scaffold, and the spawn flags set how many panes of each agent type to create.

ntm quick api --template=go
ntm spawn api --cc=2 --cod=1 --agy=1

With the session up, the two live operator surfaces are the dashboard and the command palette. The README presents them as the way to watch and drive the swarm without memorising command names.

ntm dashboard api
ntm palette api

Work is dispatched per agent, and state is captured before anything risky. A checkpoint is the recovery point the README reaches for before a refactor.

ntm send api --cc "Map the auth layer and propose a refactor plan."
ntm checkpoint save api -m "before auth refactor"

Finally, the local API. ntm serve binds a port, and the robot snapshot flag returns machine-readable session state for scripts.

ntm serve --port 7337
ntm --robot-snapshot

If the repository uses br and bv, ntm work triage --format=markdown renders the work graph as a document you can read before assigning anything.

Worktree isolation, reservations, and where the seams are

The worktree feature is the most consequential design decision in the README, because it changes what an agent can break. With --worktrees, each agent gets its own branch and checkout, and the lifecycle is explicit: list, merge a named agent branch, then clean the session. That is a real safety boundary, but it is also a merge burden. Three agents on three branches means three reviews and three merges, and the README's own guidance is to merge reviewed branches into main and clean up afterwards. Teams that expected parallel agents to reduce integration work will find the integration work simply moved.

The more interesting limitation is Grok Build. The README calls the support phase one and enumerates what is covered: configuration, model and --effort arguments, launch, adopt, exact process discovery, status and count projections, and topology-only saved-session restore. Then it enumerates what is not claimed: authenticated fullscreen-TUI readiness, automated prompt delivery and assignment, interrupt-with-message, restart, and restore-time process relaunch. Those operations fail closed before any pane mutation, and the README tells you to interact with an authenticated Grok pane directly. Robot flags --spawn-wait and --spawn-assign-work also fail closed for Grok panes. This is a defensible choice: failing closed beats half-mutating a pane. But it means a Grok-heavy workflow gets less automation than the flag list suggests, and the failure will look like a refused command rather than a partial success.

A second seam is the dependency surface. NTM does not ship an agent. It orchestrates whatever CLIs you have. The README lists br, bv, Agent Mail, cass, dcg and pt as optional but powerful, and ntm deps -v as the way to see what is missing. Every one of those is a separate install with its own authentication and its own failure modes, and a missing optional tool degrades a feature rather than stopping the session.

Where NTM is the wrong tool, and what it is not replacing

If you want a graphical multi-agent workspace with a hosted backend, NTM is the wrong shape. It is a local binary that drives tmux, and its web/ directory is a front end for the local API, not a hosted product. The README lists no homepage, and the install path is a curl pipe or a source build.

If your agents do not run in a terminal, NTM has nothing to attach to. The whole model assumes tmux panes and CLIs that accept prompts on a command line. An IDE-embedded agent or a hosted API agent sits outside that boundary.

If you are not already fluent in tmux, the learning curve is real. NTM adds naming, labels, dashboards and a palette on top of tmux, but it does not hide tmux. The Dockerfile installs bash and zsh and wires the shell hook into both rc files, which is a fair signal that the intended user lives in a shell.

A concrete alternative is a plain tmux session driven by a hand-written shell script plus tmux send-keys. The difference is not cosmetic. A script has no durable state, no reservations, no audit trail, no checkpoint and no machine-readable snapshot; it also has no policy layer, so a destructive command typed into the wrong pane executes. NTM's safety surface, which the README describes as destructive-command protection with policy editing, approvals and guards, is the part a script cannot reproduce without you writing it. The trade is that a script has no dependency on NTM's own release cadence, and NTM has shipped frequently: v1.32.0 on 2026-09-04, v1.33.0 on 2026-09-07, and v1.33.1 on 2026-09-09, with the last push to main on 2026-09-09.

Licence, upgrade cost, and what to check before you commit

The repository's LICENSE file is present, and the README badge describes the licence as MIT plus an OpenAI/Anthropic rider. GitHub reports the licence as NOASSERTION, which means the classifier could not match the file to a standard licence. Those two facts point the same way: read LICENSE yourself before you depend on it, particularly the rider, and treat this as a question for whoever handles licensing where you work rather than something a badge settles.

The upgrade cost is visible in the repository layout. There is a UPGRADE_LOG.md at the top level, and the Makefile defines an upgrade-contract target, which suggests the project tracks breaking changes across releases deliberately. There is also an AGENTS.md, so the project documents how agents should work in its own codebase. The go.mod pins go 1.26.8 and carries a replace directive pointing bubbletea at a vendored third_party/bubbletea, which the Dockerfile comments on explicitly: the module files for that local copy must be present before go mod download runs. If you build from source rather than using the installer, that replace directive is the detail most likely to trip a naive build.

Before adopting, run ntm deps -v and read its output against the agents you actually use. Then confirm your licence position on the rider, and check whether the agent types you depend on are in the fully automated set rather than the phase-one set.

Editorial conclusion

Adopt NTM if you already run several coding agents in tmux and want labels, worktree isolation, checkpoints and a machine-readable surface for scripts. Skip it if you want a GUI, or if you cannot install tmux and the agent CLIs it drives. Before committing, run ntm deps -v against your machine and confirm the agent CLIs you actually use are listed; the README notes that Grok Build support is phase one and that prompt delivery, interrupt-with-message and restore-time relaunch for Grok panes fail closed rather than partially working.

Frequently asked questions

Official sources

1. Dicklesworthstone/ntm on GitHub
2. Issues
3. README
4. Releases