TypeScriptHome

Choose documentation 3

latest

Current version

latest
English

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

Product
import { mkdtemp } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { PaneDirection, Server } from "libtmux";
const directory = await mkdtemp(join(tmpdir(), "ltx-home-"));
const server = new Server({
socketPath: join(directory, "tmux.sock"),
configFile: "/dev/null",
timeoutMs: 5_000,
});
const signal = AbortSignal.timeout(5_000);
const session = await server.newSession({ name: "demo", signal });
// Lay out the session: name its window, split it, add a second window.
const editor = session.activeWindow;
if (!editor) throw new Error("The session has no active window");
await editor.rename("editor");
const left = editor.activePane;
if (!left) throw new Error("The window has no active pane");
const right = await left.split({
direction: PaneDirection.Right,
signal,
});
const logs = await session.newWindow({ name: "logs", signal });
// Type a command into the new pane and wait for what it prints.
await right.sendKeys("printf 'hello from %s\\n' tmux", { signal });
for (;;) {
const lines = await right.capture({ signal });
if (lines.some((line) => line.includes("hello from tmux"))) break;
await delay(20, undefined, { signal });
}
// Move the focus an attached client sees: the pane, then the window.
await right.select();
await logs.select();
// Walk the objects: down from the server, then up from one pane.
const snapshot = await server.snapshot({ signal });
for (const each of snapshot.sessions) {
console.log("session", each.name);
for (const window of each.windows) {
const ids = window.panes.map((pane) => pane.id).join(" ");
console.log(` window ${window.index}:${window.name}: ${ids}`);
}
}
const pane = snapshot.panes.one({ id: right.id });
const home = pane.window;
const owner = pane.session;
if (!home || !owner) throw new Error("The pane has no window or session");
console.log(pane.id, "is in window", home.name, "of session", owner.name);
import { mkdtemp } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { PaneDirection, Server } from "libtmux";
const directory = await mkdtemp(join(tmpdir(), "ltx-home-"));
const server = new Server({
socketPath: join(directory, "tmux.sock"),
configFile: "/dev/null",
timeoutMs: 5_000,
});
try {
const signal = AbortSignal.timeout(5_000);
const session = await server.newSession({ name: "demo", signal });
// Lay out the session: name its window, split it, add a second window.
const editor = session.activeWindow;
if (!editor) throw new Error("The session has no active window");
await editor.rename("editor");
const left = editor.activePane;
if (!left) throw new Error("The window has no active pane");
const right = await left.split({
direction: PaneDirection.Right,
signal,
});
const logs = await session.newWindow({ name: "logs", signal });
// Type a command into the new pane and wait for what it prints.
await right.sendKeys("printf 'hello from %s\\n' tmux", { signal });
for (;;) {
const lines = await right.capture({ signal });
if (lines.some((line) => line.includes("hello from tmux"))) break;
await delay(20, undefined, { signal });
}
// Move the focus an attached client sees: the pane, then the window.
await right.select();
await logs.select();
// Walk the objects: down from the server, then up from one pane.
const snapshot = await server.snapshot({ signal });
for (const each of snapshot.sessions) {
console.log("session", each.name);
for (const window of each.windows) {
const ids = window.panes.map((pane) => pane.id).join(" ");
console.log(` window ${window.index}:${window.name}: ${ids}`);
}
}
const pane = snapshot.panes.one({ id: right.id });
const home = pane.window;
const owner = pane.session;
if (!home || !owner) throw new Error("The pane has no window or session");
console.log(pane.id, "is in window", home.name, "of session", owner.name);
} catch (error) {
throw new Error("tmux quickstart failed", { cause: error });
}
import { mkdtemp, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { PaneDirection, Server } from "libtmux";
const directory = await mkdtemp(join(tmpdir(), "ltx-home-"));
const server = new Server({
socketPath: join(directory, "tmux.sock"),
configFile: "/dev/null",
timeoutMs: 5_000,
});
try {
const signal = AbortSignal.timeout(5_000);
const session = await server.newSession({ name: "demo", signal });
// Lay out the session: name its window, split it, add a second window.
const editor = session.activeWindow;
if (!editor) throw new Error("The session has no active window");
await editor.rename("editor");
const left = editor.activePane;
if (!left) throw new Error("The window has no active pane");
const right = await left.split({
direction: PaneDirection.Right,
signal,
});
const logs = await session.newWindow({ name: "logs", signal });
// Type a command into the new pane and wait for what it prints.
await right.sendKeys("printf 'hello from %s\\n' tmux", { signal });
for (;;) {
const lines = await right.capture({ signal });
if (lines.some((line) => line.includes("hello from tmux"))) break;
await delay(20, undefined, { signal });
}
// Move the focus an attached client sees: the pane, then the window.
await right.select();
await logs.select();
// Walk the objects: down from the server, then up from one pane.
const snapshot = await server.snapshot({ signal });
for (const each of snapshot.sessions) {
console.log("session", each.name);
for (const window of each.windows) {
const ids = window.panes.map((pane) => pane.id).join(" ");
console.log(` window ${window.index}:${window.name}: ${ids}`);
}
}
const pane = snapshot.panes.one({ id: right.id });
const home = pane.window;
const owner = pane.session;
if (!home || !owner) throw new Error("The pane has no window or session");
console.log(pane.id, "is in window", home.name, "of session", owner.name);
} finally {
if ((await readdir(directory)).includes("tmux.sock")) {
await server.kill();
}
await rm(directory, { recursive: true });
}
import { mkdtemp, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { PaneDirection, Server } from "libtmux";
const directory = await mkdtemp(join(tmpdir(), "ltx-home-"));
const server = new Server({
socketPath: join(directory, "tmux.sock"),
configFile: "/dev/null",
timeoutMs: 5_000,
});
const failures: unknown[] = [];
try {
const signal = AbortSignal.timeout(5_000);
const session = await server.newSession({ name: "demo", signal });
// Lay out the session: name its window, split it, add a second window.
const editor = session.activeWindow;
if (!editor) throw new Error("The session has no active window");
await editor.rename("editor");
const left = editor.activePane;
if (!left) throw new Error("The window has no active pane");
const right = await left.split({
direction: PaneDirection.Right,
signal,
});
const logs = await session.newWindow({ name: "logs", signal });
// Type a command into the new pane and wait for what it prints.
await right.sendKeys("printf 'hello from %s\\n' tmux", { signal });
for (;;) {
const lines = await right.capture({ signal });
if (lines.some((line) => line.includes("hello from tmux"))) break;
await delay(20, undefined, { signal });
}
// Move the focus an attached client sees: the pane, then the window.
await right.select();
await logs.select();
// Walk the objects: down from the server, then up from one pane.
const snapshot = await server.snapshot({ signal });
for (const each of snapshot.sessions) {
console.log("session", each.name);
for (const window of each.windows) {
const ids = window.panes.map((pane) => pane.id).join(" ");
console.log(` window ${window.index}:${window.name}: ${ids}`);
}
}
const pane = snapshot.panes.one({ id: right.id });
const home = pane.window;
const owner = pane.session;
if (!home || !owner) throw new Error("The pane has no window or session");
console.log(pane.id, "is in window", home.name, "of session", owner.name);
} catch (error) {
failures.push(error);
}
try {
if ((await readdir(directory)).includes("tmux.sock")) {
await server.kill();
}
await rm(directory, { recursive: true });
} catch (error) {
failures.push(new Error(`Cleanup failed: ${directory}`, {
cause: error,
}));
}
if (failures.length) throw new AggregateError(failures);
Example details
No tmux server yet

tmux before the first call: no server is running.

No tmux server yet

tmux after Server: no server is running; the call sent no command.

%0 sh
[demo]

tmux after Server.newSession: added session demo.

%0 sh
[demo]

tmux after Session.activeWindow: unchanged, the call sent no command.

%0 sh
[demo]

tmux after Window.rename: renamed window 0:sh to 0:editor.

%0 sh
[demo]

tmux after Window.activePane: unchanged, the call sent no command.

%0 sh
%1 sh
[demo]

tmux after Pane.split: added pane %1 to window 0:editor.

%0 sh
%1 sh
[demo]

tmux after Session.newWindow: added window 1:logs.

%0 sh
%1 sh
[demo]

tmux after Pane.sendKeys: sent keys to pane %1.

%0 sh
%1 sh
$ printf 'hello from %s\n' tmux
hello from tmux
$
[demo]

tmux after Pane.capture: read pane %1.

%0 sh
%1 sh
$ printf 'hello from %s\n' tmux
hello from tmux
$
[demo]

tmux after Pane.select: selected pane %1 in window 0:editor.

%2 sh
[demo]

tmux after Window.select: selected window 1:logs.

%2 sh
[demo]

tmux after Server.snapshot: unchanged.

%2 sh
[demo]

tmux after Window.panes: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Window.panes: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Selection.one: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Pane.window: unchanged, the call sent no command.

%2 sh
[demo]

tmux after Pane.session: unchanged, the call sent no command.

No sessions

tmux after Server.kill: the server has exited.

Before the first call

No tmux server is running yet.

Server returned Server

{
"socketPath": "/tmp/tmp/ltx-home-ssDQbg/tmux.sock",
"configFile": "/dev/null"
}

The call sent no tmux command.

Server.newSession returned Promise<Session>

{
"id": "$0",
"name": "demo"
}
5 tmux commands, 3 that change tmux
  1. 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)
  2. display-message -p #{version} tmux 3.8a
  3. new-session -d -P -F #{session_id} -s demo $0
  4. run-shell -C libtmux-version-26d13899b699466dbdeaf7e49a137ed0-#{version}/#{pid}/#{start_time} unknown command: libtmux-version-26d13899b699466dbdeaf7e49a137ed0-3.8a/2953902/1793886660
  5. display-message -p 'ltxI#{pid};#{start_time}' ; list-sessions '-FltxSa7b5fc4bcf264d51a1318868#{q:active_window_index};#{q:alternate_on};#{q:alternate_saved_x};#{q:alternate_saved_y};#{q:bracket_paste_flag};#{q:config_files};#{q:cursor_blinking};#{q:cursor_character};#{q:cursor_colour};#{q:cursor_flag};#{q:cursor_shape};#{q:cursor_very_visible};#{q:cursor_x};#{q:cursor_y};#{q:history_all_bytes};#{q… ltxI2953902;1793886660 ltxSa7b5fc4bcf264d51a13188680;0;4294967295;4294967295;0;/dev/null;0;\ ;none;1;default;0;2;0;24,960,20,100,0,0;1060;2000;0;0;0;0;0;0;0;0;0;0;0;\$1;0;1;1;1;1;1;default;23;sh;/tmp/marked;0;;;;default;\*;0;0;24;\%0;0;0;0;VT10x;0;0;0;0;;;0;hidden;2953903;0;;79;;;/tmp/marked;0;8,16,24,32,40,48,56,64,72;host;0;/dev/pts/14;0;80;0;0;1;0;2953902;23…

Session.activeWindow returned Window | undefined

{
"id": "@0",
"index": 0,
"name": "sh"
}

The call sent no tmux command.

Window.rename returned Promise<void>

null
1 tmux command, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-6c3cedd2c0d648faa7feed4e38a15083 ; rename-window -t @0 -- editor no output

Window.activePane returned Pane | undefined

{
"id": "%0"
}

The call sent no tmux command.

Pane.split returned Promise<Pane>

{
"id": "%1"
}
2 tmux commands, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-a2dd59b3d4be414fa474ecea75efbd52 ; split-window -d -P -F #{pane_id} -h -t %0 %1
  2. display-message -p 'ltxI#{pid};#{start_time}' ; list-sessions '-FltxS522ac4d5c0084153add34415#{q:active_window_index};#{q:alternate_on};#{q:alternate_saved_x};#{q:alternate_saved_y};#{q:bracket_paste_flag};#{q:config_files};#{q:cursor_blinking};#{q:cursor_character};#{q:cursor_colour};#{q:cursor_flag};#{q:cursor_shape};#{q:cursor_very_visible};#{q:cursor_x};#{q:cursor_y};#{q:history_all_bytes};#{q… ltxI2953902;1793886660 ltxS522ac4d5c0084153add344150;0;4294967295;4294967295;0;/dev/null;0;\ ;none;1;default;0;2;0;24,960,20,100,0,0;1060;2000;0;0;0;0;0;0;0;0;0;0;0;\$1;0;1;1;1;0;1;default;23;sh;/tmp/marked;0;;;;default;\*;0;0;24;\%0;0;0;0;VT10x;0;0;0;0;;;0;hidden;2953903;0;;39;;;/tmp/marked;0;8,16,24,32;host;0;/dev/pts/14;0;40;0;0;1;0;2953902;23;0;0;1793886660…

Session.newWindow returned Promise<Window>

{
"id": "@1",
"index": 1,
"name": "logs"
}
2 tmux commands, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-cac7e03aabca4d1598edecfeecd1903b ; new-window -d -P -F #{window_id} -t $0 -n logs @1
  2. display-message -p 'ltxI#{pid};#{start_time}' ; list-sessions '-FltxSca11577966ac4aeaa51bda2c#{q:active_window_index};#{q:alternate_on};#{q:alternate_saved_x};#{q:alternate_saved_y};#{q:bracket_paste_flag};#{q:config_files};#{q:cursor_blinking};#{q:cursor_character};#{q:cursor_colour};#{q:cursor_flag};#{q:cursor_shape};#{q:cursor_very_visible};#{q:cursor_x};#{q:cursor_y};#{q:history_all_bytes};#{q… ltxI2953902;1793886660 ltxSca11577966ac4aeaa51bda2c0;0;4294967295;4294967295;0;/dev/null;0;\ ;none;1;default;0;2;0;24,960,20,100,0,0;1060;2000;0;0;0;0;1;0;0;0;0;0;0;\$1;0;1;1;1;0;1;default;23;sh;/tmp/marked;0;;;;default;\*;0;0;24;\%0;0;0;0;VT10x;0;0;0;0;;;0;hidden;2953903;0;;39;;;/tmp/marked;0;8,16,24,32;host;0;/dev/pts/14;0;40;0;0;1;0;2953902;23;0;0;1793886660…

Pane.sendKeys returned Promise<void>

null
1 tmux command, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-414e7427b7394844a0d628873848587b ; send-keys -t %1 -- 'printf '\''hello from %s\n'\'' tmux' ; send-keys -t %1 Enter no output

Pane.capture returned Promise<readonly string[]>

[
"$ printf 'hello from %s\\n' tmux",
"hello from tmux",
"$"
]
1 tmux command
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-f5c9a2f59fdd4914bb3f881033f728d6 ; capture-pane -p -t %1 $ printf 'hello from %s\n' tmux hello from tmux $

Pane.select returned Promise<void>

null
1 tmux command, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-6cad1a8ba26a4aad9e5d15d56cef0e23 ; select-pane -t %1 no output

Window.select returned Promise<void>

null
1 tmux command, 1 that changes tmux
  1. if-shell -F #{==:#{version},3.8a} '' libtmux-version-872e70632d4045a5b2012d3388e29fbb ; select-window -t $0:1 no output

Server.snapshot returned Promise<ServerSnapshot>

{
"sessions": 1,
"windows": 2,
"panes": 3
}
1 tmux command
  1. display-message -p 'ltxI#{pid};#{start_time}' ; list-sessions '-FltxSbee1dee5ae984eec847e19cf#{q:active_window_index};#{q:alternate_on};#{q:alternate_saved_x};#{q:alternate_saved_y};#{q:bracket_paste_flag};#{q:config_files};#{q:cursor_blinking};#{q:cursor_character};#{q:cursor_colour};#{q:cursor_flag};#{q:cursor_shape};#{q:cursor_very_visible};#{q:cursor_x};#{q:cursor_y};#{q:history_all_bytes};#{q… ltxI2953902;1793886660 ltxSbee1dee5ae984eec847e19cf1;0;4294967295;4294967295;0;/dev/null;0;\ ;none;1;default;0;2;0;24,960,20,100,0,0;1060;2000;0;0;0;0;1;0;0;0;0;0;0;\$1;0;1;1;1;1;1;default;23;sh;/tmp/marked;0;;;;default;\*;0;0;24;\%2;0;0;0;VT10x;0;0;0;0;;;0;hidden;2954248;0;;79;;;/tmp/marked;0;8,16,24,32,40,48,56,64,72;host;0;/dev/pts/17;0;80;0;0;1;0;2953902;23…

Window.panes returned Selection<Pane>

{
"panes": "%0 %1"
}

The call sent no tmux command.

Window.panes returned Selection<Pane>

{
"panes": "%2"
}

The call sent no tmux command.

Selection.one returned Pane

{
"id": "%1"
}

The call sent no tmux command.

Pane.window returned Window | undefined

{
"id": "@0",
"index": 0,
"name": "editor"
}

The call sent no tmux command.

Pane.session returned Session | undefined

{
"id": "$0",
"name": "demo"
}

The call sent no tmux command.

Server.kill returned Promise<void>

null
1 tmux command, 1 that changes tmux
  1. kill-server no output
0/17
Run this example

POSIX shell, tmux 3.3a or newer and Bun 1.4.2.

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.

package.json
{"type":"module","private":true,"dependencies":{"libtmux":"0.1.2"}}

Setup and run

bun install
unset TMUX TMUX_PANE
export ENV=/dev/null BASH_ENV=/dev/null SHELL=/bin/sh
bun run quickstart.ts

Expected output

session demo
window 0:editor: %0 %1
window 1:logs: %2
%1 is in window editor of session demo

Install libtmux

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.

Cooldown type
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.

Learn more at cooldowns.dev · Datadog Security Labs writeup.

$ npm install libtmux
$ npm install \
    --min-release-age=7 \
    --min-release-age-exclude=libtmux \
    libtmux
$ npm install --min-release-age=0 libtmux
$ pnpm add libtmux
$ pnpm_config_minimum_release_age=10080 \
    pnpm_config_minimum_release_age_exclude='["libtmux"]' \
    pnpm add libtmux
$ pnpm_config_minimum_release_age=0 pnpm add libtmux
$ yarn add libtmux
$ YARN_NPM_MINIMAL_AGE_GATE=7d \
    YARN_NPM_PREAPPROVED_PACKAGES=libtmux \
    yarn add libtmux
$ YARN_NPM_MINIMAL_AGE_GATE=0 yarn add libtmux
$ bun add libtmux
$ bun add libtmux

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

Replay Hover a call to preview the tmux state after it. Click to pin it.

tmux before the first call.

tmux window of 1 pane
%0 sh
[checks] 0:sh*

tmux after create_session.

tmux window of 2 panes
%0 sh
%1 sh
[checks] 0:sh*

tmux after split_window.

tmux window of 2 panes
%0 sh
%1 sh
[checks] 0:sh*

tmux after list_windows: unchanged, the call only reads.

tmux window of 2 panes
%0 sh
$ pytest -q
..                               [100%]
2 passed in 0.00s
%1 sh
[checks] 0:sh*

tmux after run_shell_command.

tmux window of 2 panes
%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.

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.

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

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

Embed the server in a program
examples/mcp-agent/mcp-agent.ts
export async function connectAgent(server: Server): Promise<Client> {
const client = new Client({ name: "example", version: "0.0.0" });
const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
await Promise.all([
createTmuxMcpServer(server, {
environment: { LIBTMUX_TOOLSETS: "inspect,execute" },
}).connect(serverSide),
client.connect(clientSide),
]);
return client;
}

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

Preset
Three 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

Choose a preset 22

Three panes

A window of three panes.

session_name: 3-panes
windows:
- window_name: dev window
layout: main-vertical
shell_command_before:
- cd ~/
panes:
- shell_command:
- cd /var/log
- ls -al | grep \.log
- echo hello
- echo hello
{
"session_name": "3-panes",
"windows": [
{
"window_name": "dev window",
"layout": "main-vertical",
"shell_command_before": [
"cd ~/"
],
"panes": [
{
"shell_command": [
"cd /var/log",
"ls -al | grep \\.log"
]
},
"echo hello",
"echo hello"
]
}
]
}
Window 0, dev window: 3 panes, main-vertical❯ cd /var/log❯ ls -al | grep \.log❯ echo hello❯ echo hello
layout main-vertical

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/3-pane.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Short-hand panes

A pane can be one command written as a string, and a command list can be one string.

session_name: shorthands
windows:
- window_name: long form
panes:
- shell_command:
- echo 'did you know'
- echo 'you can inline'
- shell_command: echo 'single commands'
- echo 'for panes'
{
"session_name": "shorthands",
"windows": [
{
"window_name": "long form",
"panes": [
{
"shell_command": [
"echo 'did you know'",
"echo 'you can inline'"
]
},
{
"shell_command": "echo 'single commands'"
},
"echo 'for panes'"
]
}
]
}
Window 0, long form: 3 panes, tiled❯ echo 'did you know'❯ echo 'you can inline'❯ echo 'single commands'❯ echo 'for panes'
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/shorthands.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Two panes

A window of two panes.

session_name: 2-pane-vertical
windows:
- window_name: my test window
panes:
- echo hello
- echo hello
{
"session_name": "2-pane-vertical",
"windows": [
{
"window_name": "my test window",
"panes": [
"echo hello",
"echo hello"
]
}
]
}
Window 0, my test window: 2 panes, tiled❯ echo hello❯ echo hello
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/2-pane-vertical.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Four panes

A window of four panes.

session_name: 4-pane-split
windows:
- window_name: dev window
layout: tiled
shell_command_before:
- cd ~/
panes:
- shell_command:
- cd /var/log
- ls -al | grep \.log
- echo hello
- echo hello
- echo hello
{
"session_name": "4-pane-split",
"windows": [
{
"window_name": "dev window",
"layout": "tiled",
"shell_command_before": [
"cd ~/"
],
"panes": [
{
"shell_command": [
"cd /var/log",
"ls -al | grep \\.log"
]
},
"echo hello",
"echo hello",
"echo hello"
]
}
]
}
Window 0, dev window: 4 panes, tiled❯ cd /var/log❯ ls -al | grep \.log❯ echo hello❯ echo hello❯ echo hello
layout tiled

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/4-pane.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Main-horizontal layout

The main-horizontal layout gives the first pane the top of the window and splits the rest below it.

session_name: main-pane-height
start_directory: "~"
windows:
- layout: main-horizontal
options:
main-pane-height: 30
panes:
- shell_command:
- top
start_directory: "~"
- shell_command:
- echo "hey"
- shell_command:
- echo "moo"
window_name: my window name
{
"session_name": "main-pane-height",
"start_directory": "~",
"windows": [
{
"layout": "main-horizontal",
"options": {
"main-pane-height": 30
},
"panes": [
{
"shell_command": [
"top"
],
"start_directory": "~"
},
{
"shell_command": [
"echo \"hey\""
]
},
{
"shell_command": [
"echo \"moo\""
]
}
],
"window_name": "my window name"
}
]
}
Window 0, my window name: 3 panes, main-horizontal❯ top❯ echo "hey"❯ echo "moo"
layout main-horizontal

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/main-pane-height.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Environment

environment sets variables for a session, a window or a pane.

session_name: Environment variables test
environment:
EDITOR: /usr/bin/vim
DJANGO_SETTINGS_MODULE: my_app.settings.local
SERVER_PORT: "8009"
windows:
- window_name: Django project
panes:
- ./manage.py runserver 0.0.0.0:${SERVER_PORT}
- window_name: Another Django project
environment:
DJANGO_SETTINGS_MODULE: my_app.settings.local
SERVER_PORT: "8010"
panes:
- ./manage.py runserver 0.0.0.0:${SERVER_PORT}
- environment:
DJANGO_SETTINGS_MODULE: my_app.settings.local-testing
SERVER_PORT: "8011"
shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT}
{
"session_name": "Environment variables test",
"environment": {
"EDITOR": "/usr/bin/vim",
"DJANGO_SETTINGS_MODULE": "my_app.settings.local",
"SERVER_PORT": "8009"
},
"windows": [
{
"window_name": "Django project",
"panes": [
"./manage.py runserver 0.0.0.0:${SERVER_PORT}"
]
},
{
"window_name": "Another Django project",
"environment": {
"DJANGO_SETTINGS_MODULE": "my_app.settings.local",
"SERVER_PORT": "8010"
},
"panes": [
"./manage.py runserver 0.0.0.0:${SERVER_PORT}",
{
"environment": {
"DJANGO_SETTINGS_MODULE": "my_app.settings.local-testing",
"SERVER_PORT": "8011"
},
"shell_command": "./manage.py runserver 0.0.0.0:${SERVER_PORT}"
}
]
}
]
}
Window 0, Django project: 1 pane, tiled❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set, so the port tiles the panes
Window 1, Another Django project: 2 panes, tiled❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}❯ ./manage.py runserver 0.0.0.0:${SERVER_PORT}
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/session-environment.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Start directory

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.'"
]
}
]
}
]
}
Window 0, should be /var/: 2 panes, tiled❯ echo "\033c❯ it trickles down from session-level"❯ echo hello
no layout set, so the port tiles the panes
Window 1, should be /var/log: 2 panes, tiled❯ echo '\033c❯ window start_directory concatenates to session start_directory❯ if it is not absolute'❯ echo hello
no layout set, so the port tiles the panes
Window 2, should be ~: 2 panes, tiled❯ echo \\033c ~ has precedence. note: remember to quote ~ in YAML❯ echo hello
no layout set, so the port tiles the panes
Window 3, should be /bin: 2 panes, tiled❯ echo '\033c absolute paths also have precedence.'❯ echo hello
no layout set, so the port tiles the panes
Window 4, should be workspace file's dir: 2 panes, tiled❯ echo '\033c❯ ./ is relative to workspace file location❯ ../ will be parent of workspace file❯ ./test will be \"test\" dir inside dir of workspace file'❯ echo '\033c❯ This way you can load up workspaces from projects and maintain❯ relative paths.'
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/start-directory.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Synchronized panes

