HAL9000
dde71cf8e2
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 1m12s
CI / quality (pull_request) Successful in 1m24s
CI / push-validation (pull_request) Successful in 33s
CI / helm (pull_request) Successful in 34s
CI / typecheck (pull_request) Successful in 1m33s
CI / build (pull_request) Successful in 1m13s
CI / benchmark-regression (pull_request) Failing after 37s
CI / security (pull_request) Successful in 2m25s
CI / e2e_tests (pull_request) Successful in 4m31s
CI / unit_tests (pull_request) Successful in 6m25s
CI / integration_tests (pull_request) Successful in 6m24s
CI / docker (pull_request) Successful in 1m36s
CI / coverage (pull_request) Successful in 13m7s
CI / coverage (push) Blocked by required conditions
CI / docker (push) Blocked by required conditions
CI / status-check (push) Blocked by required conditions
CI / benchmark-publish (push) Waiting to run
CI / benchmark-regression (push) Waiting to run
CI / status-check (pull_request) Successful in 5s
CI / push-validation (push) Successful in 31s
CI / quality (push) Successful in 1m22s
CI / lint (push) Successful in 1m28s
CI / helm (push) Successful in 43s
CI / build (push) Successful in 1m0s
CI / security (push) Successful in 1m41s
CI / typecheck (push) Successful in 2m5s
CI / e2e_tests (push) Successful in 4m13s
CI / integration_tests (push) Successful in 4m37s
CI / unit_tests (push) Has been cancelled
Split docs/advanced-concepts.md (554 lines) into four sub-documents under docs/advanced-concepts/ and docs/tui.md (634 lines) into four sub-documents under docs/tui/, each under the 500-line limit per CONTRIBUTING.md. Advanced Concepts sub-documents: - docs/advanced-concepts/index.md: Overview, context strategies, LLM backends - docs/advanced-concepts/resource-types.md: Resource types, A2A rename - docs/advanced-concepts/container-tools.md: Container tools, scope chain, budgets, safety - docs/advanced-concepts/e2e-tests-and-plugins.md: E2E tests, code review, plugins TUI sub-documents: - docs/tui/index.md: Overview, getting started, main screen layout - docs/tui/sidebar-and-personas.md: Sidebar states, persona system - docs/tui/input-and-sessions.md: Reference/command input, session management - docs/tui/configuration-and-integration.md: Config, key bindings, theme, integration Updated mkdocs.yml navigation to reflect new sub-document structure. Updated CONTRIBUTORS.md with contribution entry for PR #9903. ISSUES CLOSED: #10533
157 lines
5.8 KiB
Markdown
157 lines
5.8 KiB
Markdown
# 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*
|