RustHome

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.

MoreLess about this notice

libtmux for Rust

Rust-based tmux client

tmux client library for Rust. Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents

Product

Control tmux from Rust code 0.x Released; the API may change. Read more Core Library home →

Capability: Navigate tmux via a typed object graph

Navigate tmux via a typed object graph

use libtmux::{PaneWait, Server, SplitDirection, SplitOptions};
use std::{error::Error, time::Duration};
type ExampleError = Box<dyn Error>;
async fn work(server: &Server) -> Result<(), ExampleError> {
let session = server.new_session("demo").await?;
// Lay out the session: name its window, split it, add a second window.
let mut editor =
session.active_window().await?.ok_or("missing window")?;
editor.rename("editor").await?;
let left = editor.active_pane().await?.ok_or("missing pane")?;
let mut right =
left.split(SplitOptions::new(SplitDirection::Right)).await?;
let mut logs = session.new_window("logs").await?;
// Type a command into the new pane and wait for what it prints.
right.send_line("printf 'hello from %s\\n' tmux").await?;
let seen = right
.wait_for_text("hello from tmux", Duration::from_secs(5))
.await?;
if seen != PaneWait::Arrived {
return Err("The pane did not print hello from tmux".into());
}
// Move the focus an attached client sees: the pane, then the window.
right.select().await?;
logs.select().await?;
// Walk the objects: down from the server, then up from one pane.
let sessions = server.sessions().await?;
for each in sessions {
println!("session {}", each.name().to_string_lossy());
let windows = each.windows().await?;
for window in windows {
let name = window.name().to_string_lossy();
print!(" window {}:{}:", window.index(), name);
let panes = window.panes().await?;
for pane in panes {
print!(" {}", pane.id());
}
println!();
}
}
let window = right.window().await?.ok_or("missing window")?;
let owner = window.session().await?.ok_or("missing session")?;
println!(
"{} is in window {} of session {}",
right.id(),
window.name().to_string_lossy(),
owner.name().to_string_lossy(),
);
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory =
tempfile::Builder::new().prefix("home-").tempdir_in(root)?.keep();
let server = Server::builder()
.socket_path(directory.join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome =
tokio::time::timeout(Duration::from_secs(10), work(&server))
.await;
server.shutdown().await?;
outcome??;
Ok(())
}
use libtmux::{PaneWait, Server, SplitDirection, SplitOptions};
use std::{error::Error, time::Duration};
type ExampleError = Box<dyn Error>;
async fn work(server: &Server) -> Result<(), ExampleError> {
let session = server.new_session("demo").await?;
// Lay out the session: name its window, split it, add a second window.
let mut editor =
session.active_window().await?.ok_or("missing window")?;
editor.rename("editor").await?;
let left = editor.active_pane().await?.ok_or("missing pane")?;
let mut right =
left.split(SplitOptions::new(SplitDirection::Right)).await?;
let mut logs = session.new_window("logs").await?;
// Type a command into the new pane and wait for what it prints.
right.send_line("printf 'hello from %s\\n' tmux").await?;
let seen = right
.wait_for_text("hello from tmux", Duration::from_secs(5))
.await?;
if seen != PaneWait::Arrived {
return Err("The pane did not print hello from tmux".into());
}
// Move the focus an attached client sees: the pane, then the window.
right.select().await?;
logs.select().await?;
// Walk the objects: down from the server, then up from one pane.
let sessions = server.sessions().await?;
for each in sessions {
println!("session {}", each.name().to_string_lossy());
let windows = each.windows().await?;
for window in windows {
let name = window.name().to_string_lossy();
print!(" window {}:{}:", window.index(), name);
let panes = window.panes().await?;
for pane in panes {
print!(" {}", pane.id());
}
println!();
}
}
let window = right.window().await?.ok_or("missing window")?;
let owner = window.session().await?.ok_or("missing session")?;
println!(
"{} is in window {} of session {}",
right.id(),
window.name().to_string_lossy(),
owner.name().to_string_lossy(),
);
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory =
tempfile::Builder::new().prefix("home-").tempdir_in(root)?.keep();
let server = Server::builder()
.socket_path(directory.join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome =
tokio::time::timeout(Duration::from_secs(10), work(&server))
.await;
let closed = server.shutdown().await;
let mut failures = Vec::new();
match outcome {
Ok(Ok(())) => {}
Ok(Err(error)) => failures.push(format!("work: {error}")),
Err(error) => failures.push(format!("deadline: {error}")),
}
if let Err(error) = closed {
failures.push(format!("close executor: {error}"));
}
if failures.is_empty() {
Ok(())
} else {
Err(failures.join("; ").into())
}
}
use libtmux::{PaneWait, Server, SplitDirection, SplitOptions};
use std::{error::Error, time::Duration};
type ExampleError = Box<dyn Error>;
async fn work(server: &Server) -> Result<(), ExampleError> {
let session = server.new_session("demo").await?;
// Lay out the session: name its window, split it, add a second window.
let mut editor =
session.active_window().await?.ok_or("missing window")?;
editor.rename("editor").await?;
let left = editor.active_pane().await?.ok_or("missing pane")?;
let mut right =
left.split(SplitOptions::new(SplitDirection::Right)).await?;
let mut logs = session.new_window("logs").await?;
// Type a command into the new pane and wait for what it prints.
right.send_line("printf 'hello from %s\\n' tmux").await?;
let seen = right
.wait_for_text("hello from tmux", Duration::from_secs(5))
.await?;
if seen != PaneWait::Arrived {
return Err("The pane did not print hello from tmux".into());
}
// Move the focus an attached client sees: the pane, then the window.
right.select().await?;
logs.select().await?;
// Walk the objects: down from the server, then up from one pane.
let sessions = server.sessions().await?;
for each in sessions {
println!("session {}", each.name().to_string_lossy());
let windows = each.windows().await?;
for window in windows {
let name = window.name().to_string_lossy();
print!(" window {}:{}:", window.index(), name);
let panes = window.panes().await?;
for pane in panes {
print!(" {}", pane.id());
}
println!();
}
}
let window = right.window().await?.ok_or("missing window")?;
let owner = window.session().await?.ok_or("missing session")?;
println!(
"{} is in window {} of session {}",
right.id(),
window.name().to_string_lossy(),
owner.name().to_string_lossy(),
);
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory =
tempfile::Builder::new().prefix("home-").tempdir_in(root)?;
let server = Server::builder()
.socket_path(directory.path().join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome =
tokio::time::timeout(Duration::from_secs(10), work(&server))
.await;
let killed = server.kill().await;
let closed = server.shutdown().await;
if killed.is_err() || closed.is_err() {
directory.keep();
} else {
directory.close()?;
}
killed?;
closed?;
outcome??;
Ok(())
}
use libtmux::{PaneWait, Server, SplitDirection, SplitOptions};
use std::{error::Error, time::Duration};
type ExampleError = Box<dyn Error>;
async fn work(server: &Server) -> Result<(), ExampleError> {
let session = server.new_session("demo").await?;
// Lay out the session: name its window, split it, add a second window.
let mut editor =
session.active_window().await?.ok_or("missing window")?;
editor.rename("editor").await?;
let left = editor.active_pane().await?.ok_or("missing pane")?;
let mut right =
left.split(SplitOptions::new(SplitDirection::Right)).await?;
let mut logs = session.new_window("logs").await?;
// Type a command into the new pane and wait for what it prints.
right.send_line("printf 'hello from %s\\n' tmux").await?;
let seen = right
.wait_for_text("hello from tmux", Duration::from_secs(5))
.await?;
if seen != PaneWait::Arrived {
return Err("The pane did not print hello from tmux".into());
}
// Move the focus an attached client sees: the pane, then the window.
right.select().await?;
logs.select().await?;
// Walk the objects: down from the server, then up from one pane.
let sessions = server.sessions().await?;
for each in sessions {
println!("session {}", each.name().to_string_lossy());
let windows = each.windows().await?;
for window in windows {
let name = window.name().to_string_lossy();
print!(" window {}:{}:", window.index(), name);
let panes = window.panes().await?;
for pane in panes {
print!(" {}", pane.id());
}
println!();
}
}
let window = right.window().await?.ok_or("missing window")?;
let owner = window.session().await?.ok_or("missing session")?;
println!(
"{} is in window {} of session {}",
right.id(),
window.name().to_string_lossy(),
owner.name().to_string_lossy(),
);
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory =
tempfile::Builder::new().prefix("home-").tempdir_in(root)?;
let server = Server::builder()
.socket_path(directory.path().join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome =
tokio::time::timeout(Duration::from_secs(10), work(&server))
.await;
// kill stops our daemon; shutdown closes this client executor.
let killed = server.kill().await;
let closed = server.shutdown().await;
let cleanup_failed = killed.is_err() || closed.is_err();
let mut failures = Vec::new();
match outcome {
Ok(Ok(())) => {}
Ok(Err(error)) => failures.push(format!("work: {error}")),
Err(error) => failures.push(format!("deadline: {error}")),
}
if let Err(error) = killed {
failures.push(format!("stop owned daemon: {error}"));
}
if let Err(error) = closed {
failures.push(format!("close executor: {error}"));
}
if cleanup_failed {
let retained = directory.keep();
failures.push(format!("inspect {}", retained.display()));
} else if let Err(error) = directory.close() {
failures.push(format!("remove directory: {error}"));
}
if failures.is_empty() {
Ok(())
} else {
Err(failures.join("; ").into())
}
}
Example details
No tmux server yet

tmux before the first call: no server is running.

No tmux server yet

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

%0 sh
[demo]

tmux after Server.new_session: added session demo.

%0 sh
[demo]

tmux after Session.active_window: unchanged.

%0 sh
[demo]

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

%0 sh
[demo]

tmux after Window.active_pane: unchanged.

%0 sh
%1 sh
[demo]

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

%0 sh
%1 sh
[demo]

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

%0 sh
%1 sh
[demo]

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

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

tmux after Pane.wait_for_text: read pane %1.

%0 sh
%1 sh
0
$ 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.sessions: unchanged.

%2 sh
[demo]

tmux after Session.windows: unchanged.

%2 sh
[demo]

tmux after Window.panes: unchanged.

%2 sh
[demo]

tmux after Window.panes: unchanged.

%2 sh
[demo]

tmux after Pane.window: unchanged.

%2 sh
[demo]

tmux after Window.session: unchanged.

No sessions

tmux after Server.kill: the server has exited.

No sessions

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

  1. Before the first call

    No tmux server is running yet.

  2. ServerBuilder.build returned Server

    {
    "socket": "tmux.sock",
    "configFile": "/dev/null"
    }

    The call sent no tmux command.

  3. Server.new_session returned Session

    {
    "id": "$0",
    "name": "demo"
    }
    1 tmux command, 1 that changes tmux
    1. new-session -d -P -F #{q:session_id}=#{q:session_activity}=#{q:session_attached}=#{q:session_created}=#{q:session_last_attached}=#{q:session_many_attached}=#{q:session_name}=#{q:session_path}=#{q:session_windows}= -s demo \$0=1793886425=0=1793886425==0=demo=/tmp/marked=1=

    Before these, the library asked tmux about itself 4 times (its version, its daemon, how a control client reads escapes).

  4. Session.active_window returned Option<Window>

    {
    "id": "@0",
    "name": "sh"
    }
    1 tmux command
    1. list-windows -t $0 -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window_flags}=#{q:window_la… @0=1793886425=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%0\"\}\}=sh=1=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%0\"\}\}=80=0=\$0=0=1=0=0=1=\*=0=0=0=\*=0=0=1=0==1=demo=1=demo=
  5. Window.rename returned &mut Window

    {
    "id": "@0",
    "name": "editor"
    }
    2 tmux commands, 1 that changes tmux
    1. rename-window -t @0 -- editor no output
    2. list-windows -t $0 -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window_flags}=#{q:window_la… @0=1793886425=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%0\"\}\}=editor=1=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%0\"\}\}=80=0=\$0=0=1=0=0=1=\*=0=0=0=\*=0=0=1=0==1=demo=1=demo=
  6. Window.active_pane returned Option<Pane>

    {
    "id": "%0"
    }
    1 tmux command
    1. list-panes -t @0 -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:orig… \%0=4294967295=4294967295=0=\ =1=2=0=1060=2000=0=0=0=0=0=0=0=0=0=0=1=1=1=1=1=default=23=sh=/tmp/marked=0====default=\*=0=24=0=0=0=0=0=0===0=hidden=2929144=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==23=0=0=1=\$0=@0=0=
  7. Pane.split returned Pane

    {
    "id": "%1"
    }
    1 tmux command, 1 that changes tmux
    1. split-window -P -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:origi… \%1=4294967295=4294967295=0=\ =1=0=0=960=2000=0=0=0=0=0=0=0=0=0=0=0=1=0=1=1=default=23=sh=/tmp/marked=0====default==0=24=0=1=0=0=41=0===0=hidden=2929481=0==79===/tmp/marked=0=8,16,24,32=host=0=/dev/pts/16=0=39=41=0=1=0==23=0=0=1=\$0=@0=0=
  8. Session.new_window returned Window

    {
    "id": "@1",
    "name": "logs"
    }
    1 tmux command, 1 that changes tmux
    1. new-window -P -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window_flags}=#{q:window_last_fl… @1=1793886427=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%2\"\}\}=logs=1=\{\"V\":2,\"L\":\{\"t\":\"p\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"a\":true,\"i\":0,\"I\":\"\%2\"\}\}=80=0=\$0=1=0=0=0=1==0=0=0==0=0=0=0==0==1=demo=
  9. Pane.send_line returned ()

    null
    1 tmux command, 1 that changes tmux
    1. send-keys -t %1 -l -- 'printf '\''hello from %s\n'\'' tmux ' no output
  10. Pane.wait_for_text returned PaneWait

    "Arrived"
    1 tmux command
    1. display-message -p -t %1 -F #{pane_dead} ; capture-pane -p -t %1 -S - -J 0 $ printf 'hello from %s\n' tmux hello from tmux $
  11. Pane.select returned &mut Pane

    {
    "id": "%1"
    }
    2 tmux commands, 1 that changes tmux
    1. select-pane -t %1 no output
    2. list-panes -t %1 -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:orig… \%0=4294967295=4294967295=0=\ =1=2=0=1060=2000=0=0=0=0=0=0=0=0=0=0=0=1=1=0=1=default=23=sh=/tmp/marked=0====default=-=0=24=0=0=0=1=0=0===0=hidden=2929144=0==39===/tmp/marked=0=8,16,24,32=host=0=/dev/pts/14=0=40=0=0=1=0==23=0=0=1=\$0=@0=0= \%1=4294967295=4294967295=0=\ =1=2=2=1295=2000=0=0=0=0=0=0=0=0=0=0=1=1=0=1=1=default=23=sh=/tmp/marked=0…
  12. Window.select returned &mut Window

    {
    "id": "@1",
    "name": "logs"
    }
    2 tmux commands, 1 that changes tmux
    1. select-window -t @1 no output
    2. list-windows -t $0 -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window_flags}=#{q:window_la… @0=1793886428=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0,\"i\":0,\"I\":\"\%0\"\},\{\"t\":\"p\",\"w\":39,\"h\":24,\"x\":41,\"y\":0,\"a\":true,\"i\":1,\"I\":\"\%1\"\}]\}\}=editor=2=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0…
  13. Server.sessions returned Vec<Session>

    [
    "$0"
    ]
    1 tmux command
    1. list-sessions -F #{q:session_id}=#{q:session_activity}=#{q:session_attached}=#{q:session_created}=#{q:session_last_attached}=#{q:session_many_attached}=#{q:session_name}=#{q:session_path}=#{q:session_windows}= \$0=1793886425=0=1793886425==0=demo=/tmp/marked=2=
  14. Session.windows returned Vec<Window>

    [
    "@0",
    "@1"
    ]
    1 tmux command
    1. list-windows -t $0 -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window_flags}=#{q:window_la… @0=1793886428=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0,\"i\":0,\"I\":\"\%0\"\},\{\"t\":\"p\",\"w\":39,\"h\":24,\"x\":41,\"y\":0,\"a\":true,\"i\":1,\"I\":\"\%1\"\}]\}\}=editor=2=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0…
  15. Window.panes returned Vec<Pane>

    [
    "%0",
    "%1"
    ]
    1 tmux command
    1. list-panes -t @0 -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:orig… \%0=4294967295=4294967295=0=\ =1=2=0=1060=2000=0=0=0=0=0=0=0=0=0=0=0=1=1=0=1=default=23=sh=/tmp/marked=0====default=-=0=24=0=0=0=1=0=0===0=hidden=2929144=0==39===/tmp/marked=0=8,16,24,32=host=0=/dev/pts/14=0=40=0=0=1=0==23=0=0=1=\$0=@0=0= \%1=4294967295=4294967295=0=\ =1=2=2=1295=2000=0=0=0=0=0=0=0=0=0=0=1=1=0=1=1=default=23=sh=/tmp/marked=0…
  16. Window.panes returned Vec<Pane>

    [
    "%2"
    ]
    1 tmux command
    1. list-panes -t @1 -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:orig… \%2=4294967295=4294967295=0=\ =1=2=0=1060=2000=0=0=0=0=0=0=0=0=0=0=1=1=1=1=1=default=23=sh=/tmp/marked=0====default=\*=0=24=0=0=0=0=0=0===0=hidden=2929597=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==23=0=0=1=\$0=@1=1=
  17. Pane.window returned Option<Window>

    {
    "id": "@0",
    "name": "editor"
    }
    1 tmux command
    1. list-panes -t %1 -f #{==:#{pane_id},%1} -F #{q:window_id}=#{q:window_activity}=#{q:window_cell_height}=#{q:window_cell_width}=#{q:window_height}=#{q:window_layout}=#{q:window_name}=#{q:window_panes}=#{q:window_visible_layout}=#{q:window_width}=#{q:window_zoomed_flag}=#{q:session_id}=#{q:window_index}=#{q:window_active}=#{q:window_activity_flag}=#{q:window_bell_flag}=#{q:window_end_flag}=#{q:window… @0=1793886428=32=16=24=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0,\"i\":0,\"I\":\"\%0\"\},\{\"t\":\"p\",\"w\":39,\"h\":24,\"x\":41,\"y\":0,\"a\":true,\"i\":1,\"I\":\"\%1\"\}]\}\}=editor=2=\{\"V\":2,\"L\":\{\"t\":\"h\",\"w\":80,\"h\":24,\"x\":0,\"y\":0,\"c\":\[\{\"t\":\"p\",\"w\":40,\"h\":24,\"x\":0,\"y\":0,\"l\":0…
  18. Window.session returned Option<Session>

    {
    "id": "$0",
    "name": "demo"
    }
    1 tmux command
    1. list-sessions -F #{q:session_id}=#{q:session_activity}=#{q:session_attached}=#{q:session_created}=#{q:session_last_attached}=#{q:session_many_attached}=#{q:session_name}=#{q:session_path}=#{q:session_windows}= \$0=1793886425=0=1793886425==0=demo=/tmp/marked=2=
  19. Server.kill returned Result<(), Error>

    null
    1 tmux command, 1 that changes tmux
    1. kill-server no output

    Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

  20. Server.shutdown returned Result<(), Error>

    null

    The call sent no tmux command.