options_after sets synchronize-panes once the panes exist, so typing in one pane reaches the others.

session_name: 2-pane-synchronized
windows:
- window_name: Two synchronized panes
panes:
- ssh server1
- ssh server2
options_after:
synchronize-panes: on
{
"session_name": "2-pane-synchronized",
"windows": [
{
"window_name": "Two synchronized panes",
"panes": [
"ssh server1",
"ssh server2"
],
"options_after": {
"synchronize-panes": "on"
}
}
]
}
Window 0, Two synchronized panes: 2 panes, tiled❯ ssh server1❯ ssh server2
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/2-pane-synchronized.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Blank 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"
}
]
}
]
}
Window 0, Blank pane test: 3 panes, tiled
no layout set, so the port tiles the panes
Window 1, More blank panes: 3 panes, tiled
no layout set, so the port tiles the panes
Window 2, Empty string (return): 3 panes, tiled
no layout set, so the port tiles the panes
Window 3, Blank with options: 2 panes, tiled
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/blank-panes.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Variables in values

A ${VAR} in a name, a path or an option expands from the environment of the loading process.

start_directory: "${PWD}/test"
shell_command_before: "echo ${PWD}"
before_script: "${MY_ENV_VAR}/test3.sh"
session_name: session - ${USER} (${MY_ENV_VAR})
windows:
- window_name: editor
panes:
- shell_command:
- tail -F /var/log/syslog
start_directory: /var/log
- window_name: logging for ${USER}
options:
automatic-rename: true
panes:
- shell_command:
- htop
- ls $PWD
{
"start_directory": "${PWD}/test",
"shell_command_before": "echo ${PWD}",
"before_script": "${MY_ENV_VAR}/test3.sh",
"session_name": "session - ${USER} (${MY_ENV_VAR})",
"windows": [
{
"window_name": "editor",
"panes": [
{
"shell_command": [
"tail -F /var/log/syslog"
]
}
],
"start_directory": "/var/log"
},
{
"window_name": "logging for ${USER}",
"options": {
"automatic-rename": true
},
"panes": [
{
"shell_command": [
"htop",
"ls $PWD"
]
}
]
}
]
}
Window 0, editor: 1 pane, tiled❯ tail -F /var/log/syslog
no layout set, so the port tiles the panes
Window 1, logging for ${USER}: 1 pane, tiled❯ htop❯ ls $PWD
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/env-variables.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Focus

