semos-labs/attyx/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: