# TUI Interface Guide

Master the RiceCoder Terminal User Interface for efficient code generation and chat interactions.

**Status**: ✅ Complete

**Last Updated**: December 3, 2025

---

## Overview

The RiceCoder TUI (Terminal User Interface) provides an interactive chat-like experience for code generation, analysis, and conversation. It's designed for developers who prefer working in the terminal and want a responsive, keyboard-driven interface.

### Key Concepts

- **Chat-based interaction**: Ask questions and get responses in a conversational format
- **Real-time streaming**: See AI responses appear in real-time as they're generated
- **Multiple modes**: Switch between different interaction modes (ask, code, vibe)
- **Session persistence**: Your conversations are saved and can be resumed
- **Keyboard-driven**: Navigate and interact entirely with the keyboard
- **Syntax highlighting**: Code blocks are highlighted for readability

---

## Starting the TUI

### Basic Usage

```bash
rice chat
```

This starts the interactive TUI with your configured AI provider.

### With Specific Provider

```bash
# Use OpenAI
rice chat --provider openai

# Use local Ollama
rice chat --provider ollama

# Use Anthropic
rice chat --provider anthropic
```

### With Specific Model

```bash
rice chat --model gpt-4
rice chat --model claude-3-opus
rice chat --model mistral
```

### Exiting the TUI

Press `Ctrl+C` to exit the chat at any time. Your conversation is automatically saved.

---

## Interface Layout

The TUI is organized into several sections:

```text
┌─────────────────────────────────────────────────────────────┐
│ RiceCoder Chat - Session: default                    [1/10] │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│ > What's the best way to structure a Rust project?          │
│                                                               │
│ RiceCoder:                                                    │
│ Here are the key principles for structuring a Rust project:  │
│                                                               │
│ 1. Separate concerns into modules                            │
│ 2. Use meaningful names                                      │
│ 3. Keep modules focused                                      │
│                                                               │
├─────────────────────────────────────────────────────────────┤
│ r[ >                                                          │
│ Type your message and press Enter to send                    │
└─────────────────────────────────────────────────────────────┘
```

### Components

- **Header**: Shows session name and message count
- **Message Area**: Displays conversation history with syntax highlighting
- **Input Area**: Where you type your messages
- **Status Bar**: Shows helpful hints and keyboard shortcuts

---

## Navigation

### Scrolling Through Messages

Navigate through your conversation history:

| Key | Action |
|-----|--------|
| `↑` / `↓` | Scroll up/down one line |
| `Page Up` | Scroll up one screen |
| `Page Down` | Scroll down one screen |
| `Home` | Jump to beginning of conversation |
| `End` | Jump to end of conversation |

### Selecting Text

Copy text from the conversation:

| Key | Action |
|-----|--------|
| `Shift+↑` / `Shift+↓` | Select text line by line |
| `Shift+Page Up` | Select screen by screen |
| `Shift+Page Down` | Select screen by screen |
| `Ctrl+C` | Copy selected text (or exit if nothing selected) |

### Message Navigation

Move between messages:

| Key | Action |
|-----|--------|
| `Ctrl+P` | Previous message |
| `Ctrl+N` | Next message |
| `Ctrl+Home` | First message |
| `Ctrl+End` | Last message |

---

## Keyboard Shortcuts