focus: true selects a window or a pane when the session is built.

session_name: focus
windows:
- window_name: attached window
focus: true
panes:
- shell_command:
- echo hello
- echo 'this pane should be selected on load'
focus: true
- shell_command:
- cd /var/log
- echo hello
- window_name: second window
shell_command_before: cd /var/log
panes:
- pane
- shell_command:
- echo 'this pane should be focused, when window switched to first time'
focus: true
- pane
{
"session_name": "focus",
"windows": [
{
"window_name": "attached window",
"focus": true,
"panes": [
{
"shell_command": [
"echo hello",
"echo 'this pane should be selected on load'"
],
"focus": true
},
{
"shell_command": [
"cd /var/log",
"echo hello"
]
}
]
},
{
"window_name": "second window",
"shell_command_before": "cd /var/log",
"panes": [
"pane",
{
"shell_command": [
"echo 'this pane should be focused, when window switched to first time'"
],
"focus": true
},
"pane"
]
}
]
}
Window 0, attached window: 2 panes, tiled❯ echo hello❯ echo 'this pane should be selected on load'❯ cd /var/log❯ echo hello
no layout set, so the port tiles the panes
Window 1, second window: 3 panes, tiled❯ echo 'this pane should be focused, when window switched to first time'
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/focus-window-and-panes.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Main pane height as a percentage

