tmux-agent-switcher Watches Coding Agents

tmux-agent-switcher is a tmux plugin by Ymirke that adds a full-screen sidebar for watching AI coding agents across tmux sessions. It deals with a very plain problem: when Claude Code, Anthropic's coding agent, 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.

The trap is treating 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.

The trap is letting 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.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

- [ ] Name the Codex artifact first: an AGENTS.md instruction, a Codex CLI verification loop, an MCP boundary note, or a skills handoff.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• How should teams start with Codex?

  Start by writing down one visible team rule for Codex, not a loose preference. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Codex artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a AGENTS.md instruction, MCP note, or verification checklist. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Codex teams deciding which AGENTS.md instruction, CLI workflow, MCP boundary, or verification loop to standardize next around “tmux-agent-switcher Watches Coding Agents.”
• Best first artifact: turn the named fix into an AGENTS.md rule, verification checklist, MCP note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Codex CLI review loop, shell boundary, and evidence trail; keep the path that leaves the shortest auditable trail.

Further reading

• tmux-agent-switcher — source
• OpenAI Developers — AGENTS.md guide
• OpenAI Developers — Codex quickstart
• OpenAI developers: codex cli

Next move

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.