Library vs CLI

tmuxp is a CLI tool. libtmux is the Python library it's built on. Both control tmux, but they serve different needs.

When to Use the CLI

Use tmuxp when:

• You want declarative workspace configs — define your layout in YAML, load it with one command
• You're setting up daily development environments — same windows, same panes, every time
• You need CI/CD tmux sessions — run {ref}tmuxp load -d <cli-load> in a script
• You prefer configuration over code — no Python needed

$ tmuxp load my-workspace.yaml

New to the format? Start with {ref}quickstart, then browse ready-to-load files in {ref}examples.

When to Use libtmux

Use libtmux directly when:

• You need dynamic logic — conditionals, loops, branching based on state
• You want to read pane output — capture what's on screen and react to it
• You're testing tmux interactions — libtmux provides pytest fixtures
• You need multi-server orchestration — manage multiple tmux servers programmatically
• The CLI's config format can't express what you need

import libtmux

server = libtmux.Server()
session = server.new_session("my-project")
window = session.new_window("editor")
pane = window.split()
pane.send_keys("vim .")

Concept Mapping

How tmuxp config keys map to libtmux API calls:

tmuxp YAML	libtmux equivalent
session_name: foo	{meth}server.new_session(session_name="foo") <libtmux.Server.new_session>
windows:	{meth}session.new_window(...) <libtmux.Session.new_window>
panes:	{meth}window.split(...) <libtmux.Window.split>
shell_command:	{meth}pane.send_keys(...) <libtmux.Pane.send_keys>
layout: main-vertical	{meth}window.select_layout("main-vertical") <libtmux.Window.select_layout>
start_directory: ~/project	{meth}session.new_window(start_directory="~/project") <libtmux.Session.new_window>
before_script:	Run via {mod}subprocess before building

What the CLI Can't Express

tmuxp configs are static declarations. They can't:

• Branch on conditions — "only create this pane if a file exists"
• Read pane output — "wait until the server is ready, then open the browser"
• React to state — "if this session already has 3 windows, add a 4th"
• Orchestrate across servers — "connect to both local and remote tmux"
• Build layouts dynamically — "create N panes based on a list of services"

For these, use libtmux directly. See the {ref}libtmux quickstart <libtmux:quickstart>.