main-pane-height takes a percentage of the window as well as a row count.

session_name: main-pane-height
start_directory: "~"
windows:
- layout: main-horizontal
options:
main-pane-height: 67%
panes:
- shell_command:
- top
start_directory: "~"
- shell_command:
- echo "hey"
- shell_command:
- echo "moo"
window_name: my window name
{
"session_name": "main-pane-height",
"start_directory": "~",
"windows": [
{
"layout": "main-horizontal",
"options": {
"main-pane-height": "67%"
},
"panes": [
{
"shell_command": [
"top"
],
"start_directory": "~"
},
{
"shell_command": [
"echo \"hey\""
]
},
{
"shell_command": [
"echo \"moo\""
]
}
],
"window_name": "my window name"
}
]
}
Window 0, my window name: 3 panes, main-horizontal❯ top❯ echo "hey"❯ echo "moo"
layout main-horizontal

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/main-pane-height-percentage.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Minimal workspace

A session name and one window with one blank pane.

session_name: My tmux session
windows:
- panes:
-
{
"session_name": "My tmux session",
"windows": [
{
"panes": [
null
]
}
]
}
Window 0: 1 pane, tiled
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/minimal.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

tmux options

global_options, options and a window's options set tmux options.

session_name: test window options
start_directory: "~"
global_options:
default-shell: /bin/sh
default-command: /bin/sh
options:
main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variables
windows:
- layout: main-horizontal
options:
automatic-rename: on
panes:
- shell_command:
- man echo
start_directory: "~"
- shell_command:
- echo "hey"
- shell_command:
- echo "moo"
{
"session_name": "test window options",
"start_directory": "~",
"global_options": {
"default-shell": "/bin/sh",
"default-command": "/bin/sh"
},
"options": {
"main-pane-height": "${MAIN_PANE_HEIGHT}"
},
"windows": [
{
"layout": "main-horizontal",
"options": {
"automatic-rename": "on"
},
"panes": [
{
"shell_command": [
"man echo"
],
"start_directory": "~"
},
{
"shell_command": [
"echo \"hey\""
]
},
{
"shell_command": [
"echo \"moo\""
]
}
]
}
]
}
Window 0: 3 panes, main-horizontal❯ man echo❯ echo "hey"❯ echo "moo"
layout main-horizontal

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/options.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Shell per pane

