OpenClaw + Tmux Setup: A Game-Changing Workflow for AI Agents

Many people use AI agents like chat tabs: ask one question, wait for one answer, then start over. That works for simple tasks, but it breaks down once you want persistence, parallel execution, background jobs, observability, remote access, and the ability to keep work running while you are away from the keyboard.

This is where OpenClaw, Tmux, and Claude Code fit together. OpenClaw, the personal AI assistant, acts as the always-on control plane. Tmux provides the durable terminal runtime. Claude Code provides the agents that can work in parallel inside panes and windows—though it's not exclusively for developers, as it excels at non-coding tasks like automation, data organization, documentation workflows, and operational task management. Combined, the stack feels less like a chatbot and more like a small engineering operations desk.

Why this combination works

OpenClaw is strong at routing, automation, tools, skills, channels, and session management. It can stay online as a daemon, receive instructions from chat or CLI, and fan work out across sessions.

Tmux is strong at persistence and visibility. Sessions survive SSH disconnects, panes keep separate concerns isolated, and the scrollback gives you an audit trail that is much easier to reason about than an ephemeral terminal tab.

Claude Code agent teams are strong at decomposition. Instead of one overloaded assistant handling everything sequentially, you can use a lead agent to coordinate smaller workers: one for repo analysis, one for implementation, one for tests, one for review, and one for challenge or validation. The same operating architecture also works for non-code tasks where different panes handle document cleanup, file organization, report preparation, or automation steps.

The architecture

An example setup separates control and routing at the OpenClaw layer, then uses tmux to host a Claude Code team with one lead pane and several worker panes.

Phone / CLI / WebChat / local terminal
                |
                v
         OpenClaw Gateway
                |
        +-------+--------+
        |                |
        v                v
   session routing   automation / alerts
        |
        v
        tmux session
            |
            +-- tmux window
                |
                +-- pane 1: lead agent
                +-- pane 2: worker 1
                +-- pane 3: worker 2
                +-- pane 4: worker 3
        

In this architecture, OpenClaw is not competing with Claude Code. It is wrapping the workflow around it. Claude Code can stay focused on changes inside the workspace. Tmux keeps every moving part visible and resumable.

The workflow in practice

A high-leverage loop usually looks like this:

• OpenClaw receives a request from CLI, chat, or a scheduled automation.
• An OpenClaw session opens the relevant tmux workspace.
• A lead Claude Code session creates a team, defines the task structure, and maintains the shared task list.
• Worker panes handle research, implementation, testing, or repo-specific checks in parallel and can message each other directly.
• The lead session collects results, resolves contradictions, and produces the final summary or patch set.
• OpenClaw sends the status update back to you, stores notes, or schedules follow-up work.

The biggest advantage is not speed alone. It is flow preservation. Work can continue in the background, and your context is still there when you reattach.

Step 1: Install the base stack

Start with tmux, OpenClaw, and Claude Code. If tmux is missing, use the installation guide. Then install OpenClaw with Node ≥22 and Claude Code on the same machine so the orchestration layer and the agent runtime can work together.

# Install OpenClaw
npm install -g openclaw@latest

# Run the onboarding wizard and configure your preferred channel
openclaw onboard --install-daemon

# Install Claude Code on macOS, Linux, or WSL
curl -fsSL https://claude.ai/install.sh | bash

# Start Claude Code. You'll be prompted to log in on first use. 
claude

Instead of logging in with Anthropic directly, you can connect Claude Code to OpenRouter by setting a few environment variables. Once logged in, your credentials are stored and you won’t need to log in again. Ask anything and press Enter to start your first Claude Code conversation. Here are some quick tips for the interface:

• You can’t click on things in the terminal. Use the arrow keys to move around.
• Press Esc to interrupt Claude if it’s running.
• Type exit or press Ctrl + C to leave Claude Code.
• Type /help to see available commands.

Step 2: Configure tmux for long-running AI work

AI-heavy panes need more scrollback than a normal shell, and pane navigation should stay frictionless. This is a good starting point for ~/.tmux.conf:

# Keep enough history for agent logs and long conversations
set -g history-limit 50000

# Better interaction defaults
set -g mouse on
set -g renumber-windows on
set -g default-terminal "tmux-256color"
set -g status-interval 5

# Make layouts easier to manage during agent work
setw -g aggressive-resize on

Apply the configuration by running:

tmux source-file ~/.tmux.conf

This reloads the configuration without restarting your session.

Step 3: Configure OpenClaw tools and skills

In OpenClaw, tools grant capabilities and skills teach behavior, so the right setup depends on what you actually want the agent to do. Users should adapt tool access based on their own workflow and review the available tool surfaces in the OpenClaw tools documentation.

# OpenClaw openclaw.json snippet intentionally omitted to avoid suggesting an overly broad setup.

In OpenClaw v2026.3.7+, new local installs default to tools.profile = messaging. Broad coding and system tools are not enabled unless you add them.

Bundled skills are enabled by default. So if tmux is on your system, the bundled tmux skill is usually ready to use immediately. The tmux skill teaches OpenClaw how to interact with the environment: it can inspect, create, or kill sessions, capture pane output and scrollback, send text and special keys to interactive CLIs, and navigate windows. In practice, it is most useful for monitoring and steering long-running Claude Code sessions or other interactive terminal tasks. This allows the AI to manage the persistent terminal runtime described in the following steps.

After making changes to the OpenClaw configuration, restart the gateway to apply them:

openclaw gateway restart

Step 4: Create a dedicated tmux session

