Early release libtmux is released, and its APIs may still change between releases.
This site's structure and URLs may change too.
libtmux for TypeScript
TypeScript-based tmux client
tmux client library for TypeScript. Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents
import { mkdtemp } from"node:fs/promises";
import { tmpdir } from"node:os";
import { join } from"node:path";
import { setTimeout as delay } from"node:timers/promises";
run-shell -C libtmux-version-11bb768ca3864f8eabfe834a5d20993c-#{version}/#{pid}/#{start_time}error connecting to /tmp/tmp/ltx-home-ssDQbg/tmux.sock (No such file or directory)
Save the program above as quickstart.ts in a new directory, along with the files below.
Cleanup is omitted; the private tmux server and its temporary files may remain. Select Cleanup to remove them when the program finishes.The program stops its private tmux server and removes any temporary files it created when it finishes. Error handling adds diagnostics; every version checks required results and deadlines.
The checkbox turns a cooldown on and off for every picker on the site. It applies to what an install pulls
in; the package itself, and the libtmux it pins, stay current.
What are cooldowns?
Cooldowns delay picking up newly uploaded packages so the community has time to spot supply-chain
attacks before you install. Most package managers don't apply one by default; you opt in through a
global setting in your tool's configuration.
Bun cannot exempt libtmux from its own cooldown, so a cooldown here would also hold back the release this installs. This command runs without one.
$ bun add --minimum-release-age=0 libtmux
MCP
tmux through MCP
ReplayHover a call to preview the tmux state after it. Click to pin it.
tmux before the first call.
%0 sh
[checks]0:sh*
tmux after create_session.
%0 sh
%1 sh
[checks]0:sh*
tmux after split_window.
%0 sh
%1 sh
[checks]0:sh*
tmux after list_windows: unchanged, the call only reads.
%0 sh
$ pytest -q
.. [100%]
2 passed in 0.00s
%1 sh
[checks]0:sh*
tmux after run_shell_command.
%0 sh
$ pytest -q
.. [100%]
2 passed in 0.00s
%1 sh
$ cat checks.log
2026-01-01 checks started
2026-01-01 checks finished
[checks]0:sh*
tmux after run_shell_command.
No sessions
tmux 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.
agent in %0 it printed 2 passed in 0.00s; in %1 it printed 2026-01-01 checks finished.
0/6
Install @libtmux/mcp
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
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
Dependency cooldowns
Use the Configure cooldowns checkbox above to enable or disable. These settings choose how cooldown behaves
once enabled.
What are cooldowns?
Cooldowns delay picking up newly uploaded packages so the community has time to spot supply-chain attacks before
you install. Most package managers don't apply one by default — you opt in via a global setting in your
tool's config.
Excerpt of examples/mcp-agent/mcp-agent.ts,
which bun run typecheck && bun run test runs in the repository's CI
(.github/workflows/typescript.yml).
Workspace Manager
PresetThree panesShort-hand panesTwo panesFour panesMain-horizontal layoutEnvironmentStart directorySynchronized panesBlank panesVariables in valuesFocusMain pane height as a percentageMinimal workspacetmux optionsShell per paneSkip Enter for a commandSkip Enter for a panePause around a commandPause before a paneWait for a virtualenvKeep commands out of historyWindow index
start_directory chooses where a session, a window or a pane starts.
session_name: start directory
start_directory: /var/
windows:
- window_name: should be /var/
panes:
- shell_command:
- echo "\033c
- it trickles down from session-level"
- echo hello
- window_name: should be /var/log
start_directory: log
panes:
- shell_command:
- echo '\033c
- window start_directory concatenates to session start_directory
- if it is not absolute'
- echo hello
- window_name: should be ~
start_directory: "~"
panes:
- shell_command:
- 'echo \\033c ~ has precedence. note: remember to quote ~ in YAML'
- echo hello
- window_name: should be /bin
start_directory: /bin
panes:
- echo '\033c absolute paths also have precedence.'
- echo hello
- window_name: should be workspace file's dir
start_directory: ./
panes:
- shell_command:
- echo '\033c
- ./ is relative to workspace file location
- ../ will be parent of workspace file
- ./test will be \"test\" dir inside dir of workspace file'
- shell_command:
- echo '\033c
- This way you can load up workspaces from projects and maintain
- relative paths.'
{
"session_name": "start directory",
"start_directory": "/var/",
"windows": [
{
"window_name": "should be /var/",
"panes": [
{
"shell_command": [
"echo \"\\033c",
"it trickles down from session-level\""
]
},
"echo hello"
]
},
{
"window_name": "should be /var/log",
"start_directory": "log",
"panes": [
{
"shell_command": [
"echo '\\033c",
"window start_directory concatenates to session start_directory",
"if it is not absolute'"
]
},
"echo hello"
]
},
{
"window_name": "should be ~",
"start_directory": "~",
"panes": [
{
"shell_command": [
"echo \\\\033c ~ has precedence. note: remember to quote ~ in YAML"
]
},
"echo hello"
]
},
{
"window_name": "should be /bin",
"start_directory": "/bin",
"panes": [
"echo '\\033c absolute paths also have precedence.'",
"echo hello"
]
},
{
"window_name": "should be workspace file's dir",
"start_directory": "./",
"panes": [
{
"shell_command": [
"echo '\\033c",
"./ is relative to workspace file location",
"../ will be parent of workspace file",
"./test will be \\\"test\\\" dir inside dir of workspace file'"
]
},
{
"shell_command": [
"echo '\\033c",
"This way you can load up workspaces from projects and maintain",
"relative paths.'"
]
}
]
}
]
}
no layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panes
An empty entry, null, pane or blank opens a pane with no command.
session_name: Blank pane test
windows:
# Emptiness will simply open a blank pane, if no shell_command_before.
# All these are equivalent
- window_name: Blank pane test
panes:
-
- pane
- blank
- window_name: More blank panes
panes:
- null
- shell_command:
- shell_command:
-
# an empty string will be treated as a carriage return
- window_name: Empty string (return)
panes:
- ""
- shell_command: ""
- shell_command:
- ""
# a pane can have other options but still be blank
- window_name: Blank with options
panes:
- focus: true
- start_directory: /tmp
{
"session_name": "Blank pane test",
"windows": [
{
"window_name": "Blank pane test",
"panes": [
null,
"pane",
"blank"
]
},
{
"window_name": "More blank panes",
"panes": [
null,
{
"shell_command": null
},
{
"shell_command": [
null
]
}
]
},
{
"window_name": "Empty string (return)",
"panes": [
"",
{
"shell_command": ""
},
{
"shell_command": [
""
]
}
]
},
{
"window_name": "Blank with options",
"panes": [
{
"focus": true
},
{
"start_directory": "/tmp"
}
]
}
]
}
no layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panes
suppress_history chooses whether commands reach the shell history, per session, window, pane or command.
session_name: suppress
suppress_history: false
windows:
- window_name: appended
focus: true
suppress_history: false
panes:
- echo "window in the history!"
- window_name: suppressed
suppress_history: true
panes:
- echo "window not in the history!"
- window_name: default
panes:
- echo "session in the history!"
- window_name: mixed
suppress_history: false
panes:
- shell_command:
- echo "command in the history!"
suppress_history: false
- shell_command:
- echo "command not in the history!"
suppress_history: true
- shell_command:
- echo "window in the history!"
{
"session_name": "suppress",
"suppress_history": false,
"windows": [
{
"window_name": "appended",
"focus": true,
"suppress_history": false,
"panes": [
"echo \"window in the history!\""
]
},
{
"window_name": "suppressed",
"suppress_history": true,
"panes": [
"echo \"window not in the history!\""
]
},
{
"window_name": "default",
"panes": [
"echo \"session in the history!\""
]
},
{
"window_name": "mixed",
"suppress_history": false,
"panes": [
{
"shell_command": [
"echo \"command in the history!\""
],
"suppress_history": false
},
{
"shell_command": [
"echo \"command not in the history!\""
],
"suppress_history": true
},
{
"shell_command": [
"echo \"window in the history!\""
]
}
]
}
]
}
no layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panesno layout set, so the port tiles the panes
The workspace package is separate from the core library.
Dependency cooldowns
The checkbox turns a cooldown on and off for every picker on the site. It applies to what an install pulls
in; the package itself, and the libtmux it pins, stay current.
What are cooldowns?
Cooldowns delay picking up newly uploaded packages so the community has time to spot supply-chain
attacks before you install. Most package managers don't apply one by default; you opt in through a
global setting in your tool's configuration.
Runs tmux-workspace without installing it. Pass a command such as load ./workspace.yaml in place of --help.
$ bunx --bun @libtmux/workspace-cli --help
$ bunx --bun @libtmux/workspace-cli --help
Bun cannot exempt @libtmux/workspace-cli from its own cooldown, so a cooldown here would also hold back the release this installs. This command runs without one.
Bun cannot exempt @libtmux/workspace-cli from its own cooldown, so a cooldown here would also hold back the release this installs. This command runs without one.
$ bun add -g --minimum-release-age=0 @libtmux/workspace-cli