A pane can start its own shell or program, and window_shell sets the default for a window.

session_name: Pane shell example
windows:
- window_name: first
window_shell: /usr/bin/python2
layout: even-vertical
suppress_history: false
options:
remain-on-exit: true
panes:
- shell: /usr/bin/python3
shell_command:
- print('This is python 3')
- shell: /usr/bin/vim -u none
shell_command:
- iAll panes have the `remain-on-exit` setting on.
- When you exit out of the shell or application, the panes will remain.
- Use tmux command `:kill-pane` to remove the pane.
- Use tmux command `:respawn-pane` to restart the shell in the pane.
- Use <Escape> and then `:q!` to get out of this vim window. :-)
- shell_command:
- print('Hello World 2')
- shell: /usr/bin/top
{
"session_name": "Pane shell example",
"windows": [
{
"window_name": "first",
"window_shell": "/usr/bin/python2",
"layout": "even-vertical",
"suppress_history": false,
"options": {
"remain-on-exit": true
},
"panes": [
{
"shell": "/usr/bin/python3",
"shell_command": [
"print('This is python 3')"
]
},
{
"shell": "/usr/bin/vim -u none",
"shell_command": [
"iAll panes have the `remain-on-exit` setting on.",
"When you exit out of the shell or application, the panes will remain.",
"Use tmux command `:kill-pane` to remove the pane.",
"Use tmux command `:respawn-pane` to restart the shell in the pane.",
"Use <Escape> and then `:q!` to get out of this vim window. :-)"
]
},
{
"shell_command": [
"print('Hello World 2')"
]
},
{
"shell": "/usr/bin/top"
}
]
}
]
}
Window 0, first: 4 panes, even-vertical❯ print('This is python 3')❯ iAll panes have the `remain-on-exit` setting on.❯ When you exit out of the shell or application, the panes will remain.❯ Use tmux command `:kill-pane` to remove the pane.❯ Use tmux command `:respawn-pane` to restart the shell in the pane.❯ Use <Escape> and then `:q!` to get out of this vim window. :-)❯ print('Hello World 2')
layout even-vertical

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/pane-shell.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Skip Enter for a command

