# Conversations Browser Specification

status: implemented
date: 2026-01-24

## Overview

A lazygit-style fullscreen TUI for browsing and resuming past conversations. Two-pane layout with session list on the left and message preview on the right.

## Command

```
/conversations
```

Aliases: `/convos`, `/sessions`

## UI Layout

```
+--[Sessions 16]----------+--[frost-call | main | 42m]------------------+
|                         |                                              |
| > frost-call       5m   |  [user]                                      |
|   wolf-blade      12m   |  Can you help me fix the resume plugin       |
|   iron-storm      1h    |                                              |
|   crystal-dawn    2h    |  [assistant]                                 |
|   cyber-surge     3h    |  I'll help you fix the resume plugin.        |
|   alpha-wave      1d    |  Let me first explore the codebase...        |
|                         |                                              |
|                         |  [user]                                      |
|                         |  yes do that                                 |
|                         |                                              |
+-------------------------+----------------------------------------------+
| Tab: switch | Up/Down: navigate | Enter: resume | q/Esc: quit          |
+------------------------------------------------------------------------+
```

## Navigation Model

### Two-Pane System

The interface has two panes that can be switched with Tab:

1. **Sessions Pane (left)**: List of past conversations
2. **Messages Pane (right)**: Preview of selected conversation

### Sessions Pane Controls

```
Up/Down     Navigate session list
Enter       Resume selected session
Tab         Switch to messages pane
q/Esc       Exit browser
```

### Messages Pane Controls

```
Up/Down     Scroll message history
PageUp/Dn   Page scroll
Tab         Switch to sessions pane
Enter       Resume selected session
q/Esc       Exit browser
```

## Visual States

### Session List Item

```
Selected + Active Pane:    Primary color background, dark text
Selected + Inactive Pane:  Dark[1] background, normal text
Unselected:                Dark[0] background, dim text
```

### Message Roles

```
[user]       Dark[1] background, user_tag color (cyan)
[assistant]  Dark[1] background, ai_tag color (green)
Content      Dark[0] background, normal text
```

### Headers

```
Active Pane:    Primary color background
Inactive Pane:  Dark[0] background, dim text
```

## Data Sources

```python
# Session list
sessions = conversation_manager.get_available_sessions()
# Returns: [{session_id, message_count, duration, git_branch, ...}]

# Message preview
messages = conversation_manager.get_session_messages(session_id)
# Returns: [{role, full_content, preview, timestamp}]
```

## Filtering

Sessions with only 1 message are filtered out (not useful conversations).

## Session Resume

When Enter is pressed:
1. Plugin stores selected session in `self.selected_session`
2. Plugin sets `self.should_resume = True`
3. Plugin exits (returns True from handle_input)
4. Command handler checks `get_resume_session()`
5. If session returned, calls `conversation_manager.load_session(session_id)`

## Implementation Files

```
plugins/fullscreen/conversations_plugin.py   Main plugin class
kollabor/fullscreen/command_integration.py       Resume handling (modified)
tests/tmux/test_conversations_plugin.sh      Verification test
```

## Technical Details

### Flicker-Free Rendering

- No `clear_screen()` call in render loop
- All content written to specific positions with full-width padding
- Frame buffering handled by FullScreenSession (begin_frame/end_frame)

### Design System Integration

```python
from kollabor.ui.design_system import T, S, C, solid, solid_fg

# Theme colors
theme = T()
theme.primary[0]   # Header backgrounds (active)
theme.dark[0]      # Content backgrounds
theme.dark[1]      # Selected item backgrounds
theme.text         # Normal text
theme.text_dim     # Dimmed text
theme.user_tag     # User role color
theme.ai_tag       # Assistant role color

# Solid backgrounds
solid(text, bg_rgb, fg_rgb, width)
solid_fg(text, fg_rgb)

# Unicode characters
C['line_v']        # Vertical separator
C['arrow_right']   # Selection indicator
C['half_bottom']   # Header edge
```

### Plugin Metadata

```python
PluginMetadata(
    name="conversations",
    description="Browse and manage conversations",
    version="1.0.0",
    author="Kollabor",
    category="system",
    icon="[HST]",
    aliases=["convos", "sessions"]
)
```

## Verification

```bash
./tests/tmux/test_conversations_plugin.sh
# Expected: PASS (2/2)
```

Test assertions:
1. Sessions list visible
2. Navigation hints visible
