Skip to main content

brachio

A standalone TUI for coding agent status in Rex. Select an agent with the keyboard or mouse to ask one Rex app to show its session, tab, and pane.

Brachio does not send prompts, keys, or commands to agents. It is not a native sidebar and does not stay visible across tabs.

Brachio TUI

Requirements and installation

  • macOS or Linux with an interactive terminal and mouse reporting.
  • For installation, use Cargo or uv. A PyPI wheel does not require Rust. Source builds require Rust stable and Cargo.
  • The official Rex CLI, connected to the intended server. Brachio checks PATH first. On macOS, it also checks the app-managed installation described below.
  • An open Rex app. Brachio uses the session.select app action to show a session or tab. This action requires Remote Control.
    • In Rex, open Settings → Rex Server and enable Remote Control. It is off by default.
    • Enable this only if you accept remote app control. Brachio does not change it.
    • If disabled, Rex rejects app selection with Rex.app is not accepting actions. Press w in Brachio to read the full error. After enabling the permission, press Enter on the target agent to retry.

After publication, install from either registry:

cargo install brachio --locked
# Or install the native CLI from PyPI:
uv tool install brachio
# Run without a persistent installation:
uvx brachio --help

PyPI wheels target Linux (glibc 2.28 or newer) and macOS, on x86_64 and aarch64. Windows and musl wheels are not provided. Both distributions contain the same Rust CLI and use the version in Cargo.toml.

Build from source:

cargo build --release --locked
./target/release/brachio
# Optional local installation:
cargo install --path . --locked

Start and operate

You can start Brachio from Ghostty or another terminal; it does not need to run inside Rex. Keep the Rex app open.

Brachio uses the first executable rex on PATH. If none is found on macOS, it checks:

~/Library/Application Support/com.superlogical.rex/RexServer/Versions/Current/Rex Server.app/Contents/MacOS/rex

This uses Rex's current CLI without a fixed version number or changes to your shell or terminal configuration. If neither location has an executable CLI, Brachio reports an error before it changes terminal modes. On Linux, rex must be on PATH.

brachio
brachio --help
rex --autostart=false client ls --json
brachio --client 'client:<full-uuid-from-the-list>'

If rex is not on PATH, use the full CLI path above for the client-list command.

With one connected app, Brachio selects and retains its full client ID. Connection failures and an absent app are retried until the first pin. With multiple apps, use --client with a full ID; ambiguity remains refused until restart, even if an app later disconnects. Labels and suffixes are not accepted. Once pinned, a disconnected selected app prevents navigation without substitution. Restart to select a different client.

Brachio uses the CLI's normal server connection. Check rex whoami --json before starting if the server is uncertain. It does not aggregate hosts or start a missing server. Inherited REX_CLIENT does not override the selected app.

Input Operation
Up / Down or k / j Select the previous / next visible agent; collapsed headers are selectable
g / G Cycle grouping forward / backward: None → Agent → Status → CWD → Session
Tab / Shift+Tab Select the first matching agent in the next / previous group; wrap at either end
Left / Right Collapse / expand the selected group
Enter Navigate to the selected visible agent; on a collapsed group, expand only
Left click Select and navigate to an agent row; a group-header click only toggles its fold
Mouse wheel Scroll without changing the selected agent
/ Edit the filter incrementally
a / A Select the next / previous matching Blocked or Error agent; wrap and expand its group
w Open Details with diagnostics, messages, warnings, status source, and full selected-agent values
? Open keyboard help
Up / Down, PageUp / PageDown, or wheel in overlays Scroll Details or Help
q / Escape in overlays Close Details or Help first; w also closes Details and ? closes Help
q / Escape on the list q exits; Escape clears a query first, otherwise exits
Ctrl-C Quit from any view, including filter editing
Terminal resize Recalculate the layout and visible rows

The list has six independent columns: Status, Agent, Working directory (CWD), Session, Tab, and Pane. Session, Tab, and Pane use readable names, never a combined Location field or ID suffixes. Unnamed locations use display positions; generated tab names become Tab N.

Column widths use the terminal-cell width of matching agent values and headings, including agents in collapsed groups. Two spaces separate visible columns. Extra terminal width stays on the right rather than spreading columns apart. Natural widths are capped at 9, 20, 48, 24, 20, and 24 cells respectively. The selected-row highlight still spans the whole terminal width.

