How to Use OpenClaw with tmux for Background Agents and Session Management

tmux holds roughly 46,000 stars on GitHub and has been the standard for persistent terminal sessions since OpenBSD bundled it in 2009. In 2026, developers increasingly use it for a newer purpose: keeping AI coding agents alive after disconnects.

The problem is mechanical. When an SSH connection drops or a laptop lid closes, the kernel sends SIGHUP to the controlling process group. Every process in that group terminates immediately. A Claude Code session midway through a refactor, an OpenClaw pipeline coordinating research, a Codex CLI generating test suites: all gone the moment the terminal closes.

For short commands, this is a minor annoyance. For AI agents that accumulate hours of context and produce output continuously, it destroys real work. Session recovery flags can reload conversation history from log files on disk, but they do not restore in-flight tool state or active file operations. The context your agent built up over the last two hours is gone.

Why not just use nohup or GNU screen? nohup keeps the process alive but strips it of any terminal, so interactive agents that need a TTY cannot function. Screen works but lacks tmux's scriptability, pane layout control, and support for custom socket directories that enable session isolation. tmux gives you both persistence and the interactive terminal that AI coding agents require.

With API costs for coding agents measured in dollars per hour of active use, a killed session is not just lost context. It is wasted spend. Every minute of agent work that has to be repeated because of a disconnect is money and time burned. Running agents inside tmux eliminates this entire category of failure.

OpenClaw extends tmux with two dedicated skills that turn it from a general-purpose terminal multiplexer into a purpose-built agent orchestration layer. Instead of manually creating sessions and typing commands, you get scripts that spawn agents, check their status, and collect output from persistent sessions.

OpenClaw's skill registry includes two tmux-focused skills, each designed for a different layer of the workflow. Both are available through ClawHub, and they complement each other well.

steipete/tmux handles low-level session control. It teaches OpenClaw how to remote-control existing tmux sessions by sending keystrokes and reading pane output. Use it when you need fine-grained interaction with any interactive CLI running inside tmux.

Core capabilities include:

• Inspecting sessions with tmux list-sessions and list-panes
• Sending text literals and control keys to any pane
• Capturing recent scrollback history from a pane
• Waiting for specific text patterns using the included wait script
• Scanning all active sockets with find-sessions.sh

The skill works on macOS and Linux (Windows users need WSL with tmux installed inside it). It requires tmux on your PATH and supports isolated socket directories via the OPENCLAW_TMUX_SOCKET_DIR environment variable.

cuba6112/tmux-agents operates at a higher level. Rather than keystroke-by-keystroke control, it provides a full lifecycle for background coding agents:

• spawn.sh launches a named agent session with a task description and your choice of backend
• status.sh lists all running agent sessions with their current state and uptime
• check.sh inspects a specific session's recent output
• tmux attach drops you into a live session to watch or interact directly

The skill supports cloud agents (Claude, Codex, Gemini) that use API credits and local Ollama-backed agents (ollama-claude, ollama-codex) that run on your machine's GPU at no additional cost. Local agents work well for quick experiments and repetitive tasks. Cloud agents are the better choice for work that needs strong reasoning or large context windows.

Use tmux-agents when you want to fire up background coders and check on them later. Use steipete/tmux when you need finer control: steering an interactive CLI, capturing specific output patterns, or automating terminal interactions that go beyond simple command execution.

Before launching agents, tune your tmux configuration for AI workloads. The defaults work for casual terminal use, but agents generate more output than typical sessions.

Add these lines to ~/.tmux.conf:

set -g history-limit 50000
set -g mouse on
set -g renumber-windows on
set -g default-terminal "tmux-256color"
set -g status-interval 5
setw -g aggressive-resize on

The critical setting is history-limit. The default 2,000 lines fills up fast when an agent streams long responses. 50,000 lines gives enough scrollback to review an entire coding session without consuming excessive memory. After editing, reload with:

tmux source-file ~/.tmux.conf

Session structure matters. Create a dedicated session for agent work rather than mixing it with your regular terminal usage. A good pattern is a named session with separate windows: one for launching and interacting with agents, another for tailing builds, watching test output, or monitoring long-running processes. Keeping these concerns in separate windows lets you scroll through agent output without interrupting active sessions, and you can detach from the entire group at once.

Socket isolation prevents session name collisions when running multiple agent workflows simultaneously. The steipete/tmux skill supports a custom socket directory through the OPENCLAW_TMUX_SOCKET_DIR environment variable. When set, all agent tmux sessions use that directory instead of the default socket path. For teams sharing a development server, each developer points OPENCLAW_TMUX_SOCKET_DIR to their own directory to keep agent sessions separate. The find-sessions.sh script included with steipete/tmux can scan all active sockets across directories, giving you a unified view of every running session regardless of which socket directory it belongs to.

