tmux-agent-switcher Watches Coding Agents

By Rogier Muller08.13.26
tmux-agent-switcher Watches Coding Agents

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

tmux-agent-switcher is a tmux plugin by Ymirke that adds a full-screen sidebar for watching AI coding agents across tmux sessions. When Claude Code Codex CLI, OpenAI's terminal coding workflow, and OpenCode are all running remotely, you need to know which pane is working, blocked, or done. The useful idea is not that tmux becomes an agent platform; it is that passive status plus a fast jump key can beat a heavier dashboard for parallel Codex CLI workflows.

A tmux agent switcher is a navigation layer that shows where your agent processes are running and which ones need human attention. That sounds small. If you have ever left three agents running on a server, closed your laptop, then reopened it to a mess of stale panes, it is not small.

See the actual project before the pattern

The project is intentionally narrow. Press Ctrl+n, and tmux-agent-switcher opens a full-screen popup with windows from all tmux sessions on the left and a live scaled preview of the selected window on the right.

The agent-specific part is the badge. Panes running Claude Code, Codex, or OpenCode can be marked Working, Blocked, or Idle, with a timer. The same rolled-up state can also appear in tmux window tabs without replacing your existing tab format.

The important detail is how little it asks from the tools it watches. The README says detection is fully passive: it does not wrap, shim, or launch your agents. You keep running claude, codex, or opencode as usual, and the plugin reads tmux plus the process table.

That is the right kind of boring for terminal infrastructure. A wrapper can be powerful, but it also becomes the thing you must debug when a long-running job vanishes. tmux-agent-switcher keeps tmux as the process manager and adds just enough awareness to make the room less noisy.

Don't treat the badge as ground truth. Blocked is a signal to inspect a pane, not proof that the underlying agent is correct, safe, or ready to merge. Status helps you find the work; it does not review the work.

Why developers cared about this small plugin

The Hacker News interest made sense because the author described a workflow many agent-heavy developers have quietly converged on: run several agents in parallel, keep them on a separate machine, and let tasks continue when the laptop is closed or the network goes away.

That is exactly what tmux is good at. It survives disconnects. It keeps processes attached to a server. It lets a half-finished test run keep going while you move between places.

The new pain is attention routing. Classic tmux tells you that panes exist. It does not tell you which Codex run is waiting for permission, which Claude pane finished, or which background refactor is still chewing on tests.

As of August 2026, the repository was still small: 26 GitHub stars, mainly Rust, MIT licensed, and last pushed on 2026-08-01. That matters because this is not a polished platform story. It is a sharp utility from someone who hit a real daily annoyance and chose the existing terminal stack instead of replacing it.

The likely objection is robustness. Passive detection can be wonderfully low-friction, but agent CLIs change output, process names, and terminal behavior. If your workflow depends on perfect status semantics, you probably want a more explicit supervisor. If your workflow needs a better smoke alarm, passive is a good trade.

Make Codex panes easier to trust

For OpenAI Codex users, the interesting part is not the sidebar itself. It is the boundary between navigation and verification.

A good Codex CLI workflow should make it easy to answer two questions: where is the agent, and how do I know the result is good? tmux-agent-switcher helps with the first question. Your repo instructions and verification loop answer the second.

A simple AGENTS.md file can give Codex durable local rules before the work starts. For example, in a JavaScript service repo:

# AGENTS.md

## Project rules
- Prefer small changes over broad rewrites.
- Do not edit generated files in `dist/`.
- Keep API behavior backward-compatible unless the task says otherwise.

## Verification
Before handing back work, run:
- npm test
- npm run lint

If a command fails, summarize the failure and the smallest next fix.

Now the tmux view has something useful to point at. One pane might be a Codex agent updating request validation. Another might be running tests. A third might be idle after producing a patch. The sidebar gets you to the right pane quickly; the AGENTS.md file keeps the agent from improvising your repo norms.

This is the same lesson behind good Codex CLI workflows: do not ask the terminal UI to carry all the safety. Put stable rules in files, keep verification commands explicit, and use the switcher as an attention tool.

Don't let a smooth switcher hide weak handoffs. If an agent says it is done but did not run tests, the pane is not done. It is just quiet.

Try it when tmux is already home

tmux-agent-switcher is a good fit if you already live in tmux and run agents on a remote machine. It is especially natural when you keep separate sessions for a backend service, frontend app, test runner, and experiments.

It is probably overkill if you run one agent at a time in one local terminal. The plugin solves coordination cost. If you do not have coordination cost, it adds another moving part.

It also may not be the right first tool if your main problem is external context. If Codex needs GitHub issues, Slack threads, database state, or design docs, an MCP server boundary may matter more than pane switching. The switcher helps you find the process; MCP helps the process reach the right system.

A concrete boundary note can stay small:

# AGENTS.md

## MCP boundary
- GitHub MCP may read issues and pull requests.
- Do not write comments, labels, or branches unless the task explicitly asks.
- Summarize any external fact used in the final handoff.

That is enough to keep a local terminal workflow honest. The Codex agent can use context when allowed, but the final answer still tells you what it used and what it changed.

For a related example of a coding agent built around a narrower language and runtime surface, see keen-code: A Go Coding Agent. The useful comparison is scope: tmux-agent-switcher watches existing agents, while a language-specific agent tries to shape the work itself.

Try it safely

Use this as a small experiment, not a grand migration.

Fit check Try tmux-agent-switcher if... Skip it for now if...
Agent count You often run two or more agent panes at once. You usually run one local agent and watch it directly.
Runtime location Your agents run on a server or persistent dev box. Everything is short-lived on your laptop.
Main pain You lose track of blocked or idle panes. Your main pain is bad instructions or flaky tests.
Safety model You already have repo rules and verification commands. You expect status badges to replace review.

A safe first pass looks like this:

  • Start in a disposable tmux session, not your busiest work session.
  • Run your normal codex, claude, or opencode command; do not change how the agent starts.
  • Open the switcher with Ctrl+n and confirm that window navigation still feels like tmux.
  • Check whether Working, Blocked, and Idle match what you see in the panes.
  • Put one verification rule in AGENTS.md, then see whether completed panes actually report test results.
  • Remove the plugin if the status signal is noisy enough that you stop trusting it.

The best experiment is boring: one repo, one afternoon, two agents, one test command. If the switcher saves you from manually sweeping panes every ten minutes, it earned its place.

Further reading

Next move

Start from CLI workflows.