enter: false types a command without running it.

session_name: Skip command execution (command-level)
windows:
- panes:
- shell_command:
# You can see this
- echo "___$((11 + 1))___"
# This is skipped
- cmd: echo "___$((1 + 3))___"
enter: false
{
"session_name": "Skip command execution (command-level)",
"windows": [
{
"panes": [
{
"shell_command": [
"echo \"___$((11 + 1))___\"",
{
"cmd": "echo \"___$((1 + 3))___\"",
"enter": false
}
]
}
]
}
]
}
Window 0: 1 pane, tiled❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/skip-send.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Skip Enter for a pane

enter: false on a pane types its commands without running them.

session_name: Skip command execution (pane-level)
windows:
- panes:
- shell_command: echo "___$((1 + 3))___"
enter: false
- shell_command:
- echo "___$((1 + 3))___"\;
- echo "___$((1 + 3))___"
enter: false
{
"session_name": "Skip command execution (pane-level)",
"windows": [
{
"panes": [
{
"shell_command": "echo \"___$((1 + 3))___\"",
"enter": false
},
{
"shell_command": [
"echo \"___$((1 + 3))___\"\\;",
"echo \"___$((1 + 3))___\""
],
"enter": false
}
]
}
]
}
Window 0: 2 panes, tiled❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"\;❯ echo "___$((1 + 3))___"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/skip-send-pane-level.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Pause around a command

