# TUI: Sidebar States & Persona System (v3.7.0)

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

---

## Sidebar States

The sidebar cycles through three states via `shift+tab`:

| State | Layout | Input Focus | Content |
|-------|--------|-------------|---------|
| **Hidden** | Sidebar has `display: none`; conversation takes full width | Prompt retains focus | No sidebar content visible |
| **Visible** | Sidebar docked right, 32-40 chars wide | Prompt retains focus; `ctrl+b` focuses sidebar | Plans and Projects panels in collapsible containers; read-only status |
| **Fullscreen** | Sidebar covers entire screen | Sidebar takes input focus | Extended plan/project details, persona management, selection mode |

State transitions:

```
Hidden --shift+tab--> Visible --shift+tab--> Fullscreen
  ^                                              |
  +-------------- escape (x1-2) ----------------+
```

In fullscreen mode, `escape` returns to visible; another `escape` returns to hidden. This
cascading escape behavior is consistent across all TUI states — pressing `escape` always
moves toward the main screen.

### Plans Panel

The Plans panel (visible and fullscreen sidebar) shows:

- Active plans with their current phase and state
- Phase indicator: `Strategize` / `Execute` / `Apply` / `Complete` / `Error`
- State badge: `Running` / `Paused` / `Waiting` / `Complete`
- Decision depth counter (number of decisions made)
- Real-time updates via A2A event subscription

### Projects Panel

The Projects panel shows:

- All registered projects with their resource counts
- Scoped projects (from the active persona) highlighted with a pin indicator
- Recently accessed projects sorted to the top

---

## Persona System

Personas are TUI-only abstractions that bundle an actor, its configuration, project/plan
scope, and argument presets into a single switchable unit. They are defined in ADR-045.

### What a Persona Contains

```yaml
# ~/.config/cleveragents/personas/feature-dev.yaml
name: "feature-dev"
description: "Feature development with Claude on main projects"
actor: "anthropic/claude-4-sonnet"
color: "$primary"

base_arguments:
  thinking_effort: "medium"
  temperature: 0.7
  max_tokens: 16384

scoped_projects:
  - "local/cleveragents"
  - "local/api-service"

scoped_plans: []

argument_presets:
  - name: "default"
    display: "default"
    overrides: {}

  - name: "think-more"
    display: "think: high"
    overrides:
      thinking_effort: "high"

  - name: "quick"
    display: "quick"
    overrides:
      thinking_effort: "low"
      max_tokens: 4096

cycle_order: 1
```

### Switching Personas

- **`tab`** — cycle forward through personas in the configured cycle list
- **`/persona:set <name>`** — switch to a specific persona by name
- **Fullscreen sidebar** — select from the full persona list

When you switch personas, the PersonaBar updates immediately and subsequent prompts use the
new persona's actor and scope. Previous conversation history is retained.

### Argument Presets

**`ctrl+tab`** cycles through the current persona's argument presets:

```
default --> think: high --> think: max --> quick --> default --> ...
```

The active preset's display name appears in the PersonaBar. Effective arguments are computed
as `merge(base_arguments, active_preset.overrides)`.

### PersonaBar

The PersonaBar sits below the prompt input and is always visible:

```
  feature-dev | anthropic/claude-4-sonnet | think: high | 2 projects | $0.12
```

| Segment | Updates When |
|---------|-------------|
| Persona name | `tab` cycle |
| Actor name | `tab` cycle |
| Preset label | `ctrl+tab` cycle |
| Scope indicator | Persona change or `/scope:add/remove` |
| Session cost | After each actor response |

### Managing Personas

```bash
/persona:list              # List all personas
/persona:create            # Open PersonaEditorModal
/persona:edit feature-dev  # Edit an existing persona
/persona:delete old-persona # Delete a persona
/persona:export feature-dev # Export to YAML file
/persona:import ./shared.yaml # Import from YAML file
```

Personas are stored as YAML files in `~/.config/cleveragents/personas/` and are portable
between machines via export/import.

---

## Related ADRs

| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
| [ADR-045](../adr/ADR-045-tui-persona-system.md) | TUI Persona System | Persona data model and lifecycle |

---

*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*