Gateway integration ties it together. OpenClaw's gateway dev mode uses tmux sessions by default. The gateway:watch command starts the Gateway process in a named tmux session and auto-attaches from interactive terminals. Non-interactive shells get the attach command printed instead, so you can connect manually. If the Gateway exits during startup, gateway:watch runs openclaw doctor to diagnose and fix the issue automatically before retrying.

Store and share what your background agents build

Fastio gives every agent 50GB of persistent storage with MCP access, no credit card required. When your tmux sessions end, the files your agents created stay indexed, searchable, and shareable.

Start 14-Day Trial

With tmux configured, spawning a background agent takes one command through the tmux-agents skill. The spawn script creates a new named tmux session, starts your chosen agent inside it, and passes your task description. Say you have a repository that needs its test suite updated after a major API change. Name the session "test-rewrite," describe the task, and pick Claude as the backend. The agent starts working immediately in its own session while you move on to other things.

Picking the right backend. The tmux-agents skill supports several options, and choosing well saves both time and money.

Cloud agents offer the strongest reasoning and largest context windows, but each session consumes API credits independently:

• Claude (Anthropic) for complex refactoring and multi-file code generation
• Codex (OpenAI) for focused code editing tasks
• Gemini (Google) for broad research and analysis

Local agents run on your machine's GPU with zero API cost:

• ollama-claude and ollama-codex through Ollama for cost-free experimentation and iteration

Checking progress. Once agents are running in the background, you have three ways to monitor them.

status.sh gives a quick overview of all running sessions, including names, uptimes, and whether each agent is actively generating output or sitting idle.

check.sh takes a session name and returns recent output from that agent's pane. This works well for scripted monitoring, periodic status checks, or quick reads without disrupting your current work.

tmux attach -t [session-name] drops you directly into the live session. Watch the agent work in real time, scroll through its output history, or type additional instructions. Detach with Ctrl+B then D to leave the agent running undisturbed.

Collecting results. Finished agents leave their output in the tmux scrollback buffer and any files they created on disk. Use check.sh to capture the final state, or attach and copy what you need.

The files an agent writes persist on disk regardless of the tmux session lifecycle. But scrollback is volatile. If you kill the session or the tmux server restarts, that terminal output disappears. For important results, pipe them to files or send them to a shared workspace. Local filesystems and S3 buckets work for raw storage, but neither indexes content or makes it searchable. Fastio provides 50GB of free workspace storage with MCP server access, so agents can write files directly to a shared, indexed location that survives beyond any terminal session. Intelligence Mode auto-indexes uploaded content for semantic search, meaning you can ask questions about agent output across all your sessions without digging through logs.

The real payoff of tmux with OpenClaw shows up when you run multiple agents simultaneously. Instead of one agent working through a task list sequentially, you spawn several agents in separate sessions, each handling a different piece of work.

A practical example: suppose you need to review a large codebase for security issues, performance problems, and test coverage gaps. Running one agent through all three checks takes the combined time. Running three agents in parallel, each focused on one review dimension, takes only as long as the slowest reviewer. Spawn each reviewer in its own named session, check progress periodically with status.sh, and collect findings from each when they finish.

For more complex work, OpenClaw supports a lead-worker pattern. One lead agent creates a team and maintains a shared task list. Worker agents handle subtasks in parallel tmux panes. The lead collects results and produces the final summary. This is the same architecture that Steve Yegge's Gas Town project uses to coordinate 20 to 30 Claude Code agents across tmux panes for large-scale code operations.

Session naming conventions help when running many agents at once. Use descriptive names that include the task type and target: security-review-api, perf-audit-frontend, coverage-check-auth. These names show up in status.sh output and make it easy to identify which session is doing what when you have five or ten agents running.

Task decomposition strategies vary by project. For a full-stack application, split by layer: one agent for the API, one for the frontend, one for infrastructure. For a monorepo, split by package. For a migration, split by target module. The key constraint is that parallel agents should not edit the same files simultaneously, since tmux does not provide file locking. When agents need to touch overlapping code, run them sequentially or use a lead agent to merge outputs.

Remote monitoring lets you check on agents from anywhere. OpenClaw's messaging integrations support Telegram, Slack, Discord, Signal, and WhatsApp. Ask OpenClaw to read a specific tmux session's output and send you a summary. Start a refactor before lunch, check the results from your phone after. Kick off test generation before you leave for the day, review findings the next morning. tmux keeps the work alive; OpenClaw keeps you connected to it.

Cost management matters with parallel execution. Five cloud agents running in parallel cost five times what one costs. Use the local Ollama-backed agents for tasks where output quality is less critical, and reserve cloud agents for the work that needs their stronger reasoning. Keep status.sh running periodically to catch agents that have stalled or finished, so you do not let idle sessions accumulate unnecessary charges.