Quickstart¶

One happy path from zero to a working tool invocation.

1. Install¶

Pick your MCP client and install method:

With uvx installed:

$ claude mcp add tmux -- uvx libtmux-mcp

Config file: ~/.claude.json (this project)

With uvx installed:

$ claude mcp add tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: ~/.claude.json (this project)

With uvx installed:

$ claude mcp add tmux -- uvx --no-config libtmux-mcp

Config file: ~/.claude.json (this project)

With uvx installed:

$ claude mcp add tmux --scope user -- uvx libtmux-mcp

Config file: ~/.claude.json (all projects)

With uvx installed:

$ claude mcp add tmux --scope user -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: ~/.claude.json (all projects)

With uvx installed:

$ claude mcp add tmux --scope user -- uvx --no-config libtmux-mcp

Config file: ~/.claude.json (all projects)

With uvx installed:

$ claude mcp add tmux --scope project -- uvx libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With uvx installed:

$ claude mcp add tmux --scope project -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With uvx installed:

$ claude mcp add tmux --scope project -- uvx --no-config libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

$ claude mcp add tmux -- pipx run libtmux-mcp

Config file: ~/.claude.json (this project)

With pipx installed:

$ claude mcp add tmux -- pipx run libtmux-mcp

pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the uvx tab — it applies the cooldown to transitive deps via `--exclude-newer` while exempting libtmux-mcp itself via `--exclude-newer-package`.

Config file: ~/.claude.json (this project)

With pipx installed:

$ claude mcp add tmux -- pipx run libtmux-mcp

Config file: ~/.claude.json (this project)

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

Config file: ~/.claude.json (all projects)

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

Config file: ~/.claude.json (all projects)

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

Config file: ~/.claude.json (all projects)

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Config file: ~/.claude.json (all projects)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Config file: ~/.claude.json (all projects)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Config file: ~/.claude.json (all projects)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

Config file: .mcp.json (in repo, version-controlled)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

$ codex mcp add tmux -- uvx libtmux-mcp

Config file: ~/.codex/config.toml

With uvx installed:

$ codex mcp add tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: ~/.codex/config.toml

With uvx installed:

$ codex mcp add tmux -- uvx --no-config libtmux-mcp

Config file: ~/.codex/config.toml

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["libtmux-mcp"]

Config file: .codex/config.toml (in repo)

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]

Config file: .codex/config.toml (in repo)

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["libtmux-mcp"]
env = { UV_NO_CONFIG = "1" }

Config file: .codex/config.toml (in repo)

With pipx installed:

$ codex mcp add tmux -- pipx run libtmux-mcp

Config file: ~/.codex/config.toml

With pipx installed:

$ codex mcp add tmux -- pipx run libtmux-mcp

Config file: ~/.codex/config.toml

With pipx installed:

$ codex mcp add tmux -- pipx run libtmux-mcp

Config file: ~/.codex/config.toml

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

Config file: .codex/config.toml (in repo)

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

Config file: .codex/config.toml (in repo)

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

Config file: .codex/config.toml (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

Config file: .codex/config.toml (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

Config file: .codex/config.toml (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

Config file: .codex/config.toml (in repo)

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- libtmux-mcp

Config file: ~/.gemini/settings.json

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: ~/.gemini/settings.json

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- --no-config libtmux-mcp

Config file: ~/.gemini/settings.json

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- libtmux-mcp

Config file: .gemini/settings.json (in repo)

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

Config file: .gemini/settings.json (in repo)

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- --no-config libtmux-mcp

Config file: .gemini/settings.json (in repo)

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

Config file: ~/.gemini/settings.json

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

Config file: ~/.gemini/settings.json

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

Config file: ~/.gemini/settings.json

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

Config file: .gemini/settings.json (in repo)

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

Config file: .gemini/settings.json (in repo)

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

Config file: .gemini/settings.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Config file: ~/.gemini/settings.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Config file: ~/.gemini/settings.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Config file: ~/.gemini/settings.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

Config file: .gemini/settings.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

Config file: .gemini/settings.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

Config file: .gemini/settings.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "libtmux-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

See MCP Clients for dev-checkout setup, full config-file locations, and common pitfalls.

2. Verify¶

Ask your LLM:

Prompt

List all my tmux sessions and show me what’s running in each pane.

The agent will call list_sessions, then list_panes and capture_pane to inspect your workspace. You should see your tmux sessions, windows, and pane contents in the response.

3. Try it¶

Here are a few things to try:

Prompt

Create a new tmux session called “workspace” with a window named “build”.

Prompt

Send make test to the pane in my build window, then wait for it to finish and capture the output.

Prompt

Search all my panes for the word “error”.

How it works¶

When you say “run make test and show me the output”, the agent follows a typed command pattern:

run_command mutating — send the authored shell command, wait for completion, and return exit status plus output
Inspect the typed result’s exit_status, timed_out, and output fields

This run → inspect sequence is the default workflow for commands the agent authors. For custom shell composition outside run_command mutating, the lower-level escape hatch is send_keys mutating with tmux wait-for -S <channel> composed into the payload, followed by wait_for_channel mutating. For output the agent does not author (third-party log lines, daemon prompts, interactive supervisors), use wait_for_text readonly or wait_for_content_change readonly.

When you need to keep checking the same pane after that first read, switch to capture_since readonly: the first call returns a cursor, and follow-up calls return only new pane output.

Next steps¶

Concepts — Understand the tmux hierarchy and how tools target panes
Configuration — Environment variables and socket isolation
Safety tiers — Control which tools are available
Tools — Browse all available tools