1/18
Run this example

POSIX shell, tmux 3.3a or newer, rustup with Rust 1.97.1 (rust-toolchain.toml), and a C linker.

Save the program above as src/main.rs 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.

Cargo.toml
[package]
name = "libtmux-home-quickstart"
version = "0.0.0"
edition = "2024"
publish = false
[dependencies]
libtmux = "0.1.2"
tempfile = "3.20"
tokio = { version = "1.40", features = ["macros", "rt", "time"] }
Cargo.lock
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "aho-corasick"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
dependencies = [
"memchr",
]
[[package]]
name = "bitflags"
version = "2.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
[[package]]
name = "bytes"
version = "1.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
[[package]]
name = "caseless"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8b6fd507454086c8edfd769ca6ada439193cdb209c7681712ef6275cccbfe5d8"
dependencies = [
"unicode-normalization",
]
[[package]]
name = "cfg-if"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
[[package]]
name = "errno"
version = "0.3.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
"windows-sys",
]
[[package]]
name = "fastrand"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "getrandom"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"libc",
"r-efi",
]
[[package]]
name = "libc"
version = "0.2.191"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
[[package]]
name = "libtmux"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a7ec00257bb76e43923acb335470657d5d427a8bc802e7c51b611b268c052ea3"
dependencies = [
"caseless",
"regex",
"rustix",
"thiserror",
"tokio",
]
[[package]]
name = "libtmux-home-quickstart"
version = "0.0.0"
dependencies = [
"libtmux",
"tempfile",
"tokio",
]
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "mio"
version = "1.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee"
dependencies = [
"libc",
"wasi",
"windows-sys",
]
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "pin-project-lite"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "r-efi"
version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "regex"
version = "1.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
dependencies = [
"aho-corasick",
"memchr",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "regex-automata"
version = "0.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
dependencies = [
"aho-corasick",
"memchr",
"regex-syntax",
]
[[package]]
name = "regex-syntax"
version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "rustix"
version = "1.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa"
dependencies = [
"bitflags",
"errno",
"libc",
"linux-raw-sys",
"windows-sys",
]
[[package]]
name = "signal-hook-registry"
version = "1.4.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
dependencies = [
"errno",
"libc",
]
[[package]]
name = "syn"
version = "3.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "tempfile"
version = "3.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [
"fastrand",
"getrandom",
"once_cell",
"rustix",
"windows-sys",
]
[[package]]
name = "thiserror"
version = "2.0.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
dependencies = [
"thiserror-impl",
]
[[package]]
name = "thiserror-impl"
version = "2.0.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "tinyvec"
version = "1.13.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
[[package]]
name = "tokio"
version = "1.54.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3"
dependencies = [
"bytes",
"libc",
"mio",
"pin-project-lite",
"signal-hook-registry",
"tokio-macros",
"windows-sys",
]
[[package]]
name = "tokio-macros"
version = "2.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
dependencies = [
"proc-macro2",
"quote",
"syn",
]
[[package]]
name = "unicode-ident"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
[[package]]
name = "unicode-normalization"
version = "0.1.26"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "75cd3fb03d5288b3ba9a1ee103ac7e9cbb59f0b03d64f8ddfcc04dd42758a85d"
dependencies = [
"tinyvec",
]
[[package]]
name = "wasi"
version = "0.11.1+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.61.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
dependencies = [
"windows-link",
]
rust-toolchain.toml
[toolchain]
channel = "1.97.1"
components = ["clippy", "rust-src", "rustfmt"]
profile = "minimal"

