Allows an AI agent to list tmux sessions, read pane output, send keys, and wait for specific text matches via a stdio MCP server.
Also known as libtmux/libtmux-ts, @libtmux/mcp
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- 2,060
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is libtmux-ts MCP?
libtmux-ts allows an AI agent to list tmux sessions, read pane output, send keys, and wait for specific text matches via a stdio MCP server.
Summary generated from the project's README
About libtmux-ts MCP server
Automating terminal workflows by giving AI agents direct control over tmux sessions is what libtmux-ts enables. This stdio MCP server allows an agent to interact with a running tmux daemon to manage windows, panes, and sessions. It is designed for developers building agents that need to run commands, read terminal output, and react to specific state changes without manual polling.
Users connect the server to an MCP client by specifying a command and an optional LIBTMUX_SOCKET environment variable. The server works on Linux and WSL, with best-effort support for macOS, and requires tmux 3.3a or newer. It provides specialized tools for inspection, management, execution, and teardown, allowing an agent to perform complex terminal tasks through a structured interface.
Unlike simple command runners, this server provides high-level capabilities like waiting for specific text matches or capturing pane output since a specific cursor position. By using the capture_since and wait_for_text tools, an agent can synchronize its actions with the actual progress of long-running shell processes.
Written from the project's README. Every use case is checked against a quote from it.
How to install libtmux-ts MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall libtmux-ts MCP in Claude Code
$ claude mcp add libtmux-ts -- npx -y @libtmux/mcpInstall libtmux-ts MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"libtmux-ts": {
"command": "npx",
"args": [
"-y",
"@libtmux/mcp"
]
}
}
}Install libtmux-ts MCP in VS Code
.vscode/mcp.json
{
"servers": {
"libtmux-ts": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@libtmux/mcp"
]
}
}
}Install libtmux-ts MCP in VS Code CLI
$ code --add-mcp '{"name":"libtmux-ts","type":"stdio","command":"npx","args":["-y","@libtmux/mcp"]}'Install libtmux-ts MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"libtmux-ts": {
"command": "npx",
"args": [
"-y",
"@libtmux/mcp"
]
}
}
}Install libtmux-ts MCP in Codex
$ codex mcp add libtmux-ts -- npx -y @libtmux/mcpInstall libtmux-ts MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.libtmux-ts] command = "npx" args = ["-y", "@libtmux/mcp"]
Install libtmux-ts MCP in Gemini CLI
$ gemini mcp add -s user libtmux-ts npx -- -y @libtmux/mcpInstall libtmux-ts MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"libtmux-ts": {
"command": "npx",
"args": [
"-y",
"@libtmux/mcp"
]
}
}
}Configuration
LIBTMUX_SOCKET
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablelibtmux/libtmux-ts is public and reachablegithub.com/libtmux/libtmux-ts ↗Pass
- Package names this repository as its source@libtmux/mcp names libtmux/libtmux-ts as sourcenpmjs.com/package/@libtmux/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @libtmux/mcpnpmjs.com/package/@libtmux/mcp/v/0.1.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/libtmux/libtmux-ts ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @libtmux/mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHublibtmux for TypeScript
Typed control of tmux for Bun and TypeScript — immutable snapshots, declarative queries, and a library that ships zero runtime dependencies.
Quickstart • Querying • Packages • API reference • Hosted API reference • Examples • Changelog
[!WARNING] Releases are numbered
0.1.N, and each release incrementsN. The API is not settled: any release may change or remove exported identifiers, and each package's changelog marks its breaks. Pin an exact version to avoid one. The root changelog summarizes each release. Read the changelog of each package you use before you upgrade:libtmux,@libtmux/mcp,@libtmux/workspaceand@libtmux/workspace-cli.
Is this for you?
Yes, if you drive tmux from a program — an agent that runs commands and reads what they printed, a workspace launcher, a test harness, a dashboard — and you want the terminal's state as typed data rather than as parsed strings.
Probably not, if you want a .tmux.conf generator or a TUI. This library
controls a running server; it does not write your tmux configuration.
The idea in one line: read the whole server once into an immutable snapshot, then query it like data.
Quickstart
$ bun add libtmux
$ npm i libtmux
$ pnpm add libtmux
$ yarn add libtmux
Requires Bun 1.3.14+ or Node 22+, and tmux 3.3a or newer.
- The version that counts is the running daemon's.
- An older daemon, or an executable that would start one, is refused with
VersionTooLowErrorbefore any command takes effect. - A client reporting a newer release does not change that.
Runs on Linux, including WSL. macOS is supported on a best-effort basis, and CI coverage for it is highly limited.
import { Server } from "libtmux";
const server = new Server();
const snapshot = await server.snapshot();
// No further tmux calls: everything below resolves against the snapshot.
const editors = snapshot.panes.where({ currentCommand: "vim" });
console.log(editors.count(), editors.at(0)?.session?.name);
Building something rather than reading it looks like this — and this block is a
literal excerpt of examples/quickstart/quickstart.ts, which the
integration suite runs against a real tmux server:
const session = await server.newSession({ name: "quickstart" });
const editor = await session.newWindow({ name: "editor" });
await editor.split();
const snapshot = await server.snapshot();
const found = snapshot.windows.where({ name: "editor" }).one();
const paneCount = found.panes.length;
Refresh an object
A Session, Window or Pane you hold is what tmux said when it was read.
Changing tmux does not change it. refreshed() reads it
again and returns a new handle, the way Python libtmux's .refresh() does,
except that the handle you called it on stays as it was:
const window = snapshot.windows.one({ name: "editor" });
await window.rename("build");
const stale = window.name;
const fresh = (await window.refreshed()).name;
console.log(stale, fresh);
// editor build
Session and Pane have the same method.
What querying looks like
This is the part worth judging the library on. .where() takes declarative,
serializable criteria; .filter() takes an ordinary predicate. They are
never overloaded into each other.
// Equality, string operators, AND/OR/NOT, and regular expressions as data.
snapshot.sessions.where({
AND: [
{ name: { startsWith: "prod" } },
{ windows: { some: { name: { regex: { pattern: "^log", flags: "" } } } } },
],
});
// Quantifiers over relations: some / every / none, and is / isNot.
snapshot.windows.where({ session: { is: { name: "work" } } });
// Case-insensitive when you ask for it.
snapshot.sessions.where({ name: { contains: "API", mode: "insensitive" } });
A Selection is immutable, ordered, replayable, and Iterable.
It is not an Array:
selection.length;
selection.at(-1);
selection.toArray();
[...selection];
selection.one({ name: "work" }); // throws NoMatchError / MultipleMatchesError
selection.oneOrUndefined({ name: "work" });
selection.exists({ name: "work" });
Criteria are data. encodeWhereDocument writes a model-tagged query;
decodeWhereDocument validates one read from a config file, MCP call, or CLI.
Packages
The library, MCP server, workspace builder, and workspace CLI share one release version.
| Package | What it is | npm |
|---|---|---|
| libtmux | The library. Server, session, window, pane and client handles over a snapshot. | |
| @libtmux/mcp | An MCP server exposing tmux to an AI agent. | |
| @libtmux/workspace | Declarative workspace builder, tmuxp-shaped config. | |
| @libtmux/workspace-cli | The native tmux-workspace command for Node and Bun. |
|
| examples | Runnable examples, executed as tests. | — |
libtmux — the library
The library: Server, Session, Window, Pane and Client handles over an
immutable snapshot of tmux.
API reference · npm · Changelog
$ bun add libtmux
import { Server } from "libtmux";
const server = new Server();
const session = await server.newSession({ name: "work" });
const editor = await session.newWindow({ name: "editor" });
await editor.split();
await editor.panes.at(0)?.sendKeys("echo hello");
const lines = await editor.panes.at(0)?.capture();
Read next: Snapshots · Querying · Operations · Watching · Recipes · Errors · API reference
@libtmux/mcp — tmux for an AI agent
A stdio MCP server. Point it at a socket and an agent can list sessions, read a pane, send keys, and wait for output rather than polling for it.
API reference · Tools · npm · Changelog
With no socket chosen it passes tmux none, so tmux picks the server: the one it is launched inside, otherwise its default socket:
$ npx -y @libtmux/mcp@0.1.2
Add it to any MCP client — this is the whole configuration:
{
"mcpServers": {
"tmux": {
"command": "npx",
"args": ["-y", "@libtmux/mcp@0.1.2"],
"env": { "LIBTMUX_SOCKET": "agent" }
}
}
}
$ claude mcp add tmux --env LIBTMUX_SOCKET=agent -- \
npx -y @libtmux/mcp@0.1.2
The tools an agent reaches for first:
| Tool | What it does |
|---|---|
list_sessions |
Lists stable session identities and metadata |
capture_since |
Returns only pane output after a cursor |
wait_for_text |
Waits for bounded literal or regular-expression matches |
run_shell_command |
Runs a command through a pane and reports output and exit status |
create_session |
Creates a session without accepting a command or environment value |
The tools are split into inspect, manage, execute, and teardown.
tmux://capabilities is the only resource; the server exposes no prompts,
resource templates, background jobs, or generic mutation tools.
Read next: Why it exists · Configuration · Toolsets and trust · Choosing the right tool
@libtmux/workspace — declarative sessions
Describe a session; apply it. Applying twice converges rather than duplicating.
API reference · npm · Changelog
$ bun add @libtmux/workspace libtmux
import { Server } from "libtmux";
import { applyWorkspace } from "@libtmux/workspace";
const server = new Server();
await applyWorkspace(server, {
session_name: "api",
windows: [
{ window_name: "editor", panes: ["vim", "git status"] },
{ window_name: "server", panes: [{ shell_command: "bun dev", focus: true }] },
],
});
Read next: The config shape · Converging
@libtmux/workspace-cli — tmuxp workspaces from the shell
tmux-workspace loads, captures and converts tmuxp workspace files on Node or
Bun. Ordinary loads start no Python.
Command reference · npm · Changelog
Save this document as workspace.yaml:
session_name: dev
windows:
- window_name: editor
layout: main-vertical
panes:
- vim
- top
Load it detached, on a socket of its own:
$ npx -y @libtmux/workspace-cli@0.1.2 load ./workspace.yaml \
-L workspace-cli-demo \
-d
Read next: Install · Load and capture · Command reference
examples — runnable, and run
Programs covering acquisition, control-mode watching, the act-then-wait loop an agent needs, and building a workspace. Each is executed by the integration suite, so the code there is the code that runs.
$ bun test examples
How work is arranged
Observation, planning and concurrency compose around the same command engine — the full table is here.
| Mode | Turn it on | When to use it |
|---|---|---|
| connected | await server.connect() |
Pairing commands with a persistent event observer |
| watching | server.watch() |
Reacting to a change rather than polling to find it |
| pipeline | server.pipeline([…]) |
Ordered commands when printed output is enough |
| planned | .plan + server.batch([…]) |
Ordered mutations that must return typed handles |
| concurrent | Promise.all |
Independent work that may safely overlap |
Creating twelve windows costs, each figure including the one query that reads the result back:
- 25 tmux invocations one at a time, 13 through
pipeline, and 14 throughbatch, whose extra is the snapshot that turns printed ids into typed handles. - A snapshot is one invocation whatever the server's size, and querying it is none.
- The wall-clock beside those counts, and why
Promise.allbuys nothing over doing the same work in order, are in the benchmarks.
$ bun packages/libtmux/scripts/bench-modes.ts
What this project promises
- The library ships zero runtime dependencies. A test holds it.
@libtmux/mcpand@libtmux/workspacedeclare their own. - Real tmux, every commit. CI runs the suite against tmux 3.3a and 3.8 on each push, and against every release from 3.3a to 3.8, the
release_3.8abranch and tmux master before each release — no mocks stand in for a server. - Documentation is a gate. Every public symbol carries a compiled example, the API reference is generated from the source that implements it, and every link, install command and recipe on this page is checked on each run.
- Softly tracks Python libtmux. Names and shapes follow 0.62.0 where TypeScript agrees with them; each departure is a decision a gate holds to the code.
Repository
packages/libtmux the library
packages/mcp the MCP server
packages/workspace the workspace builder
packages/workspace-cli the tmux-workspace command
examples runnable examples, used as tests
attic reference notes
Working here: AGENTS.md routes to the policy that governs a change. The layout and the change discipline live there; how we write is in .github/WRITING.md, and the gates, real tmux, and releases are in .github/CONTRIBUTING.md.
AI policy
Use these packages with AI tools as you like. When contributing, check what you submit and wait for a maintainer's invitation before preparing a pull request. See the AI policy, also kept as AI_POLICY.md.
Attribution
Please use the following BibTeX template to cite libtmux-ts in scientific discourse:
@misc{libtmux-ts,
author = {Tony Narlock},
year = {2026},
note = {https://libtmux.org/en/ts/},
title = {libtmux-ts: TypeScript wrapper for tmux}
}
License
MIT — a port of tmux-python/libtmux.
libtmux-ts MCP questions
How do I add libtmux-ts MCP to Claude Code?
Run claude mcp add libtmux-ts -- npx -y @libtmux/mcp in your terminal. Add --scope user to make it available in every project.
How do I add libtmux-ts MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can an AI agent do with this MCP server?
An agent can list sessions, read pane output, send keys, run shell commands, and wait for specific text or regex matches.
Does this library generate tmux configuration files?
No, this library is designed to control a running tmux server rather than writing configuration files.