attyx

Attyx Terminal IPC Skill

You are running inside Attyx, a terminal emulator with a full IPC interface. You can control it programmatically.

Identifying Panes — Stable IPC IDs

Every pane has a stable numeric ID that never changes once assigned, even when other panes are closed. IDs are monotonically increasing integers (1, 2, 3, ...).

How to find your own pane

Run attyx list splits — the pane marked with * is the active/focused pane (the one you're running in):

1	bash	*	80x24    ← this is YOU (pane 1)
3	python		40x24    ← another pane (pane 3)

Or attyx list for the full tree with tab context:

1	bash	*
  1	bash	*	80x24    ← YOU (pane 1)
  3	python		40x24    ← another pane (pane 3)
2	vim
  2	vim		80x24

Tracking newly created panes

When you create a tab or split, the command returns the new pane's ID:

id=$(attyx tab create)              # returns e.g. "4"
id=$(attyx tab create --cmd htop)   # returns e.g. "5"
id=$(attyx split v)                 # returns e.g. "6"
id=$(attyx split v --cmd python3)   # returns e.g. "7"

Always capture this output so you can target the pane later without guessing:

attyx send-keys -p "$id" "print('hello'){Enter}"
attyx get-text -p "$id"

Waiting for Commands (--wait)

tab create and split support --wait to block until the spawned command exits (requires --cmd):

attyx tab create --cmd "make test" --wait    # blocks, returns exit code + stdout
attyx split v --cmd "cargo build" --wait     # same for splits

The response is the process exit code (first byte) followed by captured stdout. Useful for scripting:

attyx run "make test" --wait && echo "Tests passed"

Don't confuse titles with identity

Multiple panes can have the same title (e.g. two bash panes). Never rely on title matching to find a specific pane. Always use IDs from attyx list or captured from creation.

Session Management

Sessions are independent workspaces, each with their own tabs and panes. They persist across window reconnects.

Creating Sessions

# Create and switch to a new session
attyx session create

# Create with a working directory (name derived from path: "myapp")
attyx session create ~/Projects/myapp

# Create with explicit name
attyx session create ~/Projects/myapp "dev server"

# Create in background (don't switch)
attyx session create ~/Projects/myapp -b "build"

# Capture the session ID
sid=$(attyx session create ~/Projects/myapp -b)

Session-Targeted Commands

Use -s/--session <id> to route any command to a specific session:

attyx -s 123 tab create                # create tab in session 123
attyx -s 123 send-keys "hello" -p 2    # send to pane 2 in session 123
attyx -s 123 get-text -p 5             # read from pane 5 in session 123
attyx -s 123 list                      # list tabs/panes in session 123

When -s is omitted, commands target the currently attached session.

Other Session Commands

attyx session list                     # list all sessions
attyx session switch 2                 # switch to session 2
attyx session rename "dev server"      # rename current session
attyx session rename 1 "dev server"    # rename session 1
attyx session kill 3                   # kill session 3

Critical Rules

Always Pin Your Session

The user can switch sessions at any time. If you send commands without -s, they'll hit whatever session is currently focused — which may not be yours.

At the start of every interaction, discover your session and pane IDs and use them for all subsequent commands:

# Step 1: Find your session and pane from the full tree
attyx list
# Output:
# Session 1 "myapp" *          ← your session (marked *)
#   1	bash	*	80x24        ← your pane (marked *)
#   3	python		40x24
# Session 2 "server"
#   4	bash	*	80x24

# Step 2: Use -s <session_id> on EVERY command from now on
attyx -s 1 split v --cmd htop
attyx -s 1 send-keys -p 3 "print('hi'){Enter}"
attyx -s 1 get-text -p 3
attyx -s 1 tab create

Never omit -s after the initial discovery. Even if you think you're still in the same session, always be explicit — the user may have switched focus between your commands.

Don't Close Yourself

Before closing a pane, use targeted close with --pane / -p:

attyx split close -p 3              # close pane 3
attyx tab close 2                   # close entire tab 2

This closes the specified pane/tab without changing focus. Plain attyx split close (no target) closes the focused pane — which is YOU.

Named Keys — Use {Enter}, Not \n

send-keys supports {KeyName} syntax (case-insensitive) for all special keys:

# Press Enter to submit a command
attyx send-keys "ls -la{Enter}"

# Arrow keys for navigation
attyx send-keys "{Down}{Down}{Enter}"    # navigate a menu
attyx send-keys "{Up}{Enter}"            # rerun last command

# Ctrl combos
attyx send-keys "{Ctrl-c}"              # interrupt
attyx send-keys "{Ctrl-d}"              # EOF
attyx send-keys "{Ctrl-z}"              # suspend

# Tab completion, Escape, function keys
attyx send-keys "{Tab}{Tab}"            # show completions
attyx send-keys "{Escape}:wq{Enter}"    # vim: save and quit
attyx send-keys "{F1}"                  # help in many TUIs

Full key reference:

Modifier combos — prefixes are combinable (Ctrl-, Shift-, Alt-, Super-):

C-style escapes (\r, \t, \xHH, \e) also work but named keys are preferred for clarity.

Navigating TUI Applications

When interacting with interactive programs (menus, prompts, fzf, editors, etc.):

1. Read the screen first — use attyx get-text -p <id> to see what's displayed
2. Navigate with arrow keys — {Up}, {Down} to move through lists/menus
3. Select with Enter — {Enter} to confirm a selection
4. Type to filter — many TUIs support typing to search/filter
5. Use Tab for completion — {Tab} cycles through options in shells and some TUIs
6. Cancel/back with Escape — {Escape} to dismiss dialogs or go back
7. Read again after each action — always get-text to verify the result

Example: navigating a numbered list and selecting item 3:

attyx send-keys -p "$id" "3{Enter}"

Example: scrolling down in a TUI and selecting:

attyx send-keys -p "$id" "{Down}{Down}{Down}{Enter}"
output=$(attyx get-text -p "$id")

Example: searching in fzf-style interface:

attyx send-keys -p "$id" "search query"
sleep 0.5  # let filter update
attyx send-keys -p "$id" "{Enter}"

Example: vim/editor interaction:

attyx send-keys -p "$id" "ihello world{Escape}:wq{Enter}"

Reading Scrollback History — --lines / -n

By default get-text returns only the visible screen. To capture more (like tail -N over the pane's scrollback + screen), pass --lines N / -n N:

attyx get-text -n 100              # last 100 rows from focused pane
attyx get-text -p 3 -n 500         # last 500 rows from pane 3
attyx -s 1 get-text -p 5 -n 1000   # last 1000 rows from pane 5 in session 1

The count is clamped to the pane's available scrollback depth. Use this when a long-running command's output has scrolled off-screen, or when you need to inspect history beyond the current viewport.

Incremental Capture — --since <cursor>

When babysitting a long-running pane (a build, a test loop, another agent), don't re-read the whole screen every poll. --since returns only the rows produced since your last read, so a quiet pane returns nothing. Each read prints the next cursor (an opaque token) to stderr; pass it back next time. An empty/omitted token (--since "") seeds: it returns the current screen and a starting cursor.

# Seed a cursor (printed to stderr as "cursor: g<gen>.l<line>").
attyx get-text -p 3 --since "" 2>cur; cur=$(cut -d' ' -f2 <cur)
# Later: only the new rows since last time. Advance the cursor each read.
new=$(attyx get-text -p 3 --since "$cur" 2>c2); cur=$(cut -d' ' -f2 <c2)

The cleaner path for agents is --json, which returns everything in one object:

{ "cursor": "g3.l10581", "text": "  CC parser.o\n", "truncated": false, "reset": false, "rows": 1 }

Feed cursor back as the next --since. truncated: true means output scrolled past the retained scrollback between reads (read more often, or raise --scrollback-lines). reset: true means the layout changed (resize, clear, or alt-screen) and text is a fresh baseline, not a delta. Semantics are append-only (new scrolled output) — for a full-screen TUI that redraws in place, use plain get-text instead. Cursors are per-pane; don't reuse one across panes.

Reading Output — Use --wait-stable

Instead of blind sleep N && attyx get-text, use --wait-stable to send keys and automatically wait for output to settle:

# Send a command and wait for output to stabilize (default: 300ms stable window)
attyx send-keys --wait-stable "ls -la{Enter}"

# Custom stability window (500ms) for slower commands
attyx send-keys --wait-stable 500 "make build{Enter}"

# With pane targeting
attyx send-keys -p 3 --wait-stable "cargo test{Enter}"

--wait-stable [ms] sends the keys, then polls get-text every 50ms until screen content is unchanged for ms milliseconds (default 300). The final screen content is printed to stdout. Hard timeout at 30s.

For quick commands where you don't need the output, plain send-keys without --wait-stable is fine. Use --wait-stable when you need to read the result.

Pane Targeting (Preferred)

Almost all commands support --pane (-p) to target any pane by its stable ID:

# IO
attyx send-keys -p 3 "ls -la{Enter}"  # send to pane 3
attyx get-text -p 3                   # read visible screen from pane 3
attyx get-text -p 3 -n 200            # last 200 rows (scrollback + screen)

# Split management
attyx split close -p 5               # close pane 5
attyx split zoom -p 5                # toggle zoom on pane 5
attyx split rotate -p 3              # rotate splits in pane 3's tab

# Tab management (positional tab number)
attyx tab close 3                     # close tab 3
attyx tab rename 2 "build logs"       # rename tab 2

Pane IDs are flat integers shown in attyx list output. This avoids focus juggling and is the recommended approach.

Focus Management (Legacy)

Without --pane, send-keys and get-text operate on the focused pane:

1. attyx focus <direction> to switch to it
2. Do your send-keys / get-text
3. Focus back if needed

Tracking Agents — Status & Watching

Attyx tracks the run state of AI agents (Claude Code, Codex, etc.) running inside panes. An agent reports one of four states:

Listing active agents — list agents

attyx list agents lists every pane currently running an agent (any state except none). Use --json for a machine-readable array:

attyx list agents
# PANE  SESSION  STATE    MODEL          IN     OUT    CTX        COST    MESSAGE
# 3     1        working  opus-4.8       1.2M   320K   82K/200K   $0.42   Editing parser.zig
# 8     1        input    opus-4.8       -      -      -          -       Approve running tests?

attyx list agents --json
# [{"pane_id":3,"tab_id":3,"session":1,"pid":48213,"state":"working","message":"Editing parser.zig",
#   "usage":{"input_tokens":7199162,"output_tokens":320836,"context_used":82000,"context_max":200000,
#            "cost_usd":0.4213,"cost_is_estimate":false,"model":"claude-opus-4-8"}},
#  {"pane_id":8,"tab_id":7,"session":1,"pid":48455,"state":"input","message":"Approve running tests?","usage":{}}]

Fields: pane_id (stable ID of the agent's pane — use for targeting), tab_id (stable ID of the agent's tab; in attyx a tab is identified by its focused pane's id — the same pane:N shown by attyx list — so for a single-pane tab tab_id == pane_id), session, pid (the agent's foreground process id; 0 when unknown, e.g. daemon-backed panes), state, message (the agent's latest status preview, may be empty), and usage (token/cost/context telemetry — see below). Default scope is the attached/local session.

usage object. Present on every record (possibly {} before the agent reports anything). Only known fields appear — an absent field means unknown, never zero, so don't treat a missing cost_usd as free. Fields: input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens (cumulative for the session), context_used / context_max (current context window), cost_usd, cost_is_estimate (true when attyx computed cost from a built-in price table because the agent didn't report one — Codex), and model. Coverage varies by agent (Claude/opencode/Pi report cost directly; Codex is estimated; Codex pre-Sep-2025 builds and some gaps report no usage at all). Without --json, list agents (and watch agents) print an aligned, human-readable table — columns PANE SESSION STATE MODEL IN OUT CTX COST MESSAGE, tokens humanized (1.2M), context as used/max, - for unknowns, with a colored ● status dot at a terminal. Color is automatic (plain when piped, so | grep stays clean); force with --color, disable with --no-color. Parse --json, not the table — the table is for humans and its layout/color may change.

A live table of the same data is available two ways: the in-window overlay (Cmd/Ctrl+Shift+A, or the agent_dashboard command — current window only), and the full-screen attyx dashboard CLI, which shows agents across all sessions and lets you jump to any of them. For a scriptable cross-session snapshot, attyx dashboard --once prints a plain-text table and exits. Add -s <id> to list agents to query any session's agents directly from the daemon — it works even when no window is attached to that session:

attyx -s 2 list agents             # agents in session 2
attyx -s 2 list agents --json

For per-session counts across all daemon sessions, use attyx list sessions.

Watching for changes — watch agents

attyx watch agents opens a long-lived stream: the live counterpart of list agents, emitting the same data as it changes. On connect it emits the current agents as a snapshot, then one update per change. It blocks until interrupted. Default output is the human table (like list agents); use --json for one NDJSON record per change — same shape as list agents --json, including the usage object — for scripting:

# Human: live table, run it in a split/popup to keep an eye on the swarm
attyx watch agents

# Scripts: parse NDJSON (one record per change)
attyx watch agents --json | while read -r line; do
  echo "$line" | grep -q '"state":"input"' && notify-send "Agent needs input"
done
# {"pane_id":3,"tab_id":3,"session":1,"pid":48213,"state":"input","message":"Needs your input","usage":{...}}

Unlike list agents, the watch stream includes transitions to state:"none" so you can tell when an agent's session ends. Use watch agents instead of polling list agents in a loop — it's push-based and won't miss fast transitions.

Like list agents, the stream defaults to the attached/local session. Add -s <id> to watch a specific session straight from the daemon, regardless of which session a window is showing (or whether any window is attached):

attyx -s 2 watch agents            # stream session 2's agents

Watching a single agent — --pane / -p

To follow just one agent instead of all of them, pass its stable pane ID with -p. The snapshot and the live stream are both filtered to that pane:

attyx watch agents -p 3             # only pane 3's agent
# {"pane_id":3,"tab_id":3,"session":1,"pid":48213,"state":"working","message":"..."}
# {"pane_id":3,"tab_id":3,"session":1,"pid":48213,"state":"idle","message":""}

# Block until a specific agent finishes its current turn — use `agent await`
# (the formalized version of the hand-rolled `watch … | while read` loop):
attyx agent await -p 3 --state idle

The pane ID is the pane_id from attyx list agents (or the ID returned when you created the pane). 0/omitted means all agents.

Checking a single agent

To check one pane's agent without streaming, pass its stable pane ID:

attyx list agents -p 3              # just pane 3's agent (one line, or empty if none)
attyx list agents -p 3 --json      # same, as a JSON array

Driving another agent — agent send / agent await

To send a prompt to an agent in another pane and block until its turn finishes, use agent send --wait instead of hand-rolling send-keys + a watch loop + get-text. It pastes the prompt (multi-line safe), presses Enter, waits for the turn, and reports the outcome.

# Send a prompt and wait; exit code encodes the outcome.
attyx agent send -p 3 "run the tests and fix any failures" --wait

# Capture just the turn's output (uses get-text --since) as JSON:
attyx agent send -p 3 "summarize src/api" --wait --capture --json
# {"pane":3,"session":1,"outcome":"done","duration_ms":48213,"message":"…",
#  "output":"…only the rows this turn produced…","truncated":false}

# Just wait (send nothing) until an agent is done or needs you:
attyx agent await -p 3 --state any

# Read an agent's last message from its transcript (not the screen):
attyx agent read -p 3                  # the last message
attyx agent read -p 3 --offset 1       # the one before it

agent read returns an agent's message straight from its transcript file (structural, not a screen scrape) — use it to collect another agent's actual output instead of get-text. --offset n/-o n gives the n-th message back (0 = last). Works with -s <session> too. Only agents that report a transcript (Claude Code, Codex) are supported; others return a clear error. Over MCP it's the agent_read tool.

Outcomes (and exit codes): done (0) · needs_input (2) · timeout (3) · no_turn/ended (4). So attyx agent send -p 3 "build" --wait && attyx agent send -p 5 "deploy" --wait chains turns only on success. Add --tokens for the per-turn token/cost delta. Outcomes are honest: no_turn means the agent never started (wrong pane / it didn't accept the input), timeout means it's still working (the agent is never interrupted — we just stop waiting). Over MCP this is the agent_send tool. (Currently targets the attached session; -s background sessions are a follow-up.) -p/--pane works on both list agents and watch agents; omit it for all agents.

Argument Handling

If the user provides arguments, interpret them as a natural language instruction. Remember to always use -s <session_id> (discovered via attyx list at start):

• /attyx open a split with htop → attyx -s <sid> split v --cmd htop
• /attyx send "hello" to the other pane → attyx -s <sid> send-keys -p <id> "hello{Enter}"
• /attyx close the other pane → attyx -s <sid> split close -p <id>
• /attyx what's on screen in the right pane → attyx -s <sid> get-text -p <id>
• /attyx create a background session for ~/Projects/api → attyx session create ~/Projects/api -b
• /attyx list sessions → attyx session list
• /attyx create a tab in session 5 → attyx -s 5 tab create
• /attyx which agents are running → attyx list agents
• /attyx tell me when an agent needs input → attyx watch agents (filter for "state":"input")
• /attyx watch the agent in pane 3 → attyx watch agents -p 3

If no arguments, ask the user what they'd like to do with the terminal.