tmux

v0.1.1

tmux as an iii worker — list, create, rename and kill sessions and windows, see which pane runs Claude Code or Codex (working, waiting for you, idle), which runs `iii compose` and every listening port by process and pane, plus a Console page whose terminal is a live tmux client.

license: Apache-2.0Published 5d agoagents console multiplexer ports sessions terminal tmux

Install

bash

iii trigger compose::add worker=tmux

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions22

tmux::configuration-id

Function

Returns this worker instance's effective configuration entry ID, without its value.

Request

Empty object

Response

idstringrequired

tmux::on-config-change

Function

Internal: re-read the tmux configuration after an operator change.

Request

idstring
Configuration id that changed.

Response

okbooleanrequired

tmux::panes::capture

Function

The visible screen of one pane as text with its colour and style escapes (capture-pane -e), plus the pane's size, cursor position and whether a full-screen program has the alternate screen. Read-only.

Request

panestringrequired
Pane id, e.g. `%5`.

Response

alternatebooleanrequired
The pane shows its alternate screen (a full-screen program).
cursor_xinteger· uint32requiredmin 0
Cursor column, from 0.
cursor_yinteger· uint32requiredmin 0
Cursor row, from 0.
heightinteger· uint32requiredmin 0
Height in rows.
pane_idstringrequired
Pane id.
textstringrequired
The visible screen, one line per row separated by `\n`, with SGR escapes.
widthinteger· uint32requiredmin 0
Width in columns.

tmux::panes::select

Function