Separate roles into windows instead of overloading a single shell. The goal here is to launch Claude Code from inside a tmux session so agent teams can use split-pane mode automatically when teammateMode is set to auto. You do not need to pre-build teammate panes yourself; Claude Code will create them when the team starts.

# Start the session in your project directory
tmux new-session -d -s claw -n coding
tmux send-keys -t claw:coding 'cd ~/example_repo' C-m

# Optional logs or build window
tmux new-window -t claw -n logs

# Attach to the session
tmux attach -t claw

Once attached, use the coding window to launch the lead Claude Code session. If agent teams are enabled and Claude is running inside tmux, split panes can be created automatically for teammates. The optional logs window is useful for tailing builds, servers, or other long-running output.

Step 5: Launch Claude Code inside tmux

Claude Code agent teams are experimental and disabled by default. Enable them in Claude Code settings before launching the lead session, typically in ~/.claude/settings.json, or export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the shell. Officially, the default teammateMode is auto, which uses split panes when Claude Code is already running inside tmux and in-process teammates otherwise.

{
    "env": {
        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
    }
}

With that setting in place, launch Claude Code from inside the tmux workspace.

cd ~/example_repo

# If you want to skip permission check in Claude Code, append --dangerously-skip-permissions to the command below,
# but be cautious as this can lead to unintended consequences.
claude

Once the Claude Code session is running with agent teams enabled, you do not need a special slash command. You can ask for a team in natural language and describe the roles you want Claude Code to create.

# Token-Efficient Prompt for Testing AI Agent Team Creation:
Create an agent team to translate "Hello world" to Spanish, French, and Chinese.
Assign one agent to each language. Report back the results. Use the model Haiku-4.5 for each agent.

Use agent teams when teammates should communicate and coordinate through a shared task list. If you only need quick helpers that report back to the main session, subagents are usually cheaper and simpler.

Step 6: Use OpenClaw channels for interaction

Once the gateway, channel, tmux, and Claude Code are all in place, you can treat OpenClaw as the control surface for the whole stack. Send the request through a paired channel such as Telegram, Slack, Discord, Signal, or WhatsApp. OpenClaw receives the message, routes it to the right session, and can reply back to the same channel with status, summaries, or follow-up questions.

Interact through your channel like this:

Or even create a new team:

Once the team has finished its work:

This is where OpenClaw becomes more than a chatbot wrapper. It gives you a stable inbox for steering the tmux runtime remotely, whether you are at your desk, on your phone, or away from the machine entirely.

Step 7: Streamline prompting with an agent skill

In Step 6, you may notice that we repeatedly prompt the AI assistant with the same patterns and operations to avoid confusing OpenClaw. While the bundled tmux skill handles low-level control, a higher-level skill can abstract away these repetitive instructions. Instead of requiring the user to describe every operation, it converts a channel request into the steps needed to start or manage an agent team.

Below is a working agent skill that implements this abstraction layer:

---
name: tmux-agent-teams
description: Create Claude Code agent teams when users ask to "Create an agent team ..." or "Spawn an agent team ...".
metadata:
  { "openclaw": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux", "claude"] } } }
---

# Agent Teams Workflow

## When to use this skill
Use this skill when the user wants to create a Claude Code agent team and the request is expressed as an outcome rather than a terminal procedure.

## Preconditions
- Claude Code credentials are configured.
- Claude Code Agent teams are enabled for Claude Code.


## Intent detection
1. Infer the work dir as `work_dir`, and team name as `team` from user's request.
2. If the team name is not provided, infer the name based on the teammates' tasks.

## Tmux session naming
`dir_hash`: `printf "$work_dir"|sha256sum | cut -c1-6`
`tmux_session`: `team-<dir_hash>-<team>`

## Behavior
load the bundled tmux/SKILL.md before any operations.
 
### Creation
1. If the work dir is not provided, ask for it before creating a tmux session.
2. If the request includes multiple possible directories, ask the user which work dir to use.
3. Ask the user for confirmation if a tmux session that includes the same `dir_hash` already exists.
4. In the tmux session `tmux_session`, run `source ~/.bashrc`
5. Launch Claude Code in the tmux session `tmux_session` with the command `claude`.
6. If Claude Code shows a confirmation prompt, ask the user for the choice.
7. Send the user's original request to the Claude Code lead.
8. Capture the lead pane output and report back to the user.

## Boundaries
- Do not confuse agents/teammates with ACP Agents, or sub-agents, and only use tmux skills to interact with Claude Code in tmux sessions.
- Do not assume dangerous permission bypass flags unless the user or policy explicitly allows them.
- Ask for clarification if the work dir or repository is ambiguous.
- Prefer reusing an existing team when the user clearly refers to ongoing work, but only in service of creating or continuing a requested team setup.

You can ask OpenClaw to install this skill, or fork and modify it based on your own workflow.

With the skill in place, you can interact with your assistant at the level of intent, significantly reducing prompting overhead:

Final thoughts

OpenClaw + tmux + Claude Code agent teams are not just a productivity trick. They represent a game-changing workflow for AI agents. Instead of a single monolithic chat, you get a persistent workspace with roles, visibility, background execution, and repeatable operating procedures.

Start small: one OpenClaw instance and one agent team. Once that feels natural, expand to additional teams—or even additional OpenClaw instances. At that point, the AI assistant and agent-skill stack becomes a practical control layer that lets you steer teams by intent.

Be aware that running AI agents can incur significant token costs. Monitor usage closely and budget accordingly to avoid unexpected charges.

For adjacent improvements, see the tmux plugins and tools page and the theming guide.