tmux-python/libtmuxPublic

NotificationsYou must be signed in to change notification settings
Fork110
Star1.1k

⚙️ Python API / wrapper for tmux

License

MIT license

1.1k stars 110 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 2,179 Commits
.cursor/rules		.cursor/rules
.github		.github
.vim		.vim
docs		docs
src/libtmux		src/libtmux
tests		tests
.codecov.yml		.codecov.yml
.gitignore		.gitignore
.prettierrc		.prettierrc
.python-version		.python-version
.tmuxp.yaml		.tmuxp.yaml
.tool-versions		.tool-versions
.windsurfrules		.windsurfrules
CHANGES		CHANGES
CITATION.cff		CITATION.cff
LICENSE		LICENSE
MIGRATION		MIGRATION
Makefile		Makefile
README.md		README.md
TODO		TODO
conftest.py		conftest.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Repository files navigation

libtmux

libtmux is atyped Python library that provides a wrapper for interacting programmatically with tmux, a terminal multiplexer. You can use it to manage tmux servers,sessions, windows, and panes. Additionally,libtmux powerstmuxp, a tmux workspace manager.

libtmux builds upon tmux'starget andformats tocreate an object mapping to traverse, inspect and interact with livetmux sessions.

View thedocumentation,API information andarchitectural details.

Install

$pip install --user libtmux

Open a tmux session

Session namefoo, window namebar

$tmux new-session -s foo -n bar

Pilot your tmux session via python

$python

Useptpython,ipython, etc. for a nice shell with autocompletions:

$pip install --user ptpython

$ptpython

Connect to a live tmux session:

>>>importlibtmux>>>svr=libtmux.Server()>>>svrServer(socket_path=/tmp/tmux-.../default)

Tip: You can also usetmuxp'stmuxp shell to drop straight into yourcurrent tmux server / session / window pane.

Run any tmux command, respective of context:

Honors tmux socket name and path:

>>>server=Server(socket_name='libtmux_doctest')>>>server.cmd('display-message','hello world')<libtmux...>

New session:

>>>server.cmd('new-session','-d','-P','-F#{session_id}').stdout[0]'$2'

>>>session.cmd('new-window','-P').stdout[0]'libtmux...:2.0'

From raw command output, to a richWindow object (in practice and as shownlater, you'd useSession.new_window()):

>>>Window.from_window_id(window_id=session.cmd('new-window','-P','-F#{window_id}').stdout[0],server=session.server)Window(@22:...,Session($1libtmux_...))

Create a pane from a window:

>>>window.cmd('split-window','-P','-F#{pane_id}').stdout[0]'%2'

Raw output directly to aPane:

>>>Pane.from_pane_id(pane_id=window.cmd('split-window','-P','-F#{pane_id}').stdout[0],server=window.server)Pane(%...Window(@11:...,Session($1libtmux_...)))

List sessions:

>>>server.sessions[Session($1 ...),Session($0 ...)]

Filter sessions by attribute:

>>>server.sessions.filter(history_limit='2000')[Session($1 ...),Session($0 ...)]

Direct lookup:

>>>server.sessions.get(session_id="$1")Session($1 ...)

Filter sessions:

>>>server.sessions[0].rename_session('foo')Session($1foo)>>>server.sessions.filter(session_name="foo")[Session($1foo)]>>>server.sessions.get(session_name="foo")Session($1foo)

Control your session:

>>>sessionSession($1 ...)>>>session.rename_session('my-session')Session($1my-session)

Create new window in the background (don't switch to it):

>>>bg_window=session.new_window(attach=False,window_name="ha in the bg")>>>bg_windowWindow(@...2:hainthebg,Session($1 ...))# Session can search the window>>>session.windows.filter(window_name__startswith="ha")[Window(@...2:hainthebg,Session($1 ...))]# Directly>>>session.windows.get(window_name__startswith="ha")Window(@...2:hainthebg,Session($1 ...))# Clean up>>>bg_window.kill()

Close window:

>>>w=session.active_window>>>w.kill()

Grab remaining tmux window:

>>>window=session.active_window>>>window.split(attach=False)Pane(%2Window(@11:...Session($1 ...)))

Rename window:

>>>window.rename_window('libtmuxower')Window(@11:libtmuxower,Session($1 ...))

Split window (create a new pane):

>>>pane=window.split()>>>pane=window.split(attach=False)>>>pane.select()Pane(%3Window(@11:...,Session($1 ...)))>>>window=session.new_window(attach=False,window_name="test")>>>windowWindow(@22:test,Session($1 ...))>>>pane=window.split(attach=False)>>>panePane(%5Window(@22:test,Session($1 ...)))

Type inside the pane (send key strokes):

>>>pane.send_keys('echo hey send now')>>>pane.send_keys('echo hey',enter=False)>>>pane.enter()Pane(%1 ...)

Grab the output of pane:

>>>pane.clear()# clear the panePane(%1 ...)>>>pane.send_keys("cowsay 'hello'",enter=True)>>>print('\n'.join(pane.cmd('capture-pane','-p').stdout))# doctest: +SKIP$cowsay'hello'_______<hello>-------        \^__^         \  (oo)\_______            (__)\       )\/\||----w|||||...

Traverse and navigate:

>>>pane.windowWindow(@11:...,Session($1 ...))>>>pane.window.sessionSession($1 ...)

Python support

Unsupported / no security releases or bug fixes:

Python 2.x: The backports branch isv0.8.x.

Donations

Your donations fund development of new features, testing and support.Your money will go directly to maintenance and development of theproject. If you are an individual, feel free to give whatever feelsright for the value you get out of the project.

See donation options athttps://tony.sh/support.html.