tmux MCP, built in TypeScript

tmux terminal control for AI agents, built on libtmux for TypeScript and MCP TypeScript SDK. This server maps tmux's object hierarchy — sessions, windows, panes — into MCP tools grouped by the operation they request. The server enforces the selected groups at the MCP tool boundary.

Install

Choose your client and configuration scope, then run the command or paste the configuration.

$ claude mcp add tmux -- npx -y @libtmux/mcp

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

$ claude mcp add tmux -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

$ claude mcp add tmux -- npx -y --min-release-age=0 @libtmux/mcp

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

$ claude mcp add tmux --scope user -- npx -y @libtmux/mcp

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

$ claude mcp add tmux --scope user -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

$ claude mcp add tmux --scope user -- npx -y --min-release-age=0 @libtmux/mcp

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

$ claude mcp add tmux --scope project -- npx -y @libtmux/mcp

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

$ claude mcp add tmux --scope project -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

$ claude mcp add tmux --scope project -- npx -y --min-release-age=0 @libtmux/mcp

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

$ claude mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

Config file: claude_desktop_config.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: claude_desktop_config.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "--min-release-age=0", "@libtmux/mcp"]
        }
    }
}

Config file: claude_desktop_config.json

Build or install the server first:

$ npm install --global @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: claude_desktop_config.json

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: claude_desktop_config.json

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: claude_desktop_config.json

$ codex mcp add tmux -- npx -y @libtmux/mcp

Config file: ~/.codex/config.toml

$ codex mcp add tmux -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.codex/config.toml

$ codex mcp add tmux -- npx -y --min-release-age=0 @libtmux/mcp

Config file: ~/.codex/config.toml

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

[mcp_servers.tmux]
command = "npx"
args = ["-y", "@libtmux/mcp"]

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

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

[mcp_servers.tmux]
command = "npx"
args = ["-y", "@libtmux/mcp"]

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

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

[mcp_servers.tmux]
command = "npx"
args = ["-y", "--min-release-age=0", "@libtmux/mcp"]

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.codex/config.toml

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.codex/config.toml

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

$ codex mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.codex/config.toml

Build or install the server first:

$ npm install --global @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"

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=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"

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @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"

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

$ gemini mcp add --scope user tmux npx -- -y @libtmux/mcp

Config file: ~/.gemini/settings.json

$ gemini mcp add --scope user tmux npx -- -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.gemini/settings.json

$ gemini mcp add --scope user tmux npx -- -y --min-release-age=0 @libtmux/mcp

Config file: ~/.gemini/settings.json

$ gemini mcp add --scope project tmux npx -- -y @libtmux/mcp

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

$ gemini mcp add --scope project tmux npx -- -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

$ gemini mcp add --scope project tmux npx -- -y --min-release-age=0 @libtmux/mcp

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/settings.json

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/settings.json

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/settings.json

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "--min-release-age=0", "@libtmux/mcp"]
        }
    }
}

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.cursor/mcp.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "--min-release-age=0", "@libtmux/mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

Build or install the server first:

$ npm install --global @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.cursor/mcp.json

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.cursor/mcp.json

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.cursor/mcp.json

$ grok mcp add --scope user tmux -- npx -y @libtmux/mcp

Config file: ~/.grok/config.toml

$ grok mcp add --scope user tmux -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.grok/config.toml

$ grok mcp add --scope user tmux -- npx -y --min-release-age=0 @libtmux/mcp

Config file: ~/.grok/config.toml

$ grok mcp add --scope project tmux -- npx -y @libtmux/mcp

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

$ grok mcp add --scope project tmux -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

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

$ grok mcp add --scope project tmux -- npx -y --min-release-age=0 @libtmux/mcp

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

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.grok/config.toml

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.grok/config.toml

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.grok/config.toml

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

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

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

Config file: ~/.gemini/config/mcp_config.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "@libtmux/mcp"]
        }
    }
}

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.gemini/config/mcp_config.json

{
    "mcpServers": {
        "tmux": {
            "command": "npx",
            "args": ["-y", "--min-release-age=0", "@libtmux/mcp"]
        }
    }
}

Config file: ~/.gemini/config/mcp_config.json

Build or install the server first:

$ npm install --global @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/config/mcp_config.json

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/config/mcp_config.json

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then use this config:

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

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.gemini/config/mcp_config.json

$ opencode mcp add tmux -- npx -y @libtmux/mcp

Config file: ~/.config/opencode/opencode.jsonc

