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

> **Milestone:** v3.7.0 — M8: TUI Implementation
> **Parent:** [TUI Overview](index.md)

---

## 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](../adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference and Command System | @ references, / commands, ! shell |
| [ADR-020](../adr/ADR-020-session-model.md) | 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*