sleep_before and sleep_after delay a command or the one after it.

session_name: Pause / skip command execution (command-level)
windows:
- panes:
- shell_command:
# Executes immediately
- echo "___$((11 + 1))___"
# Delays before sending 2 seconds
- cmd: echo "___$((1 + 3))___"
sleep_before: 2
# Executes immediately
- cmd: echo "___$((1 + 3))___"
# Pauses 2 seconds after
- cmd: echo "Stuff rendering here!"
sleep_after: 2
# Executes after earlier commands (after 2 sec)
- cmd: echo "2 seconds later"
{
"session_name": "Pause / skip command execution (command-level)",
"windows": [
{
"panes": [
{
"shell_command": [
"echo \"___$((11 + 1))___\"",
{
"cmd": "echo \"___$((1 + 3))___\"",
"sleep_before": 2
},
{
"cmd": "echo \"___$((1 + 3))___\""
},
{
"cmd": "echo \"Stuff rendering here!\"",
"sleep_after": 2
},
{
"cmd": "echo \"2 seconds later\""
}
]
}
]
}
]
}
Window 0: 1 pane, tiled❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Pause before a pane

sleep_before on a pane waits before it sends any of its commands.

session_name: Pause / skip command execution (pane-level)
windows:
- panes:
- # Wait 2 seconds before sending all commands in this pane
sleep_before: 2
shell_command:
- echo "___$((11 + 1))___"
- cmd: echo "___$((1 + 3))___"
- cmd: echo "___$((1 + 3))___"
- cmd: echo "Stuff rendering here!"
- cmd: echo "2 seconds later"
{
"session_name": "Pause / skip command execution (pane-level)",
"windows": [
{
"panes": [
{
"sleep_before": 2,
"shell_command": [
"echo \"___$((11 + 1))___\"",
{
"cmd": "echo \"___$((1 + 3))___\""
},
{
"cmd": "echo \"___$((1 + 3))___\""
},
{
"cmd": "echo \"Stuff rendering here!\""
},
{
"cmd": "echo \"2 seconds later\""
}
]
}
]
}
]
}
Window 0: 1 pane, tiled❯ echo "___$((11 + 1))___"❯ echo "___$((1 + 3))___"❯ echo "___$((1 + 3))___"❯ echo "Stuff rendering here!"❯ echo "2 seconds later"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep-pane-level.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Wait for a virtualenv

A setup command with sleep_before and sleep_after gives a virtualenv time to activate before the commands run.

