GitHub

Source on GitHub 3

Core Library

libtmux-cxxlibtmux/libtmux-cxx

MCP

libtmux-mcp-serverlibtmux-cxx/apps/mcp

Workspace Manager

tmux-workspacelibtmux-cxx/apps/workspace

C++ · libtmux/libtmux-cxx

Auto Light Dark

Core LibraryalphaHome

Choose documentation 3

Core Library API reference and guides

Home Guides Topics Concepts Examples API Reference

alpha Alpha release; the API may change. Read more

MCP Tools for connected assistants

Home Guides Topics Examples Tools Prompts Resources API Reference

concept Working example; may change without notice. Read more

Workspace Manager Repeatable development environments

Home Guides Examples CLI Manual API Reference Configuration Internals

concept Working example; may change without notice. Read more

latest

Current version

English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

.mobile-toolbar, .documentation-context-navigation, #mobile-sidebar, #mobile-toc { display: none !important; }

Browse documentation

Core LibraryHome

C++

Drive a real tmux from C++.

libtmux-cxx

You are reading the latest documentation. Use the version control in the header to move between releases, or the port dropdown to find a corresponding page in another language.

Install

Library `libtmux-cxx`

include(FetchContent)
FetchContent_Declare(
  libtmux
  GIT_REPOSITORY https://github.com/libtmux/libtmux-cxx.git
  GIT_TAG        v0.1.0-alpha.10
)
FetchContent_MakeAvailable(libtmux)
target_link_libraries(your_target PRIVATE libtmux::libtmux)

Name a tag or a commit, never a moving branch. Built this way the library brings nothing else: its tests, examples and MCP server all default off when it is not the top-level project.

{
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/libtmux/libtmux-cxx",
      "baseline": "",
      "packages": ["libtmux"]
    }
  ]
}

This repository is a vcpkg git registry, not a curated-registry port. Put this in vcpkg-configuration.json, add "libtmux" to your manifest, and run vcpkg x-update-baseline to fill the baseline.

$ git submodule add \
  https://github.com/libtmux/libtmux-cxx.git \
  third_party/libtmux

Then add_subdirectory(third_party/libtmux) and link libtmux::libtmux.

Workspace Manager `tmux-workspace`

The workspace package is separate from the core library.

$ cmake --preset cxx-dev -DLIBTMUX_BUILD_WORKSPACE_CLI=ON && \
    cmake --build --preset cxx-dev --target tmux-workspace --parallel 2

Run from a libtmux-cxx checkout with Clang 18.1.3, libc++ 18.1, CMake 3.25 or newer, and Ninja. The command is build/cxx-dev/apps/workspace/tmux-workspace.

MCP `libtmux-mcp-server`

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ claude mcp add tmux -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ claude mcp add tmux --scope user -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ claude mcp add tmux --scope project -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp-server"
        }
    }
}

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

Config file: claude_desktop_config.json

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ codex mcp add tmux -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

Config file: ~/.codex/config.toml

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

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 = "/absolute/path/to/libtmux-mcp-server"

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ gemini mcp add --scope user tmux /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

Config file: ~/.gemini/settings.json

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ gemini mcp add --scope project tmux /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp-server"
        }
    }
}

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp-server"
        }
    }
}

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

Config file: ~/.cursor/mcp.json

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ grok mcp add --scope user tmux -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

Config file: ~/.grok/config.toml

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ grok mcp add --scope project tmux -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp-server"
        }
    }
}

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Build or install the server first:

$ cmake -S . -B build/mcp -DLIBTMUX_BUILD_MCP_SERVER=ON -DLIBTMUX_FETCH_DEPS=ON && cmake --build build/mcp && cmake --install build/mcp --prefix ~/.local

Then register:

$ opencode mcp add tmux -- /absolute/path/to/libtmux-mcp-server

The MCP server is a build option rather than a second package, off by default because it is the only component that needs the JSON dependency. The install above puts libtmux-mcp-server in ~/.local/bin; use its full path.

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

Topics

Subject-by-subject, with C++ in every code block.

Guides

Task guides for C++.

Examples

Complete programs, sourced from the code each port tests.

Concepts

The domain model every port shares.

Packages and integrations

Workspace Manager

Build the CLI from source and load workspace files with tmux-workspace load.

MCP

In development. Connect an MCP client to tmux tools and inspect the server API.

API references

Official reference

C++ API signatures and documentation, with links to related guides and APIs in other languages.

All C++ versions and install instructions

Reference preview Open reference