Setup and run

cargo build --locked --jobs 2
unset TMUX TMUX_PANE
export ENV=/dev/null BASH_ENV=/dev/null SHELL=/bin/sh
cargo run --quiet --locked

Expected output

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

Send keys

//! Send literal text and a named Enter key to a ready shell.
use std::error::Error;
use std::time::Duration;
use libtmux::{NewSessionOptions, PaneWait, Server};
type ExampleError = Box<dyn Error>;
async fn demonstrate(server: &Server) -> Result<(), ExampleError> {
let session = server
.new_session(
NewSessionOptions::new("input").command("env ENV=/dev/null PS1='api-ready> ' sh"),
)
.await?;
let panes = session.panes().await?;
let pane = panes.first().ok_or("session has no pane")?;
if pane
.wait_for_text("api-ready>", Duration::from_secs(5))
.await?
!= PaneWait::Arrived
{
return Err("shell prompt did not become ready".into());
}
pane.send_keys("printf '\\nC-c is text\\n'").await?;
pane.send_key_names(["Enter"]).await?;
loop {
let lines = pane.capture().await?;
if lines.iter().any(|line| line.as_bytes() == b"C-c is text") {
break;
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
println!("input: C-c is text");
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory = tempfile::Builder::new()
.prefix("api-input-")
.tempdir_in(root)?;
std::fs::write(
directory.path().join("owner"),
std::process::id().to_string(),
)?;
let server = Server::builder()
.socket_path(directory.path().join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome = tokio::time::timeout(Duration::from_secs(10), demonstrate(&server)).await;
// Stop the owned daemon before closing the client executor.
let killed = server.kill().await;
let closed = server.shutdown().await;
let cleanup_failed = killed.is_err() || closed.is_err();
let mut failures = Vec::new();
match outcome {
Ok(Ok(())) => {}
Ok(Err(error)) => failures.push(format!("example failed: {error}")),
Err(error) => failures.push(format!("example deadline: {error}")),
}
if let Err(error) = killed {
failures.push(format!("daemon cleanup: {error}"));
}
if let Err(error) = closed {
failures.push(format!("executor cleanup: {error}"));
}
if cleanup_failed {
let retained = directory.keep();
failures.push(format!("inspect retained directory {}", retained.display()));
} else if let Err(error) = directory.close() {
failures.push(format!("directory cleanup: {error}"));
}
if failures.is_empty() {
Ok(())
} else {
Err(failures.join("; ").into())
}
}
No tmux server yet

tmux before the first call: no server is running.

No tmux server yet

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

%0 sh
[input]

tmux after Server.new_session: added session input.

%0 sh
[input]

tmux after Session.panes: unchanged.

%0 sh
0
api-ready>
[input]

tmux after Pane.wait_for_text: read pane %0.

%0 sh
0
api-ready>
[input]

tmux after Pane.send_keys: sent keys to pane %0.

%0 sh
0
api-ready>
[input]

tmux after Pane.send_key_names: sent keys to pane %0.

%0 sh
api-ready> printf '\nC-c is text\n'

C-c is text
api-ready>
[input]

tmux after Pane.capture: read pane %0.

No sessions

tmux after Server.kill: the server has exited.

No sessions

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

  1. Before the first call

    No tmux server is running yet.

  2. ServerBuilder.build returned Server

    {
    "socket": "tmux.sock",
    "configFile": "/dev/null"
    }

    The call sent no tmux command.

  3. Server.new_session returned Session

    {
    "id": "$0",
    "name": "input"
    }
    1 tmux command, 1 that changes tmux
    1. new-session -d -P -F #{q:session_id}=#{q:session_activity}=#{q:session_attached}=#{q:session_created}=#{q:session_last_attached}=#{q:session_many_attached}=#{q:session_name}=#{q:session_path}=#{q:session_windows}= -s input -- 'env ENV=/dev/null PS1='\''api-ready> '\'' sh' \$0=1793875335=0=1793875335==0=input=/tmp/marked=1=

    Before these, the library asked tmux about itself 4 times (its version, its daemon, how a control client reads escapes).

  4. Session.panes returned Vec<Pane>

    [
    "%0"
    ]
    1 tmux command
    1. list-panes -s -t $0 -F #{q:pane_id}=#{q:alternate_saved_x}=#{q:alternate_saved_y}=#{q:bracket_paste_flag}=#{q:cursor_character}=#{q:cursor_flag}=#{q:cursor_x}=#{q:cursor_y}=#{q:history_bytes}=#{q:history_limit}=#{q:history_size}=#{q:insert_flag}=#{q:keypad_cursor_flag}=#{q:keypad_flag}=#{q:mouse_all_flag}=#{q:mouse_any_flag}=#{q:mouse_button_flag}=#{q:mouse_sgr_flag}=#{q:mouse_standard_flag}=#{q:o… \%0=4294967295=4294967295=0=\ =1=11=0=1060=2000=0=0=0=0=0=0=0=0=0=0=1=1=1=1=1=default=23=sh=/tmp/marked=0====default=\*=0=24=0=0=0=0=0=0===0=hidden=2570144=0==79==\"env\ ENV\=/dev/null\ PS1\=\'api-ready\>\ \'\ sh\"=/tmp/marked=0=8,16,24,32,40,48,56,64,72=host=0=/dev/pts/14=0=80=0=0=1=0==23=0=0=1=\$0=@0=0=
  5. Pane.wait_for_text returned PaneWait

    "Arrived"
    1 tmux command
    1. display-message -p -t %0 -F #{pane_dead} ; capture-pane -p -t %0 -S - -J 0 api-ready>
  6. Pane.send_keys returned ()

    null
    1 tmux command, 1 that changes tmux
    1. send-keys -t %0 -l -- 'printf '\''\nC-c is text\n'\''' no output
  7. Pane.send_key_names returned ()

    null
    1 tmux command, 1 that changes tmux
    1. send-keys -t %0 -- Enter no output
  8. Pane.capture returned Vec<TmuxText>

    [
    "api-ready> printf '\\nC-c is text\\n'",
    "",
    "C-c is text",
    "api-ready>",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    "",
    ""
    ]
    1 tmux command
    1. capture-pane -p -t %0 api-ready> printf '\nC-c is text\n' C-c is text api-ready>
  9. Server.kill returned Result<(), Error>

    null
    1 tmux command, 1 that changes tmux
    1. kill-server no output

    Before these, the library asked tmux about itself 1 time (its version, its daemon, how a control client reads escapes).

  10. Server.shutdown returned Result<(), Error>

    null

    The call sent no tmux command.

1/9

Create windows

crates/libtmux/examples/api_creation.rs
//! Create a session and window, then split a window and a pane.
use std::error::Error;
use std::time::Duration;
use libtmux::{NewSessionOptions, NewWindowOptions, Server, SplitDirection, SplitOptions};
type ExampleError = Box<dyn Error>;
fn check(condition: bool, message: &str) -> Result<(), ExampleError> {
if condition {
Ok(())
} else {
Err(message.into())
}
}
async fn demonstrate(server: &Server) -> Result<(), ExampleError> {
let session = server
.new_session(
NewSessionOptions::new("work")
.window_name("editor")
.command("cat"),
)
.await?;
let window = session
.new_window(NewWindowOptions::new("logs").command("cat"))
.await?;
let pane = window
.split(SplitOptions::new(SplitDirection::Below).command("cat"))
.await?;
pane.split(SplitOptions::new(SplitDirection::Right).command("cat"))
.await?;
check(
session.windows().await?.len() == 2,
"expected two session windows",
)?;
check(
window.panes().await?.len() == 3,
"expected three panes in split window",
)?;
check(
server.panes().await?.len() == 4,
"expected four panes on server",
)?;
println!("creation: 2 windows, 4 panes");
Ok(())
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), ExampleError> {
let root = std::path::Path::new("/tmp/libtmux-rs-dev");
std::fs::create_dir_all(root)?;
let directory = tempfile::Builder::new()
.prefix("api-creation-")
.tempdir_in(root)?;
std::fs::write(
directory.path().join("owner"),
std::process::id().to_string(),
)?;
let server = Server::builder()
.socket_path(directory.path().join("tmux.sock"))
.config_file("/dev/null")
.default_timeout(Duration::from_secs(5))
.build()?;
let outcome = tokio::time::timeout(Duration::from_secs(10), demonstrate(&server)).await;
// Stop the owned daemon before closing the client executor.
let killed = server.kill().await;
let closed = server.shutdown().await;
let cleanup_failed = killed.is_err() || closed.is_err();
let mut failures = Vec::new();
match outcome {
Ok(Ok(())) => {}
Ok(Err(error)) => failures.push(format!("example failed: {error}")),
Err(error) => failures.push(format!("example deadline: {error}")),
}
if let Err(error) = killed {
failures.push(format!("daemon cleanup: {error}"));
}
if let Err(error) = closed {
failures.push(format!("executor cleanup: {error}"));
}
if cleanup_failed {
let retained = directory.keep();
failures.push(format!("inspect retained directory {}", retained.display()));
} else if let Err(error) = directory.close() {
failures.push(format!("directory cleanup: {error}"));
}
if failures.is_empty() {
Ok(())
} else {
Err(failures.join("; ").into())
}
}

Install libtmux

cargoFrom Git
Terminal
Terminal
libtmux 0.1.2 0.x crates.io
$ cargo add libtmux
$ cargo add libtmux \
    --git https://github.com/libtmux/libtmux-rs \
    --tag libtmux@v0.1.2

Pins the tagged source; the registry release is the default.

MCP

Give an assistant tmux tools concept Working example; may change without notice. Read more MCP home →

tmux through MCP

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.

AgentList the panes, each with its window id.

list_panes Inspect {}

AgentSplit the pane the list returned (%0) in two.

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

AgentRead the window's layout, which tmux calls window_layout, through the pane the list returned (%0).

get_tmux_variables Inspect {"names":["window_layout"],"pane":"%0"}

AgentRun the tests in the pane the list returned (%0).

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

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

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

AgentRemove the session once the result is read.

kill_session Teardown {"session":"checks"}

Requests only: no recorded results for Rust yet.

Install tmux-mcp

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

Terminal
Terminal
Terminal
claude_desktop_config.json
Terminal
.codex/config.toml
Terminal
Terminal
.cursor/mcp.json
~/.cursor/mcp.json
Terminal
Terminal
~/.gemini/config/mcp_config.json
Terminal
tmux-mcp concept crates.io
First
$ cargo install tmux-mcp
$ claude mcp add tmux -- tmux-mcp
First
$ cargo install tmux-mcp
$ claude mcp add tmux --scope user -- tmux-mcp
First
$ cargo install tmux-mcp
$ claude mcp add tmux --scope project -- tmux-mcp
First
$ cargo install tmux-mcp
{
    "mcpServers": {
        "tmux": {
            "command": "tmux-mcp"
        }
    }
}
First
$ cargo install tmux-mcp
$ codex mcp add tmux -- tmux-mcp
First
$ cargo install tmux-mcp
[mcp_servers.tmux]
command = "tmux-mcp"
First
$ cargo install tmux-mcp
$ gemini mcp add --scope user tmux tmux-mcp
First
$ cargo install tmux-mcp
$ gemini mcp add --scope project tmux tmux-mcp
First
$ cargo install tmux-mcp
{
    "mcpServers": {
        "tmux": {
            "command": "tmux-mcp"
        }
    }
}
First
$ cargo install tmux-mcp
{
    "mcpServers": {
        "tmux": {
            "command": "tmux-mcp"
        }
    }
}
First
$ cargo install tmux-mcp
$ grok mcp add --scope user tmux -- tmux-mcp
First
$ cargo install tmux-mcp
$ grok mcp add --scope project tmux -- tmux-mcp
First
$ cargo install tmux-mcp
{
    "mcpServers": {
        "tmux": {
            "command": "tmux-mcp"
        }
    }
}
First
$ cargo install tmux-mcp
$ opencode mcp add tmux -- tmux-mcp

Writes ~/.claude.json (this project).

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ~/.claude.json (all projects).

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes .mcp.json (in repo, version-controlled).

The installed tmux-mcp binary speaks MCP on stdin and stdout.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ~/.codex/config.toml.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

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

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ~/.gemini/settings.json.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes .gemini/settings.json (in repo).

The installed tmux-mcp binary speaks MCP on stdin and stdout.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ~/.grok/config.toml.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ./.grok/config.toml (in repo).

The installed tmux-mcp binary speaks MCP on stdin and stdout.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Writes ~/.config/opencode/opencode.jsonc.

The installed tmux-mcp binary speaks MCP on stdin and stdout.

Embed the server in a program
crates/tmux-mcp/examples/readonly.rsExcerpt · lines 14–30
use libtmux::Server;
use rmcp::ServiceExt as _;
use rmcp::transport::stdio;
use tmux_mcp::{Selection, TmuxTools};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let tools = TmuxTools::builder(Server::new()?)
.selection(Selection::parse(Some("inspect"), None, None)?)
.build();
// stdout carries the protocol, so this goes to stderr.
eprintln!("serving {} inspect tools", tools.offered().len());
tools.serve(stdio()).await?.waiting().await?;
Ok(())
}

Excerpt of crates/tmux-mcp/examples/readonly.rs. This program is tested on every change.

Workspace Manager

Load a workspace file concept Working example; may change without notice. Read more Workspace Manager home →

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/3-pane.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/shorthands.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/2-pane-vertical.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/4-pane.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/main-pane-height.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/session-environment.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/start-directory.yaml. Tested by tmuxp_start_directory_example_builds_where_tmuxp_does (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/2-pane-synchronized.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/blank-panes.yaml. Tested by tmuxp_blank_pane_examples_build (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/env-variables.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/focus-window-and-panes.yaml. Tested by a_blank_pane_is_a_pane_without_a_command (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/main-pane-height-percentage.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/minimal.yaml. Tested by tmuxp_blank_pane_examples_build (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/options.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/pane-shell.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/skip-send.yaml. Tested by a_command_may_carry_its_own_settings (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/skip-send-pane-level.yaml. Tested by a_command_may_carry_its_own_settings (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/sleep.yaml. Tested by a_command_may_carry_its_own_settings (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/sleep-pane-level.yaml. Tested by a_command_may_carry_its_own_settings (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/sleep-virtualenv.yaml. Tested by a_command_may_carry_its_own_settings (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/suppress-history.yaml. Tested by commands_stay_out_of_history_unless_the_file_says_otherwise (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

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

Workspace file: crates/tmux-workspace/tests/fixtures/tmuxp/window-index.yaml. Tested by every_tmuxp_example_parses (crates/tmux-workspace/tests/build.rs; parsed by the library in a test; the command is not run).

Install tmux-workspace

The workspace package is separate from the core library.

cargo
Terminal
tmux-workspace concept crates.io
$ cargo install --locked tmux-workspace
Then
$ tmux-workspace load ./workspace.yaml

Needs Rust 1.85 or newer. This builds and installs the native CLI; run tmux-workspace --help afterward.

Packages and integrations

API references

Example programs, each run by the port's CI:

Esc
Search in

Type to search.

Reference previewOpen reference