session_name: virtualenv
shell_command_before:
# - cmd: source $(poetry env info --path)/bin/activate
# - cmd: source `pipenv --venv`/bin/activate
- cmd: source .venv/bin/activate
sleep_before: 1
sleep_after: 1
windows:
- panes:
- shell_command:
- ./manage.py runserver
{
"session_name": "virtualenv",
"shell_command_before": [
{
"cmd": "source .venv/bin/activate",
"sleep_before": 1,
"sleep_after": 1
}
],
"windows": [
{
"panes": [
{
"shell_command": [
"./manage.py runserver"
]
}
]
}
]
}
Window 0: 1 pane, tiled❯ ./manage.py runserver
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/sleep-virtualenv.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Keep commands out of history

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!\""
]
}
]
}
]
}
Window 0, appended: 1 pane, tiled❯ echo "window in the history!"
no layout set, so the port tiles the panes
Window 1, suppressed: 1 pane, tiled❯ echo "window not in the history!"
no layout set, so the port tiles the panes
Window 2, default: 1 pane, tiled❯ echo "session in the history!"
no layout set, so the port tiles the panes
Window 3, mixed: 3 panes, tiled❯ echo "command in the history!"❯ echo "command not in the history!"❯ echo "window in the history!"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/suppress-history.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Window index

window_index places a window at an index; a window without one takes the lowest free index.

session_name: Window index example
windows:
- window_name: zero
panes:
- echo "this window's index will be zero"
- window_name: five
panes:
- echo "this window's index will be five"
window_index: 5
- window_name: one
panes:
- echo "this window's index will be one"
{
"session_name": "Window index example",
"windows": [
{
"window_name": "zero",
"panes": [
"echo \"this window's index will be zero\""
]
},
{
"window_name": "five",
"panes": [
"echo \"this window's index will be five\""
],
"window_index": 5
},
{
"window_name": "one",
"panes": [
"echo \"this window's index will be one\""
]
}
]
}
Window 0, zero: 1 pane, tiled❯ echo "this window's index will be zero"
no layout set, so the port tiles the panes
Window 1, one: 1 pane, tiled❯ echo "this window's index will be one"
no layout set, so the port tiles the panes
Window 5, five: 1 pane, tiled❯ echo "this window's index will be five"
no layout set, so the port tiles the panes

Save the file as workspace.yaml and load it with:

tmux-workspace load workspace.yaml

Workspace file: packages/workspace-cli/tests/fixtures/tmuxp-examples/window-index.yaml. Tested by every tmuxp example workspace loads through the CLI (packages/workspace-cli/tests/tmuxp-examples.test.ts; a test runs the command).

Install @libtmux/workspace-cli

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.

Cooldown type
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.

Learn more at cooldowns.dev · Datadog Security Labs writeup.

$ npx -y @libtmux/workspace-cli --help
$ npx -y @libtmux/workspace-cli --help

npx ignores --min-release-age-exclude, so a cooldown here would also hold back the release this runs. This command runs without one.

$ npx -y --min-release-age=0 @libtmux/workspace-cli --help

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.

$ bunx --bun --minimum-release-age=0 @libtmux/workspace-cli --help

--bun runs the command on Bun. Without it, bunx runs the command on Node when Node is installed, because its shebang names node.

$ pnpm dlx @libtmux/workspace-cli --help
$ EXCLUDE='["@libtmux/workspace-cli","libtmux"]' && \
pnpm_config_minimum_release_age=10080 \
    pnpm_config_minimum_release_age_exclude="$EXCLUDE" \
    pnpm dlx @libtmux/workspace-cli --help
$ pnpm_config_minimum_release_age=0 pnpm dlx @libtmux/workspace-cli --help
$ yarn dlx @libtmux/workspace-cli --help
$ YARN_NPM_MINIMAL_AGE_GATE=7d \
    YARN_NPM_PREAPPROVED_PACKAGES=@libtmux/workspace-cli,libtmux \
    yarn dlx @libtmux/workspace-cli --help
$ YARN_NPM_MINIMAL_AGE_GATE=0 yarn dlx @libtmux/workspace-cli --help

Yarn refuses a release younger than its npmMinimalAgeGate, one day by default.

$ npm install -g @libtmux/workspace-cli
$ npm install -g \
    --min-release-age=7 \
    --min-release-age-exclude=@libtmux/workspace-cli \
    --min-release-age-exclude=libtmux \
    @libtmux/workspace-cli
$ npm install -g --min-release-age=0 @libtmux/workspace-cli

Puts tmux-workspace on PATH, so a workspace loads with tmux-workspace load ./workspace.yaml.

$ pnpm add -g @libtmux/workspace-cli
$ EXCLUDE='["@libtmux/workspace-cli","libtmux"]' && \
pnpm_config_minimum_release_age=10080 \
    pnpm_config_minimum_release_age_exclude="$EXCLUDE" \
    pnpm add -g @libtmux/workspace-cli
$ pnpm_config_minimum_release_age=0 pnpm add -g @libtmux/workspace-cli
$ bun add -g @libtmux/workspace-cli
$ bun add -g @libtmux/workspace-cli

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
Build the workspace from a program
examples/workspace/workspace.ts
export const DEVELOPMENT_WORKSPACE = {
session_name: "workspace-example",
windows: [
{ panes: ["sleep 30", "sleep 30"], window_name: "editor" },
{ panes: ["sleep 30"], window_name: "server" },
{ window_name: "logs" },
],
} satisfies WorkspaceInput;
/** Apply the package's declarative workspace to a server. */
export function buildWorkspace(server: Server): Promise<Session> {
return applyWorkspace(server, DEVELOPMENT_WORKSPACE);
}

Excerpt of examples/workspace/workspace.ts, which bun run typecheck && bun run test runs in the repository's CI (.github/workflows/typescript.yml).

Packages and integrations

API references

All TypeScript versions and install instructions

Esc

Type to search.

Reference previewOpen reference