When space is limited, values shorten before lower-priority columns disappear. Pane, Tab, and Session are hidden in that order when their minimum widths no longer fit. Very small views use status symbols and shorter Agent/CWD values before hiding essential fields. Visibility follows measured content, not fixed terminal-width breakpoints. Hidden values remain available in Details.

Long names end with …; long directories keep the path end visible. An absolute path under HOME is displayed with ~ at a path-component boundary. Abbreviation and clipping change display only: Details retains the original full path and exact navigation IDs.

The default None view keeps the original ungrouped list and its status, location, and exact identity order. It has no grouping title or group headers. Keyboard hints appear only below the list. When space permits, a solid line appears below the column headings.

Grouped views show the mode in the title. Foldable headers with matching-agent counts appear only when at least two nonempty groups remain after filtering. With zero or one group, there are no group headers or folds. Under actual multiple headers, Status, Agent, CWD, or Session grouping hides its matching data column without leaving an empty gap. With one group, that column returns. Tab and Pane remain independent in every mode. Equal group values appear together:

  • Agent uses canonical agent names.
  • Status uses this priority: Blocked, Error, Done, Working, Idle.
  • CWD uses full reported paths, not clipped labels or repository roots.
    • All missing directories form one final Unknown group.
  • Session uses session names, with exact IDs to keep same-name sessions separate.

Agent names, paths, and session names use case-sensitive text order. Within each group, rows keep status priority, then location and exact identity order.

Press g or G to change the grouping mode without changing the selected agent. Tab and Shift+Tab keep their group-jump operation: they skip the current group and select the first matching agent in the next or previous nonempty group, not the next or previous agent. With no visible selection, they select the first or last group; with one group, they select its first agent. They do not navigate Rex, expand folds, or act in None, Details, Help, or filter editing. Grouping, folds, and filters are not saved after exit.

Left / Right folds the selected group only when multiple group headers exist. A header click toggles that group without changing the selected agent or navigating. Collapsing the selected agent's group retains its exact ID; Enter expands the group without navigation. Press Enter again to navigate to that agent.

Press / to edit a case-insensitive substring filter. Every whitespace-separated term must match (AND). Use agent:, cwd:, session:, or status: to restrict a term to that field. Unqualified terms also search tab and pane names; unknown prefixes are literal text. For example, agent:pi cwd:project status:blocked requires all three matches. Filtering updates while you type or paste. Enter applies the query without navigation; Escape cancels editing and restores the previous query. Outside editing, Escape clears a query before it can exit. Filtering retains the selected ID, but a hidden selection cannot navigate. Use arrows, a group jump, an attention jump, or a click to select a matching target.

The bounded footer shows connection state, compact agent counts, and nonzero attention (Blocked/Error) and working counts when space permits. It omits zero-warning text, UUIDs, and full diagnostics. A warning count or Notice (w) points to Details; ? shows all controls even when footer hints do not fit.

Selection uses the session ID, block ID, and canonical agent name, not a row number. If the selected entry disappears, navigation stops until you deliberately select another row with arrows, a group jump, or a click. Snapshot changes invalidate old mouse hit regions. Queued input is read before list redraws; mouse-down events that arrive during a redraw are discarded with a retry message rather than mapped to a replacement row. Terminal events do not carry a display-generation token, so this is not a guarantee about delayed physical input.

Working directory means the current directory (CWD) reported by Rex for the recognized foreground agent. It is not an inferred workspace or repository root. Missing directories, exited agents, and unrelated foreground processes show Unknown. Brachio uses the existing process query; it does not send commands to the agent or inspect local project files.

Agent and record rules

