techGalen Guan

Tmux Skills for AI Agents: Why We Don't Need a Tmux Wrapper

"Remote-control tmux sessions for interactive CLIs." That's the pitch for steipete/clawdis@tmux, the most-installed tmux skill on skills.sh with 2.8K installs. It's a clean, well-written skill — 170 lines, clear when-to-use/when-not-to-use sections, safe sending patterns for interactive TUIs. But does your AI agent actually need it?

The answer depends on your agent's architecture. For Claude Code and OpenClaw users working through SSH-disconnected sessions, tmux is essential infrastructure. For Hermes users, it's an unnecessary abstraction layer. Understanding why reveals a deeper truth about agent tool design.

What the Tmux Skill Does

The skill provides a structured interface for four operations:

List sessions     → tmux list-sessions
Capture output    → tmux capture-pane -t shared -p | tail -20
Send keystrokes   → tmux send-keys -t shared "y" Enter
Manage windows    → tmux select-window -t shared:0

The primary use case is monitoring and controlling Claude Code sessions running in background tmux panes. Check if a session needs input, send approval keystrokes, scrape output for decision-making.

The design is thoughtful. Sending input uses -l (literal) mode with a sleep before Enter to avoid paste truncation. Session status checks run across all workers in a for-loop. The when-to-use/when-not-to-use section is precise: don't use tmux for one-off shell commands or non-interactive scripts.

The Architectural Question

The skill raises a fundamental question: should an AI agent control an external terminal multiplexer, or should it have the multiplexing built into its tool layer?

Claude Code's architecture makes tmux natural. Claude Code sessions run in separate terminals, often across SSH connections. Monitoring requires reaching into those sessions from outside. Tmux is the bridge.

Hermes' architecture makes tmux redundant. The terminal tool handles every execution mode directly:

Foreground commands   → terminal("npm run build", timeout=300)
Background servers    → terminal("npm run dev", background=true)
Interactive CLIs      → terminal("python repl.py", pty=true)
Long-running tasks    → terminal("pytest", background=true, notify_on_complete=true)
Process monitoring    → process(action="poll", session_id=...)
Process input         → process(action="submit", data="y", session_id=...)

The three execution paths cover every tmux use case without an external multiplexer. Background mode for servers and long tasks. PTY mode for interactive CLIs. Process management for monitoring and input. One tool, one abstraction layer.

The Trade-Off

Dimension Tmux Skill Hermes Terminal
Dependencies Requires tmux installed Built-in
Session persistence Across SSH disconnects Within agent session
Monitoring granularity capture-pane (full scrollback) Process output streaming
Input safety Manual sleep + literal mode Native stdin handling
Error handling Must parse tmux output Exit codes + structured output
Multi-session Window/pane management Multiple background processes

The trade-off is clear: tmux trades simplicity for cross-session persistence. If your agent needs to survive SSH disconnects, tmux is the right answer. If your agent's execution model handles lifetime internally, a native terminal tool is simpler and more reliable.

Why We Skip Adoption

For the Hermes skill ecosystem, the decision was straightforward. The terminal tool provides equivalent functionality with less complexity. Adding a tmux wrapper would:

  1. Introduce unnecessary dependency — tmux must be installed on every machine
  2. Create redundant surface area — two tools for the same thing, doubling the cognitive load
  3. Add parsing fragility — tmux pane output requires regex extraction; native process output is structured
  4. Break composability — a tmux skill can't declare requires_skills that benefit from it, because Hermes skills don't operate at the tmux pane level

The deeper principle: prefer tools that integrate into the agent's execution model over tools that require the agent to adapt to an external execution model.

A terminal tool that understands process lifecycle, stdin/stdout/stderr, exit codes, and background management integrates naturally. A tmux wrapper that sends keystrokes to an external pane is always operating through a glass wall — seeing output as text rather than structured results, sending input as keystrokes rather than programmatic calls.

When Tmux Skills Make Sense

Tmux skills are valuable when:

  1. You're running Claude Code or Codex CLI in tmux sessions — this is the primary use case. The skill manages AI agent sessions, not arbitrary processes.

  2. Your agent operates across SSH disconnects — tmux's session persistence is its killer feature for remote development.

  3. You need session recovery — if a long-running Claude Code session needs attention after you've disconnected, tmux skills are the only way to reach it.

But for Hermes users executing tasks directly within the agent's tool layer — building, testing, deploying — the terminal tool is the right abstraction. It's not that tmux skills are bad. It's that they solve a problem Hermes' architecture has already solved differently.

The Bigger Picture

This decision reflects a broader pattern in our skill survey. Across eight categories, the most interesting finding wasn't which skills to adopt — it was which skills were redundant because our architecture had already absorbed their capability. Tmux control, session management, background execution — these aren't skill-level concerns. They're tool-level concerns. When your agent's tool layer handles them natively, wrapping them in a skill adds indirection without value.

The best skills teach the agent why, not how. Tmux skills teach how to send keystrokes. Hermes' terminal tool already knows how — what it needs from skills is guidance on why to choose background mode over foreground, why to poll before killing, why to check exit codes in a specific order. That's the kind of skill worth writing. The rest is architecture, not instruction.