tmux

Tools to let Solveit view tmux buffers

Overview

The tmux tools module provides functions to capture and inspect content from tmux sessions, windows, and panes. These are particularly useful when working with Solveit’s AI assistant to debug terminal sessions, share command output, or monitor multiple processes.

Using as Solveit Tools

To give the AI assistant access to your tmux sessions, simply reference the tools using the usual ampersand notation – tmux_tool_info() will add a note with the full list for you:

dialoghelper.tmux tools: &`[pane, list_panes, panes, list_windows, windows, list_sessions, sessions]`

This allows the assistant to inspect your terminal state and help with debugging, process monitoring, or understanding command outputs across multiple panes.

Function Hierarchy

The module is organized from specific to broad:

Each capture function returns the visible terminal content plus additional scrollback history (default 500 lines, which can be modified by calling set_default_history(n)).

Common Use Cases with Solveit’s AI

Debug errors across terminals: When something breaks in one pane, the AI can see all your terminals at once to understand context:

My script is failing in pane 1, can you help?

The AI sees your error messages, the commands you ran, and even what’s happening in other panes (like log files you might be tailing).

Monitor long-running processes: Check on multiple jobs without switching windows:

How are my training runs doing?

The AI can inspect all your windows - seeing if processes completed, checking for errors, or summarizing outputs from different experiments running in parallel.

Reconstruct lost commands: When you can’t remember what you typed earlier:

What was that curl command I used in the other window?

The AI can search through all your session history to find specific commands, even if they’ve scrolled off screen or are in a different window.

Using as Python Functions

You can also use these functions directly in code to search and analyze terminal content. Here are some examples:

Find all lines containing “error” across all sessions:

all_content = sessions(n=2000)
errors = [(path, line)
          for path, content in flatten_dict(all_content)
          for line in content.splitlines()
          if 'error' in line.lower()]

Find which pane contains a specific command:

found = {path: content for path, content in flatten_dict(windows(n=1000))
    if 'docker run' in content}

Details

def shell_ret(*args, capture_output=True, text=True, shell=True, ret=True, **kwargs):
    "Shortcut for `subprocess.run(shell=True)`"
    o = subprocess.run(*args, shell=shell, text=text, capture_output=capture_output, **kwargs)
    return (o.stdout or o.stderr) if ret else o

source

shell_ret

 shell_ret (cmd:str, capture_output:bool=True, text:bool=True,
            ret:bool=True, host:str=None, ip:str=None, user:str=None,
            keyfile:str=None)

Run shell command locally or over ssh (use host for alias, or ip/user/keyfile)

Type Default Details
cmd str
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile 
print(shell_ret('du -sh'))
568K    .

print(shell_ret('du -sh', host='hack'))
14G .

source

set_default_history

 set_default_history (n:int)

Set the default number of lines to capture from tmux history

The set_default_history function sets a global default for how many lines of scrollback history to capture when using tmux tools. This avoids having to specify the line count every time you call a tmux function.

The default is initially 500 lines, which includes the visible terminal plus scrollback.

source

pane

 pane (n:int=None, pane:int=None, session:str=None, window:int=None,
       capture_output:bool=True, text:bool=True, ret:bool=True,
       host:str=None, ip:str=None, user:str=None, keyfile:str=None)

Grab the tmux history in plain text

Type Default Details
n int None Number of scrollback lines to capture, in addition to visible area (None uses default_tmux_lines, which is 500 if not otherwise set)
pane int None Pane number to capture from
session str None Session name to target
window int None Window number to target
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile 
# print(pane(1))
# print(pane(1, host='hack'))

pane() captures the scrollback history from a specific tmux pane. You can specify which pane to capture using any combination of session, window, and pane numbers. If you don’t specify anything, it captures from the current pane.

n controls how many lines of scrollback to include beyond the visible area. If not specified, it uses the global default_tmux_lines value.

source

list_panes

 list_panes (session:str=None, window:int=None, capture_output:bool=True,
             text:bool=True, ret:bool=True, host:str=None, ip:str=None,
             user:str=None, keyfile:str=None)

List panes for a session/window (or current if none specified)

Type Default Details
session str None Session name to list panes from
window int None Window number to list panes from
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

list_panes() returns information about panes in current or specified window. Output includes pane numbers, dimensions, and active status.

print(list_panes(window=0))
0: [188x20] [history 1468/2000, 2851143 bytes] %3 (active)