Recognized status app / effective_app values are pi, claude-code (alias claude), and codex.

  • Pi status and foreground identity were observed on the local Rex installation.
  • Claude Code and Codex mappings have fixture coverage only. Their actual status reporting depends on the agent and Rex integration; it is not native end-to-end support evidence.
  • An exact recognized foreground script basename, argv0, or executable name can identify an agent without a status report. Brachio displays an Idle fallback, with zero records and an explicit no-report source in Details. An interpreter such as node or python alone cannot.
  • Other applications and agents without an explicit recognized identity are omitted. An empty list is not proof that no agents are running.
  • Status follows the Rex schema: Blocked, Error, Done, Working, Idle. Missing or unrecognized state values use Idle; there is no Unknown status. An empty records array means no status report, not a reported Idle state. No Waiting state or need for input is inferred from Blocked. A failed status query is shown as a warning.
  • Done is a reported state, not proof of whole-session completion. Status timestamps do not establish elapsed task time.
  • Records inherit app from their nearest reported ancestor if Rex does not supply effective_app. Duplicate parent IDs are ambiguous and do not establish inheritance. Replies over the protocol limit of 256 records are rejected.
  • All records for the same recognized app in one pane become one row. The most urgent reported status wins; record order does not change the result.
    • Separate instances of the same app in one pane are intentionally not distinguished.
    • Different recognized apps in the same pane can have separate rows. Both navigate to that pane.
    • Subtasks without their own pane do not get a fictitious navigation target.
  • clear records are omitted. Retained Done/Error reports remain visible after process exit. They do not establish that a process is still running.
  • Only terminal blocks with matching, unambiguous session-view and block-list locations are navigable. Detached blocks, unknown placements, nonterminal blocks, and incomplete IDs are ignored with warnings where applicable.

Updates, navigation, and safety

A background worker obtains the initial snapshot. The CLI event stream invalidates snapshots; event bursts are coalesced. Full reconciliation also runs two seconds after each completed refresh, so missed or unknown events cannot permanently leave old state. Commands run outside the input/render loop. One dedicated navigation thread performs focus and app selection; read-only snapshot and event workers cannot change focus. A slow full-session scan does not delay navigation to a healthy target pane.

A failed server snapshot retains the old list as stale, shows a disconnected status, and disables navigation. Per-session or per-pane failures produce a partial list and warnings. Event-stream loss is shown as a warning while periodic snapshots continue; the listener reconnects. A silent recovered listener remains marked uncertain until it delivers an event.

Navigation rechecks the pinned client, action schema, pane location, and agent identity. It then issues exact-ID focus, verifies the resulting server focus, and sends session.select with both session and window IDs to that client. It does not retry a failed mutation or select a nearby pane.

rex focus and rex window focus change server state without Remote Control. Their success does not confirm that the app shows the target tab.

Session focus is shared server state. Other apps attached to that session can observe a focus change even though app selection targets only one client. If app selection is refused, server focus may already have changed; the error states this. A timed-out focus or app-selection request can still complete later. The separate Rex operations are not a transaction: concurrent layout or focus changes by another client remain a race. Brachio checks between operations but cannot lock the native app.

External commands use separate arguments, null stdin, bounded output, and deadlines (three-second Rex requests, four-second local command wall time). The event stream has no lifetime deadline. Shutdown cancels and reaps only Brachio-owned CLI process groups; it does not close Rex sessions, agent processes, or user terminals. Normal exit, handled signals, errors, and panic unwinding restore terminal modes. SIGKILL, process abort, or terminal failure cannot guarantee cleanup.

Rex labels and reports are untrusted display text. Control characters and direction overrides are removed. No terminal-screen scraping, database, plugin system, or multi-terminal backend is used.

Verification

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo build --release
uv lock --check
uv build
uvx --isolated --no-index --find-links dist brachio --version
uvx --isolated --no-index --find-links dist brachio --help

uv build builds a source distribution, then builds the local platform wheel from it. The CLI smoke tests do not start the TUI or contact Rex.

Tests use synthetic JSON, a local mock CLI, Ratatui's test backend, and owned PTYs. They do not control the real Rex app. See Rex compatibility and handoff for the measured environment, repeatable read-only queries, test evidence, native UI checks, and release restrictions.

Structure

flowchart LR
    Input[Keyboard or mouse] --> TUI[View and stable selection]
    TUI --> Worker[Background worker]
    Worker --> Rex[Rex discovery and navigation]
    Rex --> CLI[Official Rex CLI]
    CLI --> Server[Status and exact pane focus]
    CLI --> App[Selected Rex app]
    Events[CLI event stream] --> Worker
  • src/model.rs: identities, status ordering, report grouping, display filtering.
  • src/rex.rs: verified CLI schemas, snapshots, and navigation.
  • src/process.rs: bounded subprocess I/O and owned-process cleanup.
  • src/worker.rs: reconciliation, event reconnect, and navigation scheduling.
  • src/tui.rs: view state, rendering, selection, scrolling, and input.
  • src/tui/list.rs: grouping and filtering.
  • src/tui/presentation.rs: responsive columns, status display, clipping, and footer text.
  • src/main.rs: CLI, terminal guard, signal handling, and application loop.

