Zentty

Zentty Docs

tmux Compatibility

Zentty can satisfy tmux-style pane operations for tools that expect tmux, while still rendering everything as native Zentty panes.

Applies to current public Zentty builds. Last updated May 11, 2026.

Why It Exists

Some agent tools coordinate multi-pane work by shelling out to tmux. Zentty's Agent Teams mode puts a bundled tmux shim on PATH so those calls can be translated into native Zentty pane operations instead of launching a separate tmux server inside the terminal.

Should You Enable It

Enable whenAn agent orchestrator launches subagents with tmux commands and you want native Zentty panes, sidebar status, and normal restore behavior.
Leave off whenYou rely on full tmux sessions, attach/detach workflows, tmux plugins, or status-line configuration.

How Calls Are Routed

The shim re-execs into a hidden zentty __tmux-compat subcommand. The CLI strips tmux global options such as -S, forwards supported subcommands to the running Zentty instance, and validates the normal pane routing environment before changing panes. 

tmux split-window -h
tmux select-pane -L
tmux resize-pane -R
tmux wait-for -S ready

Worked Example

  1. An agent starts in the leader pane with Agent Teams enabled.
  2. The tool runs tmux split-window -h; Zentty creates a native team column to the right.
  3. The tool runs tmux send-keys; Zentty sends the subagent launch text to that pane.
  4. The tool runs tmux wait-for -S ready; the shim writes a local signal scoped to the Zentty instance.
  5. When the subagent exits, tmux kill-pane closes the native pane and the team anchor dissolves if it was the last one.

Supported Commands

tmux Command Zentty Behavior Notes
split-window / splitw Create a native Zentty pane. First team pane opens in a golden-ratio column; later panes stack in that team column.
send-keys / send Send text to a target pane or launch a deferred pane command.
select-pane / selectp Update active pane selection and optional pane title.
kill-pane / killp Close a pane and dissolve team anchors when the last subagent exits.
kill-window / killw Close the leader pane or targeted pane.
list-panes / lsp Render tmux-style pane rows with a supported -F format.
list-windows / lsw Expose worklanes as tmux windows inside the current Zentty window.
display-message / display Render pane/worklane format variables.
select-layout / selectl Supports main-vertical and even-vertical for agent-team balancing.
resize-pane / resizep Honors team-width intent while preserving Zentty's golden split.
capture-pane / capturep Read visible text and scrollback, with line-limit support from -S.
set-buffer, load-buffer, show-buffer, save-buffer Local buffer storage for agent workflows.
wait-for / wait Local signal files scoped by Zentty instance or worklane. Default timeout is 30 seconds; --timeout overrides it.
show-options / show Returns pragmatic option values for focus-events, mouse, and synchronize-panes.

Agent Teams Layout

In Agent Teams mode, Zentty treats the launching pane as the leader. The first split-window creates a team column to the right at a golden ratio. Later subagent panes stack vertically inside that team column, and select-layout main-vertical rebalances the stack without letting tmux's exact width hints fight Zentty's layout model.

wait-for is handled locally through temporary signal files, so synchronization commands do not require a running tmux server. The default timeout is 30 seconds, and --timeout overrides it.

Tracing

Set ZENTTY_TMUX_COMPAT_TRACE_PATH to a writable file path to collect JSONL trace records from both the shim and IPC handler. The trace records include event name, subcommand, arguments, worklane id, pane id, and selected result metadata. 

{"event":"tmux.command","subcommand":"split-window","args":["-h"],"paneId":"pane_...","worklaneId":"lane_...","result":"created-pane"}

Per-Session Control

Agent Teams is configured globally with [agent_teams].enabled. For one-off debugging, launch the agent in a normal pane with the real tmux earlier on PATH, or launch from a clean shell after disabling the setting and reloading configuration.

Coexistence With Real tmux

The shim is placed on PATH only for sessions Zentty owns. It does not uninstall or modify your real tmux. Use which tmux inside the agent pane to confirm whether the Zentty shim or your system tmux will handle a command.

The compatibility target is pragmatic tmux 3.x-style client behavior for pane orchestration, not a full tmux server.

Troubleshooting

tmux command not foundConfirm Agent Teams is enabled and the agent was launched from a fresh Zentty pane.
Wrong tmux is activeRun which tmux. If it points to Homebrew, your PATH order bypassed the shim.
Team column never appearsCheck trace output and confirm the tool actually called a supported split command.
wait-for hangsUse --timeout and inspect the scoped signal path in the trace.
Trace file never writesMake sure ZENTTY_TMUX_COMPAT_TRACE_PATH points to a writable file, not a directory.
Tool needs unsupported tmux featuresRun real tmux inside Zentty for that workflow.

Limits

Compatibility is intentionally pragmatic. It supports the tmux calls needed by agent workflows and pane control, not the full tmux feature surface. If a tool depends on deep tmux session management, run real tmux inside a Zentty pane instead.

  • No tmux attach/detach server lifecycle.
  • No full session/window model beyond Zentty windows and worklanes.
  • No tmux plugin manager or status-line configuration.
  • No nested server emulation.
  • No guarantee that arbitrary tmux format strings map exactly.