$ opencode mcp add tmux -- npx -y @libtmux/mcp

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release it runs; this runs without one. The Global install tab applies a cooldown to the server's dependencies.

Config file: ~/.config/opencode/opencode.jsonc

$ opencode mcp add tmux -- npx -y --min-release-age=0 @libtmux/mcp

Config file: ~/.config/opencode/opencode.jsonc

Build or install the server first:

$ npm install --global @libtmux/mcp

Then register:

$ opencode mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.config/opencode/opencode.jsonc

Build or install the server first:

$ npm install --global \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/mcp \
    --min-release-age-exclude=libtmux \
    @libtmux/mcp

Then register:

$ opencode mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.config/opencode/opencode.jsonc

Build or install the server first:

$ npm install --global --min-release-age=0 @libtmux/mcp

Then register:

$ opencode mcp add tmux -- libtmux-mcp

The package installs a `libtmux-mcp` binary. Requires Node 22 or newer, or Bun 1.3.14 or newer.

Config file: ~/.config/opencode/opencode.jsonc

@libtmux/mcp exposes tmux through an MCP stdio server and an embeddable TypeScript factory. Clients can inspect topology, capture output, run framed shell commands, and create or arrange panes.

The package requires Node 22 or newer, or Bun 1.3.14 or newer, plus tmux 3.3a or newer. Real tmux operation is supported on Linux; the package’s macOS artifact checks do not establish runtime support.

Start here¶

Install points an MCP client at this server.
Tools lists the MCP operations, arguments, and results.
Guides install and connect a client.
Topics explain toolsets, socket provenance, and waiting.
Examples call a tool, then explore server internals.
Language API documents embedding and implementation types.

The server exposes a static tmux://capabilities resource. It does not register workflow prompts or dynamic hierarchy resources.

Use Workspace Manager to load and apply declarative configurations in application code. MCP clients create topology through individual tools; there is no workspace-file tool.

Package and runtime contract.

Tools by tier

The TypeScript server groups its tools by what they request. A tier badge tells you how far a call reaches before you approve it. Set LIBTMUX_TOOLSETS to a comma-separated list of tiers, such as inspect,manage, to offer only those tools.

Inspect

Request tmux state and terminal output.

call_read_tools_batch Inspect Invoke a serial batch of at most 16 inspect tools.
capture_pane Inspect The text a pane is showing, or its scrollback.
capture_since Inspect What a pane has printed since you last looked.
find_pane_by_position Inspect Find the pane occupying a named corner of a window.
get_pane_info Inspect One pane's metadata: what it runs, where, how big, and whether it is yours or watched.
get_server_info Inspect The tmux server this process drives: its socket, version, daemon pid, and totals.
get_session_info Inspect Return metadata for one session without listing every session.
get_tmux_variables Inspect Resolve validated tmux variable names without accepting raw format syntax.
get_window_info Inspect Return metadata and placements for one window.
list_panes Inspect Panes on this server, with the command each is running and its directory.
list_sessions Inspect Every session on this server with its id, name, window count, and whether anyone is attached.
list_windows Inspect Windows on this server, optionally restricted to one session by id or name.
search_panes Inspect Find which panes are showing something.
show_environment Inspect Read the tmux environment.
show_hooks Inspect Read the hooks a server or session runs.
show_option Inspect Read one named tmux option at server, session, window, or pane scope.
snapshot_pane Inspect Return bounded terminal content and pane metadata in one MCP response.
wait_for_text Inspect Wait until a pane prints something, streaming tmux's notifications rather than polling.

Manage

Change tmux structure or presentation.

move_window Manage Move a window to another index, or into another session.
rename_session Manage Rename a session.
rename_window Manage Rename a window.
resize_pane Manage Resize a pane, either to a size or by an amount in a direction.
resize_window Manage Set a window's size in cells.
select_layout Manage Rearrange a window's panes.
select_pane Manage Make a pane the active one in its window.
select_window Manage Make a window the current one in its session.
set_history_limit Manage Set the default retained scrollback line limit through a bounded integer.
set_mouse_enabled Manage Set the global tmux mouse option through a closed boolean schema.
set_pane_title Manage Give a pane a title.
signal_channel Manage Signal a tmux wait-for channel.
swap_pane Manage Exchange two panes' positions.
wait_for_channel Manage Wait until a tmux wait-for channel is signalled.

Execute

Start or drive pane processes, or store state that can control later execution.

