cleveragents-core/docs/tui/input-and-sessions.md

TUI: Reference/Command Input & Session Management (v3.7.0)

Milestone: v3.7.0 — M8: TUI Implementation Parent: TUI Overview

---

Reference and Command Input

The TUI prompt supports three input modes, each activated by a distinct prefix character. This system is defined in ADR-046.

Input Modes

First Character	Mode	Prompt Symbol	Sent To
(any other)	Normal	>	Actor via A2A
@ (inline)	Normal + Reference	>	Actor (with CRP directives)
/	Command	/	TUI command processor
!	Shell	$	Host OS subprocess

@ Reference System

Type @ anywhere in a normal-mode prompt to open the Reference Picker overlay. This provides real-time fuzzy search across all registered projects, plans, and resources.

@project:cleveragents              # Reference an entire project
@project:cleveragents:src/foo.py   # Reference a specific file
@plan:01HXM8C2                     # Reference a plan by ULID
@plan:01HXM8C2:decision/D3         # Reference a specific decision
@handler.py                        # Fuzzy match (expands to canonical form)

Resolved @ references are translated into CRP (Context Request Protocol) directives that direct the ACMS to prioritize the referenced resources in context assembly. They are not merely display annotations — they have real semantic effect on what the actor sees.

Reference Picker Overlay

+- Reference Picker -----------------------------------------------+
| @hand                                                            |
| ---------------------------------------------------------------- |
|  PROJECT  api-service:src/auth/handler.py                        |
|           local/api-service * Python * 245 lines                 |
|                                                                  |
|  PROJECT  cleveragents:git_dir/src/cli/commands/handler.py       |
|           local/cleveragents * Python * 189 lines                |
|                                                                  |
|  PLAN     fix-auth-handler (01HXM8C2...)                         |
|           Phase: Execute * Actor: claude-4-sonnet                |
|                                                                  |
| enter Select | tab Tree | ctrl+p Projects | ctrl+l Plans         |
+------------------------------------------------------------------+

Navigation: up/down to move, enter to select, tab to switch to tree browser mode, escape to dismiss.

/ Command System

Type / at the start of the prompt to open the Slash Command overlay with tab completion. Commands cover all TUI operations and mirror the CLI command set.

Key command namespaces:

Namespace	Examples
/session:*	create, list, switch, close, export, import
/persona:*	list, set, create, edit, delete, export, import
/scope:*	add, remove, clear, show
/plan:*	use, list, status, tree, execute, apply, cancel, diff, correct
/project:*	list, create, show, delete, inspect
/actor:*	list, show, set-default
/resource:*	list, show, tree, inspect
/config:*	list, get, set
TUI utilities	/clear, /theme, /settings, /help, /about, /debug

! Shell Mode

Type ! at the start of the prompt to enter shell mode. Commands execute on the host OS and output appears as ShellResult blocks in the conversation stream.

! git status          # Run git status
! ls -la src/         # List directory
! python -m pytest    # Run tests

Shell mode features:

• Separate command history (navigable with up/down)
• File/directory tab completion
• Dangerous command detection (destructive patterns highlighted in red with confirmation)
• Real-time output streaming for long-running commands
• ctrl+c sends SIGINT to the subprocess

---

Session Management

Each session tab represents an independent domain Session (ADR-020) with its own conversation history, persona binding, and A2A Task.

Session Tabs

Session tabs appear at the top of the screen when two or more sessions are open:

Key	Action
ctrl+n	Create a new session tab with the current persona
ctrl+w	Close the current session tab (confirms if conversation exists)
ctrl+[	Switch to the previous session tab
ctrl+]	Switch to the next session tab
ctrl+r	Resume a previous session from the Sessions screen

Session tab state indicators:

• ⌛ — actor is working
• > — awaiting user input
• (plain) — idle

Session Persistence

Sessions are persisted to SQLite at ~/.local/state/cleveragents/tui.db. This includes:

• Full conversation history (all message blocks)
• Session metadata (persona, actor, creation time, last activity)
• Session cost accumulation

Sessions persist across TUI restarts. Use ctrl+r or /session:list to resume a previous session.

Sessions Screen

The Sessions screen (ctrl+s or /session:list) provides a full-screen view of all sessions:

• Sortable by name, date, cost, or message count
• Search/filter by persona, actor, or keyword
• Bulk operations: delete multiple sessions, export session history
• Resume any session with enter

---

Related ADRs

ADR	Title	Relevance
ADR-046	TUI Reference and Command System	@ references, / commands, ! shell
ADR-020	Session Model	Session persistence and management

---

Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope as of 2026-04-15. Some features may be adjusted as implementation progresses.

Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot