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
   • for unreleased worktree testing, prefers the repo-local launcher so the harness proves the current checkout rather than a stale installed psi on PATH
   • otherwise 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. For released installs, that path now depends on the jar-owned release metadata packaged inside the published psi artifact, so --tui smoke coverage should run through the installed/package-shaped launcher path rather than only through repo-local startup.

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] /model <provider> <model-id> /thinking <off|minimal|low|medium|high|xhigh> /speed [normal|fast [session|project|user]] /effort [low|medium|high|xhigh|none [session|project|user]] /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

Model, speed, and effort commands

• /model anthropic claude-opus-4-8 selects Claude Opus 4.8, an Anthropic adaptive-thinking model with native JSON Schema structured output and mid-conversation system-message support.
• /speed prints the effective speed mode. /speed fast selects the provider's alternate throughput tier for the current session. Add project or user to persist the setting; /speed normal session clears the session override. Anthropic maps fast mode to speed: "fast"; OpenAI chat-completions maps it to service_tier: "flex".
• /effort prints the active reasoning-effort override (none when unset). /effort xhigh overrides provider effort while thinking is enabled without changing /thinking; /effort none clears the override. Add project or user to persist the value or explicit clear.

The footer shows • fast when speed mode is fast and appends • effort:<value> to the thinking label when an effort override is active. Speed and effort are not restored from cold journal resume; project/user config only applies to newly created root sessions.

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.