create_session Execute Create a detached session and return it with its first window and pane, so you can start working without listing anything first.
create_window Execute Add a window to a session and return it with its pane.
paste_text Execute Put text into a pane without tmux interpreting any of it as key names.
respawn_pane Execute Restart a pane's command in place, keeping the pane and its id.
run_shell_command Execute Run a shell command in a pane with your user's permissions.
send_keys Execute Send keystrokes to a pane.
send_keys_batch Execute Send an ordered batch of pane-input operations, resolving and checking each row's configured cohort immediately before input.
set_synchronize_panes Execute Set the window default for synchronized pane input.
split_window Execute Split a pane and return the new one.

Teardown

Delete tmux objects or retained scrollback. Not reversible.

clear_pane_scrollback Teardown Discard the retained scrollback history for one pane.
kill_pane Teardown Close a pane and the process in it.
kill_session Teardown Remove a session.
kill_window Teardown Close a window and every pane in it.

Browse every tool, with its arguments, result and protocol data.

Worked example

Given this prompt, an agent connected to the TypeScript server makes these calls and gets these results.

No sessions

After kill_session.

you

Create a tmux session called checks, split its window into two panes, run pytest -q in one and show checks.log in the other, show me the results, then remove the session.

agentCreate the session.

create_session Execute {"name":"checks"}

Result

{
  "paneId": "%0",
  "session": {
    "attachedClients": 0,
    "humanAttachedClients": 0,
    "id": "$0",
    "metadataComplete": true,
    "name": "checks",
    "omittedMetadataBytes": 0,
    "windows": 1
  },
  "windowId": "@0"
}

agentSplit the pane the create result returned (%0) in two.

split_window Execute {"paneId":"%0","direction":"right"}

Result

{
  "pane": {
    "active": false,
    "command": "sh",
    "cwd": "/home/user/project",
    "dead": false,
    "height": 24,
    "id": "%1",
    "index": 1,
    "isAttended": false,
    "isCallerPane": false,
    "metadataComplete": true,
    "omittedMetadataBytes": 0,
    "title": "host",
    "…": "6 more"
  }
}

agentRead the window's layout.

list_windows Inspect {"session":"checks"}

Result

{
  "complete": true,
  "omittedEntries": 0,
  "windows": [
    {
      "id": "@0",
      "layout": "{\"V\":2,\"L\":{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":[{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"%0\"},{\"t\":\"p\",\"w\":39,\"h\":24,\"x\":41,\"y\":0,\"i\":1,\"I\":\"%1\"}]}}",
      "metadataComplete": true,
      "name": "sh",
      "omittedMetadataBytes": 0,
      "panes": 2,
      "zoomed": false,
      "omittedPlacements": 0,
      "placements": [
        {
          "active": true,
          "index": 0,
          "sessionId": "$0",
          "sessionName": "checks"
        }
      ],
      "placementsComplete": true
    }
  ]
}

agentRun the tests in the pane the create result returned (%0).

run_shell_command Execute {"paneId":"%0","command":"pytest -q"}

Result

{
  "effectiveTimeoutMs": 30000,
  "exitStatus": 0,
  "foreignOutputSuspected": false,
  "droppedLines": 0,
  "missedBytes": 0,
  "omittedBytes": 0,
  "outcome": "completed",
  "output": "..                               [100%]\n2 passed in 0.00s",
  "outputComplete": true,
  "paneId": "%0",
  "returnedBytes": 57,
  "stillRunning": false
}

agentShow the log in the new pane the split returned (%1).

run_shell_command Execute {"paneId":"%1","command":"cat checks.log"}

Result

{
  "effectiveTimeoutMs": 30000,
  "exitStatus": 0,
  "foreignOutputSuspected": false,
  "droppedLines": 0,
  "missedBytes": 0,
  "omittedBytes": 0,
  "outcome": "completed",
  "output": "2026-01-01 checks started\n2026-01-01 checks finished",
  "outputComplete": true,
  "paneId": "%1",
  "returnedBytes": 52,
  "stillRunning": false
}

agentRemove the session once the result is read.

kill_session Teardown {"session":"checks"}

Result

{
  "killed": "$0"
}

agent in %0 it printed 2 passed in 0.00s; in %1 it printed 2026-01-01 checks finished.

Calls and results are recorded against libtmux/libtmux-ts at ecc3eaca0, on a private tmux 3.8a server, running pytest 9.2.0. The preview draws only what those results state. The agent's narration is illustrative. Long values in a result are shortened here; the recording keeps them. The sandbox's project directory is shown as /home/user/project.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux MCP, built in TypeScript

Install

Dependency cooldowns

Start here¶

Tools by tier

Inspect

Manage

Execute

Teardown

Worked example