print(list_panes(window=0, host='hack'))
0: [85x25] [history 1975/2000, 4839557 bytes] %3
1: [85x26] [history 2294/2000, 5024915 bytes] %21 (active)
2: [98x25] [history 2241/2000, 10188212 bytes] %5
3: [98x26] [history 0/2000, 1712 bytes] %22

source

panes

 panes (session:str=None, window:int=None, n:int=None,
        capture_output:bool=True, text:bool=True, ret:bool=True,
        host:str=None, ip:str=None, user:str=None, keyfile:str=None)

Grab history from all panes in a session/window

Type Default Details
session str None Session name to target
window int None Window number to target
n int None Number of scrollback lines to capture
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

panes() returns a dictionary with pane numbers as keys and their captured content as values. Useful for getting a snapshot of all panes in a window at once.

from pprint import pprint
# pprint(panes(window=0, n=10))
# pprint(panes(n=10, host='hack'))

source

list_windows

 list_windows (session:str=None, capture_output:bool=True, text:bool=True,
               ret:bool=True, host:str=None, ip:str=None, user:str=None,
               keyfile:str=None)

List all windows in a session

Type Default Details
session str None Session name to list windows from
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

list_windows() shows all windows in current or specified session. Output includes window numbers, names, pane counts, and markers for active (*) and previous (-) windows.

print(list_windows())
0: python3.12* (1 panes) [188x20] [layout ac80,188x20,0,0,3] @3 (active)

print(list_windows(host='hack'))
0: bash* (4 panes) [184x52] [layout c9b1,184x52,0,0{85x52,0,0[85x25,0,0,3,85x26,0,26,21],98x52,86,0[98x25,86,0,5,98x26,86,26,22]}] @0 (active)

source

windows

 windows (session:str=None, n:int=None, capture_output:bool=True,
          text:bool=True, ret:bool=True, host:str=None, ip:str=None,
          user:str=None, keyfile:str=None)

Grab history from all panes in all windows of a session

Type Default Details
session str None Session name to target
n int None Number of scrollback lines to capture
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

windows() returns a nested dictionary: window names/numbers as keys, each containing a dictionary of panes and their content. Captures entire session structure in one call.

# pprint(windows())
# pprint(windows(host='hack'))

source

list_sessions

 list_sessions (capture_output:bool=True, text:bool=True, ret:bool=True,
                host:str=None, ip:str=None, user:str=None,
                keyfile:str=None)

List all tmux sessions

Type Default Details
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

list_sessions() shows all tmux sessions. Output includes session names, window counts, creation time, and attachment status.

print(list_sessions())
jup: 1 windows (created Tue Dec  9 14:54:59 2025)
mx: 1 windows (created Wed Dec  3 16:27:09 2025)
solveit: 1 windows (created Mon Dec  1 13:34:56 2025)
solveit-test: 1 windows (created Mon Dec  1 16:46:51 2025)

print(list_sessions(host='hack'))
0: 1 windows (created Wed Oct  1 22:53:16 2025) (attached)

source

sessions

 sessions (n:int=None, capture_output:bool=True, text:bool=True,
           ret:bool=True, host:str=None, ip:str=None, user:str=None,
           keyfile:str=None)

Grab history from all panes in all windows of all sessions

Type Default Details
n int None Number of scrollback lines to capture
capture_output bool True
text bool True
ret bool True
host str None Optional SSH Host
ip str None Optional SSH IP
user str None Optional SSH user
keyfile str None Optional SSH keyfile

sessions() returns complete tmux state: all sessions, windows, and panes with their content. Useful for capturing everything at once or debugging complex tmux setups.

# pprint(sessions())
# pprint(sessions(host='hack'))

source

flatten_dict

 flatten_dict (d, parent_key='', sep='//')

Flatten nested dict into list of (key_path, value) tuples

flatten_dict converts nested dictionaries into a flat list of (key_path, value) tuples. This is particularly useful with tmux tools since windows() and sessions() return deeply nested structures. By flattening them, you can easily search all content without writing nested loops.

The key paths show exactly where content was found (e.g., "session1//0:bash//1" tells you it’s from session1, window 0 named bash, pane 1), making it simple to trace back to the source location.

nested = {
    'session1': {
        '0:bash': {0: 'some content', 1: 'more content'},
        '1:vim': {0: 'editing file'}
    }
}
for path, content in flatten_dict(nested): print(f"{path}: {content}")
session1//0:bash//0: some content
session1//0:bash//1: more content
session1//1:vim//0: editing file

source

tmux_tool_info

 tmux_tool_info ()

Add a the message below, showing the available tools, to Solveit

dialoghelper.tmux tools: &[pane, list_panes, panes, list_windows, windows, list_sessions, sessions]