Skip to content

Launching the TUI

This page lists how to start the sase TUI, its CLI options, screenshot capture, and clipboard transports.

Launching

sase tui [QUERY] [options]

Run sase tui from an interactive terminal. It opens on the Agents tab and starts the service host (pass -x to skip that). Press ? on any tab for the keymap and a short guide, : for the Command Line, ; for the Command Palette, and q to quit. Settings live under the ace: section of sase.yml (for example ace.keymaps and ace.page_size). See TUI migration notes.

If no Patches query is provided, sase's TUI loads the last used Patches query, then the first saved Patches query, then falls back to !!! for error suffixes. The top-level Agents tab restores its own last submitted Agents query after startup.

CLI Options

Flags, defaults, and aliases are listed on the generated sase tui page. See TUI migration notes for --model-size and --tab aliases. Auto-refresh intervals are described under Auto-Refresh.

When profiling is enabled, sase's TUI writes text output to PATH. If PATH is omitted, it uses the managed temp tree: $SASE_TMPDIR/ace-profiles/ace_profile_<timestamp>.txt when SASE_TMPDIR is set, or $SASE_HOME/tmp/ace-profiles/ace_profile_<timestamp>.txt otherwise (SASE_HOME defaults to ~/.sase). On exit, sase's TUI prints the shortened path and copies it when a clipboard tool is available.

Examples

sase tui                              # Last query, first saved query, or "!!!"
sase tui '"feature" AND "Drafted"'    # Filter by name and status
sase tui '+myproject'                 # Filter by project
sase tui -m small -r 30 '!!! OR @@@' # Small model, 30s refresh

When --profile is enabled, sase's TUI prints a shortened profile-output path after the TUI exits and tries to copy that shortened path to the system clipboard (pbcopy, wl-copy, xclip, or xsel when available).

Agent Screenshots

Use sase screenshot when you need a PNG of the real TUI state an agent would see. Flags are listed on the generated sase screenshot page. The command starts sase tui in the detached sase_ace_agents tmux session at 120x40, waits for the screen to paint, sends optional tmux keys, asks the live app to export SVG, then rasterizes that SVG with the same bundled-font renderer used by the golden PNG suite.

sase screenshot -o /tmp/sase.png
sase screenshot -p j -p j -w 'Ready' -o /tmp/sase.png
sase screenshot -p / -w INSERT --type 'machine:apollo' -w 'machine:apollo' -p enter -o /tmp/sase.png
sase screenshot --host apollo -o /tmp/sase-remote.png
sase screenshot --keep -- -t services
sase screenshot --window sase_ace_agents:sase_tmux_1 -o /tmp/sase-again.png

Repeatable -p/--press, -T/--type, and -w/--wait-for form one argv-ordered input script, so a query filter can be typed and submitted without a second --window capture. --type sends literal TUI text (tmux send-keys -l). Send the query key as a literal -p /: tmux has no slash key name, so -p slash types the letters slash. Wait for the input to open (-w INSERT) before typing, and wait for the typed text before -p enter.

By default, the tmux window is killed after capture. Pass --keep to leave it running, drive it manually with tmux send-keys, and recapture it later with --window. The command pins TUI animations off and uses truecolor terminal defaults, but it still shows live machine state and timestamps by design. If capture times out, the error includes the final tmux capture-pane text so you can see what the TUI was showing.

Pass --host to run the live TUI and SVG export on an enrolled machine alias or any raw SSH destination, then fetch the SVG and rasterize it locally. Enrollment only supplies a convenient ssh_target; SSH itself is full shell access and uses your normal SSH trust boundary, not gateway-scoped credentials. Remote screenshots show that machine's installed sase and state, not your local working tree. The remote sase commands run through the account's noninteractive login shell so tools installed under login-profile paths such as ~/.local/bin can be found without allocating a terminal. Check the printed remote_sase_version=sase <version> line when comparing results; it is read from sase version --json on the remote host. A remote host needs sase, tmux, and SSH access, but it does not need the local visual rasterizer dependencies.

Clipboard Transports

Every copy inside sase's TUI runs in the background and tries both a verifiable system transport and OSC 52 for the client terminal. Inside tmux, sase's TUI tries tmux load-buffer -w - first; otherwise the system candidates are pbcopy, wl-copy, xclip, and xsel as appropriate for the platform and display environment. A plain Copied … toast means a subprocess transport confirmed success, while Copied … (OSC 52) means sase's TUI emitted the terminal escape sequence without a verifiable subprocess result. OSC 52 payloads above the terminal-safe size limit are skipped. If neither transport works, sase's TUI opens the generated text in a read-only fallback view so it can still be selected and recovered.

Moved to sase screenshot. Moved to sase screenshot.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.