Recovery and release limits

Brachio retries transient connection and initial app-discovery failures. Exit and restart to choose another client or resolve ambiguous selection. It has no persistent state or migrations. Remove the local binary to uninstall. If an uncatchable termination leaves a damaged terminal, use that terminal's reset operation.

Native app switching and physical mouse delivery require the manual checks in the handoff document before claiming end-to-end platform support. Windows is not supported. The CI workflow checks Linux and macOS PTY/process behavior; native Rex UI behavior is not established by those tests.

The publishing guide describes the single Release workflow for PR note checks, PAT-authenticated Release PRs, and publication to crates.io and PyPI, plus registry setup, verification, and recovery. Add or update a .changenote/ note for changes that need a release, then run changenote status. A maintainer must configure PAT_TOKEN and both registries before merging a Release PR to publish. Separate manual release actions need explicit authorization. Publication is not a transaction across the two registries.

Metadata

Release files for brachio 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brachio 1.0.0
File Size Uploaded Provenance Actions
brachio-1.0.0.tar.gz 112.2 kB Without provenance Details for brachio-1.0.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for brachio 1.0.0
File Actions
brachio-1.0.0-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for brachio-1.0.0-py3-none-manylinux_2_28_x86_64.whl
brachio-1.0.0-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for brachio-1.0.0-py3-none-manylinux_2_28_aarch64.whl
brachio-1.0.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for brachio-1.0.0-py3-none-macosx_11_0_arm64.whl
brachio-1.0.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for brachio-1.0.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 2.4 MB

Release files / brachio-1.0.0.tar.gz

Download URL brachio-1.0.0.tar.gz
Size 112.2 kB
Tags Source
SHA-256 checksum
How to use checksums
235c4aa0d087771b2d2112c5b45292fb3295f4d5dc3e3acb904aff462cb5b5fa
BLAKE2b-256 checksum
How to use checksums
c60de4f47644b9431eec5dcac9c6989b83406d8d5c36068b28f37285bb338581
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / brachio-1.0.0-py3-none-manylinux_2_28_x86_64.whl

Download URL brachio-1.0.0-py3-none-manylinux_2_28_x86_64.whl
Size 592.6 kB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
5ada426e1a429a80c49a9039a4cb53d3c5f63678c3e5a7defdc9430c9e7e23c0
BLAKE2b-256 checksum
How to use checksums
1be135f9de240251434d4203314bde5c40e04f9f7d513521993377e95dd2dce9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / brachio-1.0.0-py3-none-manylinux_2_28_aarch64.whl

Download URL brachio-1.0.0-py3-none-manylinux_2_28_aarch64.whl
Size 566.2 kB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
8b109dea122dd6dc75fc3f4c5bd5516ae4a6770655edd9f062854e91597ae10c
BLAKE2b-256 checksum
How to use checksums
c1a3a3048c862f050a74e1a93092b7f0cbc3ab79b3b1dab52a388bca41f0da3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / brachio-1.0.0-py3-none-macosx_11_0_arm64.whl

Download URL brachio-1.0.0-py3-none-macosx_11_0_arm64.whl
Size 555.8 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5e341ae4d070fbecdba8449315c85530464185ae8d2e6c31a36f3c4b148733aa
BLAKE2b-256 checksum
How to use checksums
52c647eb74bdcb20e9d14b2eaafe3d502075f75aa0f84f30506e28dfba0a54fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / brachio-1.0.0-py3-none-macosx_10_12_x86_64.whl

Download URL brachio-1.0.0-py3-none-macosx_10_12_x86_64.whl
Size 573.6 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
7121c2f37ecdc96168b6290f5aa404d490c22580cc9d538b4672311dc9ce58a7
BLAKE2b-256 checksum
How to use checksums
bc4494698b11261e569e1fe8bc92039f9560a94f62ec551c4c75b3cdc21f13fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for brachio 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page