### Input Editing

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Shift+Enter` | New line in message |
| `Ctrl+A` | Move to start of line |
| `Ctrl+E` | Move to end of line |
| `Ctrl+U` | Clear line |
| `Ctrl+W` | Delete word |
| `Backspace` | Delete character |
| `Delete` | Delete character forward |

### Message Editing

| Key | Action |
|-----|--------|
| `↑` (in input) | Previous message from history |
| `↓` (in input) | Next message from history |
| `Ctrl+R` | Search message history |
| `Ctrl+L` | Clear screen |

### Session Management

| Key | Action |
|-----|--------|
| `Ctrl+S` | Save current session |
| `Ctrl+O` | Open session |
| `Ctrl+N` | New session |
| `Ctrl+D` | Delete session |

### Mode Switching

| Key | Action |
|-----|--------|
| `/ask` | Switch to Ask mode |
| `/code` | Switch to Code mode |
| `/vibe` | Switch to Vibe mode |
| `Ctrl+M` | Show mode menu |

### Other Commands

| Key | Action |
|-----|--------|
| `Ctrl+C` | Exit TUI |
| `Ctrl+H` | Show help |
| `Ctrl+?` | Show keyboard shortcuts |
| `/help` | Show command help |

---

## Modes

RiceCoder supports different interaction modes optimized for different tasks.

### Ask Mode

General-purpose conversation and questions.

```bash
/ask
```

**Best for**:
- Asking questions about code
- Getting explanations
- Brainstorming ideas
- General conversation

**Example**:
```text
r[ > /ask
r[ > How do I implement error handling in Rust?
```

### Code Mode

Focused on code generation and analysis.

```bash
/code
```

**Best for**:
- Generating code
- Analyzing existing code
- Refactoring suggestions
- Code review

**Example**:
```text
r[ > /code
r[ > Generate a function to parse JSON
```

### Vibe Mode

Creative and exploratory mode.

```bash
/vibe
```

**Best for**:
- Exploring ideas
- Creative writing
- Brainstorming
- Experimental features

**Example**:
```text
r[ > /vibe
r[ > What would a futuristic CLI tool look like?
```

### Switching Modes

Switch modes at any time:

```bash
r[ > /ask
r[ > /code
r[ > /vibe
```

Or use the keyboard shortcut:

```bash
Ctrl+M  # Show mode menu
```

---

## Session Management

Sessions save your conversation history and can be resumed later.

### Creating Sessions

Sessions are created automatically when you start the TUI:

```bash
rice chat
# Creates default session
```

Create a named session:

```bash
rice chat --session my-project
```

### Listing Sessions

```bash
rice session list
```

Output:
```text
Sessions:
  default (10 messages, last used 2 hours ago)
  my-project (25 messages, last used 1 day ago)
  experiments (5 messages, last used 1 week ago)
```

### Switching Sessions

In the TUI:

```bash
/session switch my-project
```

Or from the command line:

```bash
rice chat --session my-project
```

### Saving Sessions

Sessions are automatically saved. To manually save:

```bash
Ctrl+S
```

### Deleting Sessions

```bash
rice session delete my-project
```

Or in the TUI:

```bash
/session delete my-project
```

### Exporting Sessions

Export a session to a file:

```bash
rice session export my-project > my-project.txt
```

---

## Tips & Tricks for Power Users

### 1. Use Multi-line Messages

For longer messages, use `Shift+Enter` for new lines:

```bash
r[ > This is a long message
r[ > that spans multiple lines
r[ > and is easier to read
```

### 2. Search Message History

Find previous messages quickly:

```bash
Ctrl+R
# Type to search
```

### 3. Copy Code Blocks

Select and copy code from responses:

```bash
Shift+↑/↓  # Select text
Ctrl+C     # Copy
```

### 4. Use Command Shortcuts

Define custom shortcuts in `.agent/config.yaml`:

```yaml
shortcuts:
  test: /code Generate a test for this function
  review: /code Review this code for issues
  explain: /ask Explain this code
```

Then use them:

```bash
r[ > /test
```

### 5. Pipe Commands

Use shell pipes to send file contents:

```bash
cat src/main.rs | rice chat
```

### 6. Batch Processing

Process multiple files:

```bash
for file in src/*.rs; do
  echo "=== $file ===" | rice chat
  cat "$file" | rice chat
done
```

### 7. Theme Customization

Change the TUI theme:

```bash
rice config set theme dracula
rice config set theme nord
rice config set theme solarized
```

Available themes:
- `dracula` - Dark theme with vibrant colors
- `nord` - Arctic, north-bluish color palette
- `solarized` - Precision colors for machines and people
- `monokai` - Dark theme with bright accents
- `gruvbox` - Retro groove color scheme

### 8. Keyboard Bindings

Customize keyboard bindings in `.agent/config.yaml`:

```yaml
keybindings:
  send-message: Enter
  new-line: Shift+Enter
  clear-screen: Ctrl+L
  exit: Ctrl+C
```

### 9. Auto-save Interval

Configure how often sessions are saved:

```yaml
session:
  auto-save-interval: 30s
  max-history: 1000
```

### 10. Streaming Control

Control how responses are streamed:

```yaml
streaming:
  enabled: true
  chunk-size: 50
  delay-ms: 10
```

---

## Troubleshooting

### Issue: TUI doesn't start

**Solution**: Check your configuration:

```bash
rice config show
```

Ensure you have:
- A valid API key configured
- A valid provider configured
- Network connectivity

### Issue: Responses are slow

**Solution**: Check your network and provider:

```bash
# Test with a local model
rice chat --provider ollama

# Check API status
rice info
```

### Issue: Text is cut off or misaligned

**Solution**: Resize your terminal window:

```bash
# Make terminal larger
# Or use a different terminal emulator
```

### Issue: Copy/paste not working

**Solution**: Check your terminal's clipboard support:

```bash
# Try using your terminal's native copy/paste
# Or configure clipboard in .agent/config.yaml
```

### Issue: Sessions not saving

**Solution**: Check file permissions:

```bash
ls -la ~/.ricecoder/sessions/
chmod 755 ~/.ricecoder/sessions/
```

### Issue: Mode switching not working

**Solution**: Ensure you're using the correct syntax:

```bash
# Correct
/ask
/code
/vibe

# Incorrect
ask
code
vibe
```

### Issue: Keyboard shortcuts not responding

**Solution**: Check your terminal's key handling:

```bash
# Some terminals don't support all key combinations
# Try a different terminal emulator
# Or reconfigure keybindings in .agent/config.yaml
```

### Issue: Colors not displaying correctly

**Solution**: Check your terminal's color support:

```bash
# Enable 256-color support
export TERM=xterm-256color

# Or change theme
rice config set theme monokai
```

---

## Configuration

### TUI-Specific Settings

Configure TUI behavior in `.agent/config.yaml`:

```yaml
tui:
  # Display settings
  theme: dracula
  font-size: 12
  line-height: 1.5
  
  # Behavior settings
  auto-scroll: true
  word-wrap: true
  syntax-highlight: true
  
  # Session settings
  auto-save: true
  auto-save-interval: 30s
  max-history: 1000
  
  # Streaming settings
  streaming: true
  chunk-size: 50
  delay-ms: 10
```

### Keyboard Bindings

Customize keyboard shortcuts:

```yaml
keybindings:
  send-message: Enter
  new-line: Shift+Enter
  clear-screen: Ctrl+L
  exit: Ctrl+C
  scroll-up: Page Up
  scroll-down: Page Down
  previous-message: Ctrl+P
  next-message: Ctrl+N
  search-history: Ctrl+R
```

### Theme Customization

Create a custom theme:

```yaml
themes:
  my-theme:
    background: "#1e1e1e"
    foreground: "#d4d4d4"
    primary: "#007acc"
    secondary: "#ce9178"
    error: "#f48771"
    success: "#6a9955"
```

---

## Accessibility

### Screen Reader Support

Enable screen reader support:

```bash
rice config set accessibility.screen-reader true
```

### High Contrast Mode

Use high contrast theme:

```bash
rice config set theme high-contrast
```

### Keyboard-Only Navigation

All features are accessible via keyboard. No mouse required.

### Font Size

Adjust font size:

```bash
rice config set tui.font-size 14
```

---

## Performance

### Optimize for Large Conversations

For sessions with many messages:

```yaml
session:
  max-history: 500  # Limit history
  auto-save-interval: 60s  # Save less frequently
  compress-old-messages: true  # Compress old messages
```

### Reduce Memory Usage

```yaml
tui:
  streaming:
    chunk-size: 25  # Smaller chunks
    delay-ms: 20    # Longer delay
```

### Improve Responsiveness

```yaml
tui:
  auto-scroll: false  # Disable auto-scroll
  syntax-highlight: false  # Disable highlighting
```

---

## See Also

- [Quick Start Guide](./Quick-Start.md) - Get started with RiceCoder
- [Configuration Guide](./Configuration.md) - Configure RiceCoder
- [CLI Commands](./CLI-Commands.md) - Learn all CLI commands
- [Troubleshooting Guide](./Troubleshooting.md) - Solve common problems
- [FAQ](./FAQ.md) - Frequently asked questions

---

*Last updated: December 3, 2025*