Tmux#

You can use the tmux tool to run long-lived and/or interactive applications in a tmux session. Requires tmux to be installed.

This tool is suitable to run long-running commands or interactive applications that require user input. Examples of such commands: npm run dev, python3 server.py, python3 train.py, etc. It allows for inspecting pane contents and sending input.

Instructions

You can use the tmux tool to run long-lived and/or interactive applications in a tmux session.

### When to use tmux

Use tmux for interactive applications requiring ongoing keyboard input or output
inspection: REPLs, TUIs, interactive installers, and persistent processes you
need to revisit. Prefer tmux over the shell's `bg` command when the application
requires send-keys interaction or repeated pane inspection. Use `wait
<session_id> [timeout] [stable_time]` when you need output to stabilize before
continuing.

Examples

Running subagents

User

start subagent to fix lints in parallel

Assistant

Let's start a subagent in a new tmux session:tmux
new-session gptme --non-interactive "fix lint 1"
new-session gptme --non-interactive "fix lint 2"

Running specific agent

User

Ask Bob about his latest work

Assistant

Sure! Let's start a tmux session running Bob (~/bob/):tmux
new-session cd ~/bob && gptme --non-interactive 'What is your latest work?'

Managing a dev server

User	Start the dev server
Assistant	Certainly! To start the dev server we should use tmux: tmux new-session npm run dev
System	Running `npm run dev` in session gptme_1

User

Can you show me the current content of the pane?

Assistant

Of course! Let's inspect the pane content:tmux
inspect-pane gptme_1

System

`output
Server is running on localhost:5600
`

User	Stop the dev server
Assistant	I'll send 'Ctrl+C' to the pane to stop the server: tmux send-keys 0 C-c
System	Sent 'C-c' to pane 0

Get info from ncurses applications

User	start top and give me a summary
Assistant	Sure! Let's start the top command in a tmux session: tmux new-session top
System	Running `top` in session gptme_1. `output (output from top shown here) `
Assistant	The load is...

Send keys to a session

User	start ipython
Assistant	Let's start an ipython session: tmux new-session ipython
System	Running `ipython` in session 2. `output (output from ipython shown here) `

User	Run 'print("Hello, world!")' in the ipython session tmux send-keys 2 'print("Hello, world!")' Enter

Listing active sessions

User	List all active tmux sessions tmux list-sessions
System	Active tmux sessions ['0', 'gptme_1']

gptme.tools.tmux.execute_tmux(code: str | None, args: list[str] | None, kwargs: dict[str, str] | None) → Generator[Message, None, None]: Executes a command in tmux and returns the output.

gptme.tools.tmux.inspect_pane(pane_id: str, logdir: Path | None = None) → Message

Inspect the content of a tmux pane.

Parameters:

pane_id – The tmux pane ID to inspect
logdir – Optional directory to save full output if truncated

Returns:

Message with pane content (truncated if too long)

gptme.tools.tmux.wait_for_output(session_id: str, timeout: int = 60, stable_time: int = 3, logdir: Path | None = None) → Message

Wait for command output to stabilize in a tmux session.

Monitors the pane output and waits until it remains unchanged for stable_time seconds, or until timeout is reached.

Parameters:

session_id – The tmux session ID to monitor
timeout – Maximum time to wait in seconds (default: 60)
stable_time – Seconds of unchanged output to consider stable (default: 3)

Returns:

Message with the final output and status