TUI Guide

This document covers interactive terminal usage for psi (--tui).

Integration harness (tmux)

A baseline tmux-backed integration harness test exists at:

• components/tui/test/psi/tui/tmux_integration_harness_test.clj

Reusable harness helpers live at:

• components/tui/test/psi/tui/test_harness/tmux.clj

What it validates:

1. start psi TUI in detached tmux using the resolved launcher command
   • prefers canonical installed command: exec psi --tui
   • falls back to repo-local launcher when psi is not on PATH: exec bb bb/psi.clj -- --tui
2. wait until prompt is ready (刀: / Type a message)
3. send /help and assert help output marker appears
4. send /quit and assert pane process exits the Java TUI process

Run it explicitly (integration tests are skipped by default in tests.edn):

clojure -M:test --focus psi.tui.tmux-integration-harness-test --skip-meta foo

Start

# Basic TUI start
psi --tui

# OpenAI example
psi --model gpt-4o --tui

# TUI with live nREPL introspection
psi --tui --nrepl 8888

Development/non-canonical alternatives may still use repo-local clojure -M:run ... paths, but the launcher-owned psi command is now the primary operator path.

OAuth Login (no env var needed)

/login    # browser-based OAuth flow
/logout

In-session commands

/status /history /new /resume /tree [session-id] /worktree /help /quit /skills /prompts /remember [text] /project-repl /project-repl start /project-repl attach /project-repl stop /project-repl eval <code> /project-repl interrupt /skill:<name> plus any extension commands such as /work-on, /work-done, /work-rebase, /work-status

Multi-session commands

• /resume dispatches to the backend; when selection is needed, the backend requests a frontend action and TUI renders the persisted-session picker (session files on disk).
• /tree dispatches to the backend; when selection is needed, the backend requests a frontend action and TUI renders the live context session picker (in-process multi-session view).
• /tree <session-id|prefix> switches directly to a live context session by id.
• /tree name <session-id|prefix> <name> assigns an explicit human name to a live context session.
• In /tree picker mode, sessions render in parent/child order with explicit tree glyphs (root ●, branch connectors ├─ / └─ / │).
• Right-side status cells are column-aligned across rows ([active] [stream]) to keep deep trees and mixed session states visually stable.

The selector UI is frontend-native, but candidate lists and command semantics are backend-owned.