Make a pane the active pane of its window, optionally zooming the window on it (zoom: true, like tmux's prefix z) or unzooming it (zoom: false); without zoom the window keeps its zoom state. Like tmux itself, every client looking at that window follows, your terminal included. It does not change the session's current window (tmux::windows::select does).

Request

panestringrequired
Pane id, e.g. `%5`.
zoomboolean
true zooms the window on this pane, false unzooms it, absent keeps the window's zoom.

Response

pane_idstringrequired
Pane id now active in its window.
session_idstringrequired
Session id the pane was resolved in.
window_idstringrequired
Window id holding the pane.
zoomedbooleanrequired
The window is zoomed on the active pane.

tmux::ports::list

Function

Every TCP port this user's processes listen on, with process, iii role (engine / worker / compose), worker name, compose namespace and the tmux pane the process runs in; plus each running `iii compose` stack with its engine WebSocket port and workers' ports.

Request

Empty object

Response

composesobject[]required
Running `iii compose` daemons.
- compose_filestring
  Compose file the daemon serves, when known.
- engineany of
  The engine the daemon started, if it manages one.
  any of (2)
  Variant 1
  pidinteger· uint32requiredmin 0
  Engine pid.
  portsinteger[]· uint16requiredmin 0
  Ports the engine listens on.
  ws_portinteger· uint16min 0
  The engine WebSocket port workers connect to.
  Variant 2
  valuenull
- locationany of
  tmux pane the daemon runs in.
  any of (2)
  Variant 1
  pane_idstringrequired
  Pane id.
  sessionstringrequired
  Session name.
  session_idstringrequired
  Session id.
  window_idstringrequired
  Window id.
  window_indexinteger· uint32requiredmin 0
  Window index.
  Variant 2
  valuenull
- namespacestringrequired
  Daemon namespace (`iii:c:<namespace>`).
- pidinteger· uint32requiredmin 0
  Daemon pid.
- project_dirstring
  Daemon working directory.
- workersobject[]required
  Workers the daemon started.
  namestringrequired
  Worker name.
  pidinteger· uint32requiredmin 0
  Top-most pid of the worker's process tree.
  portsinteger[]· uint16requiredmin 0
  Ports the worker's processes listen on.
errorstring
Why the scan failed, if it did.
generated_at_msinteger· uint64requiredmin 0
When the snapshot was taken.
listenersobject[]required
Every TCP listening socket of this user's processes, sorted by port.
- addressstringrequired
  Bound address, e.g. `0.0.0.0` or `::1`.
- composestring
  Compose namespace the process belongs to.
- familyall ofrequired
  IPv4 or IPv6.
  all of (1)
  Variant 1
  valuestringenum ipv4, ipv6
- locationany of
  tmux pane the process descends from.
  any of (2)
  Variant 1
  pane_idstringrequired
  Pane id.
  sessionstringrequired
  Session name.
  session_idstringrequired
  Session id.
  window_idstringrequired
  Window id.
  window_indexinteger· uint32requiredmin 0
  Window index.
  Variant 2
  valuenull
- pidinteger· uint32requiredmin 0
  Owning process.
- portinteger· uint16requiredmin 0
  Port number.
- processstringrequired
  Owning process name.
- roleall ofrequired
  What kind of process owns the socket.
  all of (1)
  Variant 1
  one of (4)
  Variant 1
  valuestringenum engine
  Variant 2
  valuestringenum worker
  Variant 3
  valuestringenum compose
  Variant 4
  valuestringenum other
- workerstring
  iii worker name, when known.
supportedbooleanrequired
This platform has a port scanner.

tmux::sessions::create

Function

Create a detached tmux session (starting the tmux server if needed). Optional name, working directory (default $HOME), first window name and a shell command to run instead of the default shell.

Request

commandstring
Shell command to run in the first window instead of the default shell.
cwdstring
Working directory, absolute or `~/…`. Defaults to $HOME.
namestring
Session name; tmux picks a number when omitted. No `:` or `.`.
window_namestring
Name of the first window.

Response

pane_idstringrequired
First pane id.
sessionstringrequired
Session name.
session_idstringrequired
New session id, e.g. `$7`.
window_idstringrequired
First window id.
window_indexinteger· uint32requiredmin 0
First window index.

tmux::sessions::kill

Function

Kill a tmux session and every program running in its windows.

Request

sessionstringrequired
Session id (`$5`) or exact name.

Response

killedbooleanrequired
Always true.

tmux::sessions::list

Function

Every tmux session with its windows and panes: foreground command, cwd, title, size, the agent CLI running in the pane (claude, codex, … with state working / waiting / idle), the `iii compose` daemon it runs and the ports its processes listen on.

Request

Empty object

Response

generated_at_msinteger· uint64requiredmin 0
When the snapshot was taken.
sessionsobject[]required
Sessions sorted by name.
- activity_at_msinteger· uint64requiredmin 0
  Last activity in any of its windows.
- attachedinteger· uint32requiredmin 0
  tmux clients attached, console terminals included.
- console_attachedinteger· uint32requiredmin 0
  How many attached clients are console terminals.
- created_at_msinteger· uint64requiredmin 0
  When the session was created.
- idstringrequired
  Session id, e.g. `$5`.
- namestringrequired
  Session name.
- windowsobject[]required
  Windows sorted by index.
  activebooleanrequired
  This is the session's current window.
  activity_at_msinteger· uint64requiredmin 0
  Last output in the window.
  bellbooleanrequired
  A bell rang in the window.
  idstringrequired
  Window id, e.g. `@3` (unique on the server).
  indexinteger· uint32requiredmin 0
  Window index inside the session.
  namestringrequired
  Window name.
  panesobject[]required
  Panes sorted by index.
  Show 13 nestedHide nested
  activebooleanrequired
  The window's active pane.
  agentany of
  The agent CLI running in this pane, if any.
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  idstringrequired
  Matcher id from the configuration, e.g. `claude`.
  labelstringrequired
  Display name, e.g. `Claude Code`.
  pidinteger· uint32requiredmin 0
  Pid of the agent process.
  since_msinteger· uint64requiredmin 0
  When the agent entered `state`.
  stateall ofrequired
  What the agent is doing.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  one of (3)
  Variant 1
  valuestringenum working
  Variant 2
  valuestringenum waiting
  Variant 3
  valuestringenum idle
  titlestring
  The agent's session title: the pane title without the agent's status glyph (Claude Code's ✳ or spinner). Null when the pane only shows tmux's default title (the host name) or nothing.
  Variant 2
  valuenull
  commandstringrequired
  Foreground process name.
  composeany of
  The `iii compose` daemon running in this pane, if any.
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  namespacestringrequired
  Compose daemon namespace.
  pidinteger· uint32requiredmin 0
  Compose daemon pid.
  Variant 2
  valuenull
  cwdstringrequired
  Current directory.
  deadbooleanrequired
  The pane's process exited and the pane is kept.
  heightinteger· uint32requiredmin 0
  Height in rows.
  idstringrequired
  Pane id, e.g. `%5`.
  indexinteger· uint32requiredmin 0
  Pane index inside the window.
  pidinteger· uint32requiredmin 0
  Pid of the process tmux started in the pane.
  portsobject[]required
  Listening sockets owned by processes started from this pane.
  Show 9 nestedHide nested
  addressstringrequired
  Bound address, e.g. `0.0.0.0` or `::1`.
  composestring
  Compose namespace the process belongs to.
  familyall ofrequired
  IPv4 or IPv6.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  valuestringenum ipv4, ipv6
  locationany of
  tmux pane the process descends from.
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  pane_idstringrequired
  Pane id.
  sessionstringrequired
  Session name.
  session_idstringrequired
  Session id.
  window_idstringrequired
  Window id.
  window_indexinteger· uint32requiredmin 0
  Window index.
  Variant 2
  valuenull
  pidinteger· uint32requiredmin 0
  Owning process.
  portinteger· uint16requiredmin 0
  Port number.
  processstringrequired
  Owning process name.
  roleall ofrequired
  What kind of process owns the socket.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  one of (4)
  Variant 1
  valuestringenum engine
  Variant 2
  valuestringenum worker
  Variant 3
  valuestringenum compose
  Variant 4
  valuestringenum other
  workerstring
  iii worker name, when known.
  titlestringrequired
  Pane title set by the program.
  widthinteger· uint32requiredmin 0
  Width in columns.
  zoomedbooleanrequired
  A pane is zoomed.
tmuxall ofrequired
tmux availability and server.
all of (1)
Variant 1
availablebooleanrequired
A usable tmux binary was found.
errorstring
Why tmux is unavailable, or the last listing error.
pathstring
Resolved tmux binary.
server_runningbooleanrequired
A tmux server is running on that socket.
socket_pathstring
Server socket, known while the server runs.
versionstring
tmux version, e.g. `3.6`.

tmux::sessions::rename

Function

Rename a tmux session.

Request

namestringrequired
New name. No `:` or `.`.
sessionstringrequired
Session id (`$5`) or exact name.

Response

namestringrequired
New name.
session_idstringrequired
Session id.

tmux::status

Function

Whether tmux is installed, its version and path, and whether a tmux server is running on the configured socket.

Request

Empty object

Response

availablebooleanrequired
A usable tmux binary was found.
errorstring
Why tmux is unavailable, or the last listing error.
pathstring
Resolved tmux binary.
server_runningbooleanrequired
A tmux server is running on that socket.
socket_pathstring
Server socket, known while the server runs.
versionstring
tmux version, e.g. `3.6`.

tmux::terminal::close

Function

Detach a console terminal's tmux client. The session keeps running.

Request

access_keystringrequired
Credential from `open`.
terminal_idstringrequired
Terminal handle from `open`.

Response

closedbooleanrequired
False when the terminal was already gone.

tmux::terminal::open

Function

Attach a console terminal to a tmux session as a real tmux client running in a PTY. Output is pushed to the page's handler.

Request

colsinteger· uint16requiredmin 0
Terminal width in columns (2..=500).
output_function_idstringrequired
Browser handler receiving output: `iii::tmux-ui::pty-output::console-<browser id>`.
rowsinteger· uint16requiredmin 0
Terminal height in rows (2..=500).
sessionstringrequired
Session id (`$5`) or exact name to attach to.
windowany of
Window id (`@3`) or index to select before attaching.
any of (2)
Variant 1
any of (2)
Variant 1
valueinteger· uint32min 0
Variant 2
valuestring
Variant 2
valuenull

Response

access_keystringrequired
Short-lived credential required by every other call. Never persist it.
client_ttystring
The tmux client's tty, as `list-clients` shows it.
session_idstringrequired
Session the client attached to.
terminal_idstringrequired
Terminal handle for the other calls.

tmux::terminal::redraw

Function

Ask tmux to repaint the console terminal's whole screen (refresh-client).

Request

access_keystringrequired
Credential from `open`.
terminal_idstringrequired
Terminal handle from `open`.

Response

okbooleanrequired
Always true.

tmux::terminal::replay

Function

Re-send buffered output frames after a sequence, for gap repair.

Request

access_keystringrequired
Credential from `open`.
after_sequenceinteger· uint64requiredmin 0
Last sequence the page applied; frames after it are returned.
terminal_idstringrequired
Terminal handle from `open`.

Response

framesobject[]required
- datastringrequired
- sequenceinteger· uint64requiredmin 0
next_sequenceinteger· uint64requiredmin 0
truncatedbooleanrequired

tmux::terminal::resize

Function

Resize a console terminal; also its heartbeat.

Request

access_keystringrequired
Credential from `open`.
colsinteger· uint16requiredmin 0
Width in columns (2..=500).
rowsinteger· uint16requiredmin 0
Height in rows (2..=500).
terminal_idstringrequired
Terminal handle from `open`.

Response

colsinteger· uint16requiredmin 0
Width applied.
rowsinteger· uint16requiredmin 0
Height applied.

tmux::terminal::switch

Function

Move only this console terminal's tmux client to another session (switch-client), optionally selecting a window there.

Request

access_keystringrequired
Credential from `open`.
sessionstringrequired
Session id (`$5`) or exact name to move this client to.
terminal_idstringrequired
Terminal handle from `open`.
windowany of
Window id (`@3`) or index to select there.
any of (2)
Variant 1
any of (2)
Variant 1
valueinteger· uint32min 0
Variant 2
valuestring
Variant 2
valuenull

Response

session_idstringrequired
Session the client now shows.

tmux::terminal::write

Function

Write base64 keyboard input to a console terminal's tmux client.

Request

access_keystringrequired
Credential from `open`.
datastringrequired
Base64 keyboard input, at most 64 KiB decoded.
terminal_idstringrequired
Terminal handle from `open`.

Response

writteninteger· uintrequiredmin 0
Bytes written to the tmux client.

tmux::ui-content

Function

Serve the tmux worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request

pathstringrequired
The asset path from the trigger config (e.g. `state/page.js`).

Response

contentstringrequired
The asset source, verbatim.
content_typestringrequired
MIME type the console should serve the asset with.

tmux::windows::create

Function

Create a window in a tmux session. Optional name, working directory (default: the directory the session was created in), a shell command to run instead of the default shell, and whether to make it the current window (default true).

Request

commandstring
Shell command to run instead of the default shell.
cwdstring
Working directory, absolute or `~/…`. Defaults to the directory the session was created in.
namestring
Window name. No `:` or `.`.
selectboolean
Make it the session's current window (default true).
sessionstringrequired
Session id (`$5`) or exact name.

Response

pane_idstringrequired
Its first pane id.
session_idstringrequired
Session id.
window_idstringrequired
New window id, e.g. `@9`.
window_indexinteger· uint32requiredmin 0
New window index.

tmux::windows::kill

Function

Kill a tmux window and every program running in its panes.

Request

sessionstringrequired
Session id (`$5`) or exact name.
windowall ofrequired
Window id (`@3`) or index.
all of (1)
Variant 1
any of (2)
Variant 1
valueinteger· uint32min 0
Variant 2
valuestring

Response

killedbooleanrequired
Always true.

tmux::windows::rename

Function

Rename a tmux window.

Request

namestringrequired
New name. No `:` or `.`.
sessionstringrequired
Session id (`$5`) or exact name.
windowall ofrequired
Window id (`@3`) or index.
all of (1)
Variant 1
any of (2)
Variant 1
valueinteger· uint32min 0
Variant 2
valuestring

Response

namestringrequired
New name.
window_idstringrequired
Window id.

tmux::windows::select

Function

Make a window the current window of its session. Like tmux itself, every client attached to that session (your terminal included) switches to it.

Request

sessionstringrequired
Session id (`$5`) or exact name.
windowall ofrequired
Window id (`@3`) or index.
all of (1)
Variant 1
any of (2)
Variant 1
valueinteger· uint32min 0
Variant 2
valuestring

Response

session_idstringrequired
Session id.
window_idstringrequired
Window id now current.

Triggers1

tmux::changed

Trigger

Live tmux overview: fires the full state (sessions, windows, panes with agent/compose/port status, compose stacks and listening ports) when bound and again whenever it changes. Config takes no options.

Invocation

Empty object

Return

portsall ofrequired
Listening ports and compose stacks.
all of (1)
Variant 1
composesobject[]required
Running `iii compose` daemons.
Show 7 nestedHide nested
compose_filestring
Compose file the daemon serves, when known.
engineany of
The engine the daemon started, if it manages one.
Show 2 nestedHide nested
any of (2)
Variant 1
pidinteger· uint32requiredmin 0
Engine pid.
portsinteger[]· uint16requiredmin 0
Ports the engine listens on.
ws_portinteger· uint16min 0
The engine WebSocket port workers connect to.
Variant 2
valuenull
locationany of
tmux pane the daemon runs in.
Show 2 nestedHide nested
any of (2)
Variant 1
pane_idstringrequired
Pane id.
sessionstringrequired
Session name.
session_idstringrequired
Session id.
window_idstringrequired
Window id.
window_indexinteger· uint32requiredmin 0
Window index.
Variant 2
valuenull
namespacestringrequired
Daemon namespace (`iii:c:<namespace>`).
pidinteger· uint32requiredmin 0
Daemon pid.
project_dirstring
Daemon working directory.
workersobject[]required
Workers the daemon started.
Show 3 nestedHide nested
namestringrequired
Worker name.
pidinteger· uint32requiredmin 0
Top-most pid of the worker's process tree.
portsinteger[]· uint16requiredmin 0
Ports the worker's processes listen on.
errorstring
Why the scan failed, if it did.
generated_at_msinteger· uint64requiredmin 0
When the snapshot was taken.
listenersobject[]required
Every TCP listening socket of this user's processes, sorted by port.
Show 9 nestedHide nested
addressstringrequired
Bound address, e.g. `0.0.0.0` or `::1`.
composestring
Compose namespace the process belongs to.
familyall ofrequired
IPv4 or IPv6.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum ipv4, ipv6
locationany of
tmux pane the process descends from.
Show 2 nestedHide nested
any of (2)
Variant 1
pane_idstringrequired
Pane id.
sessionstringrequired
Session name.
session_idstringrequired
Session id.
window_idstringrequired
Window id.
window_indexinteger· uint32requiredmin 0
Window index.
Variant 2
valuenull
pidinteger· uint32requiredmin 0
Owning process.
portinteger· uint16requiredmin 0
Port number.
processstringrequired
Owning process name.
roleall ofrequired
What kind of process owns the socket.
Show 1 nestedHide nested
all of (1)
Variant 1
one of (4)
Variant 1
valuestringenum engine
Variant 2
valuestringenum worker
Variant 3
valuestringenum compose
Variant 4
valuestringenum other
workerstring
iii worker name, when known.
supportedbooleanrequired
This platform has a port scanner.
sessionsall ofrequired
Sessions, windows, panes and their status.
all of (1)
Variant 1
generated_at_msinteger· uint64requiredmin 0
When the snapshot was taken.
sessionsobject[]required
Sessions sorted by name.
Show 7 nestedHide nested
activity_at_msinteger· uint64requiredmin 0
Last activity in any of its windows.
attachedinteger· uint32requiredmin 0
tmux clients attached, console terminals included.
console_attachedinteger· uint32requiredmin 0
How many attached clients are console terminals.
created_at_msinteger· uint64requiredmin 0
When the session was created.
idstringrequired
Session id, e.g. `$5`.
namestringrequired
Session name.
windowsobject[]required
Windows sorted by index.
Show 8 nestedHide nested
activebooleanrequired
This is the session's current window.
activity_at_msinteger· uint64requiredmin 0
Last output in the window.
bellbooleanrequired
A bell rang in the window.
idstringrequired
Window id, e.g. `@3` (unique on the server).
indexinteger· uint32requiredmin 0
Window index inside the session.
namestringrequired
Window name.
panesobject[]required
Panes sorted by index.
Show 13 nestedHide nested
activebooleanrequired
The window's active pane.
agentany of
The agent CLI running in this pane, if any.
Show 2 nestedHide nested
any of (2)
Variant 1
idstringrequired
Matcher id from the configuration, e.g. `claude`.
labelstringrequired
Display name, e.g. `Claude Code`.
pidinteger· uint32requiredmin 0
Pid of the agent process.
since_msinteger· uint64requiredmin 0
When the agent entered `state`.
stateall ofrequired
What the agent is doing.
Show 1 nestedHide nested
all of (1)
Variant 1
one of (3)
Variant 1
valuestringenum working
Variant 2
valuestringenum waiting
Variant 3
valuestringenum idle
titlestring
The agent's session title: the pane title without the agent's status glyph (Claude Code's ✳ or spinner). Null when the pane only shows tmux's default title (the host name) or nothing.
Variant 2
valuenull
commandstringrequired
Foreground process name.
composeany of
The `iii compose` daemon running in this pane, if any.
Show 2 nestedHide nested
any of (2)
Variant 1
namespacestringrequired
Compose daemon namespace.
pidinteger· uint32requiredmin 0
Compose daemon pid.
Variant 2
valuenull
cwdstringrequired
Current directory.
deadbooleanrequired
The pane's process exited and the pane is kept.
heightinteger· uint32requiredmin 0
Height in rows.
idstringrequired
Pane id, e.g. `%5`.
indexinteger· uint32requiredmin 0
Pane index inside the window.
pidinteger· uint32requiredmin 0
Pid of the process tmux started in the pane.
portsobject[]required
Listening sockets owned by processes started from this pane.
Show 9 nestedHide nested
addressstringrequired
Bound address, e.g. `0.0.0.0` or `::1`.
composestring
Compose namespace the process belongs to.
familyall ofrequired
IPv4 or IPv6.
Show 1 nestedHide nested
all of (1)
Variant 1
valuestringenum ipv4, ipv6
locationany of
tmux pane the process descends from.
Show 2 nestedHide nested
any of (2)
Variant 1
pane_idstringrequired
Pane id.
sessionstringrequired
Session name.
session_idstringrequired
Session id.
window_idstringrequired
Window id.
window_indexinteger· uint32requiredmin 0
Window index.
Variant 2
valuenull
pidinteger· uint32requiredmin 0
Owning process.
portinteger· uint16requiredmin 0
Port number.
processstringrequired
Owning process name.
roleall ofrequired
What kind of process owns the socket.
Show 1 nestedHide nested
all of (1)
Variant 1
one of (4)
Variant 1
valuestringenum engine
Variant 2
valuestringenum worker
Variant 3
valuestringenum compose
Variant 4
valuestringenum other
workerstring
iii worker name, when known.
titlestringrequired
Pane title set by the program.
widthinteger· uint32requiredmin 0
Width in columns.
zoomedbooleanrequired
A pane is zoomed.
tmuxall ofrequired
tmux availability and server.
Show 1 nestedHide nested
all of (1)
Variant 1
availablebooleanrequired
A usable tmux binary was found.
errorstring
Why tmux is unavailable, or the last listing error.
pathstring
Resolved tmux binary.
server_runningbooleanrequired
A tmux server is running on that socket.
socket_pathstring
Server socket, known while the server runs.
versionstring
tmux version, e.g. `3.6`.

Install

Functions22

Triggers1

Search the registry