# Sessions

**Status**: ✅ Complete

**Phase**: Phase 2 - Alpha Enhanced (v0.1.2)

**Last Updated**: December 4, 2025

---

## Overview

The Sessions feature enables developers to run multiple isolated agent conversations in parallel, persist sessions across terminal restarts, share sessions with teammates, and execute background agents without blocking the active session. Each session maintains its own context, conversation history, and execution state.

## Key Features

- **Multi-Session Support**: Run up to the configured limit of sessions simultaneously
- **Session Persistence**: Automatically save and restore sessions across restarts
- **Session Switching**: Seamlessly switch between active sessions without losing context
- **Conversation History**: Maintain ordered message history with timestamps and metadata
- **Context Management**: Isolate project context, files, and settings per session
- **Session Sharing**: Generate shareable links with configurable permissions and expiration
- **Background Agents**: Execute agents asynchronously without blocking the active session
- **Session Export**: Export complete sessions (context, history, metadata) to JSON files

## Installation & Setup

Sessions are built into RiceCoder and enabled by default. No additional installation is required.

### Configuration

Configure sessions in `.ricecoder/config.yaml`:

```yaml
sessions:
  # Maximum number of concurrent sessions
  max_sessions: 5
  
  # Session storage directory (relative to home)
  storage_dir: .ricecoder/sessions
  
  # Auto-save interval in seconds
  auto_save_interval: 30
  
  # Maximum history messages per session
  max_history: 1000
  
  # Session timeout in minutes (0 = no timeout)
  timeout_minutes: 0
```

## How to Use

### Basic Usage: Creating and Switching Sessions

Create a new session:

```bash
# Start RiceCoder (creates default session)
ricecoder

# Create a new session from the TUI
# Press Ctrl+N to create a new session
# Enter session name when prompted
```

Switch between sessions:

```bash
# In the TUI, use Ctrl+S to open session switcher
# Select a session from the list
# Press Enter to switch
```

View all sessions:

```bash
# In the TUI, press Ctrl+L to list all sessions
# Shows session name, status, creation date, and last message
```

### Advanced Usage: Session Management

Close a session:

```bash
# In the TUI, press Ctrl+W to close the active session
# Session is automatically saved before closing
```

Archive a session:

```bash
# In the TUI, press Ctrl+A to archive the active session
# Archived sessions are hidden from the main list
# Can be restored from the archive
```

Export a session:

```bash
# In the TUI, press Ctrl+E to export the active session
# Enter filename when prompted
# Session is saved as JSON with all context and history
```

### Session Sharing

Generate a shareable link:

```bash
# In the TUI, press Ctrl+Shift+S to share the active session
# Configure share permissions:
#   - Read-only: Prevent modifications
#   - Include history: Share conversation history
#   - Include context: Share project context and files
# Set expiration time (optional)
# Copy the generated link
```

Access a shared session:

```bash
# Open the shared link in RiceCoder
# Session displays in read-only mode
# View history and context based on permissions
# Import to create a local copy
```

Import a shared session:

```bash
# In the TUI, press Ctrl+I to import a shared session
# Paste the share link when prompted
# New local session created with shared content
```

### Background Agents

Start a background agent:

```bash
# In the TUI, press Ctrl+B to start a background agent
# Select agent type from menu
# Agent runs asynchronously
# Continue working in the active session
```

Monitor background agents:

```bash
# In the TUI, press Ctrl+Shift+B to view background agents
# Shows agent status: Running, Completed, Failed, Cancelled
# View agent output and logs
```

Control background agents:

```bash
# In the TUI, select an agent from the background agents list
# Press P to pause the agent
# Press C to cancel the agent
# Press R to resume a paused agent
```

## Configuration

### Session Limits

Control the maximum number of concurrent sessions:

```yaml
sessions:
  max_sessions: 5  # Limit to 5 concurrent sessions
```

When the limit is reached, you must close or archive a session before creating a new one.

### Storage Location

Configure where sessions are stored:

```yaml
sessions:
  storage_dir: .ricecoder/sessions  # Relative to home directory
```

Sessions are stored as JSON files in this directory. Each session file is named with the session ID.

### Auto-Save

Configure automatic session saving:

```yaml
sessions:
  auto_save_interval: 30  # Save every 30 seconds
```

Sessions are also saved when:
- Switching between sessions
- Closing a session
- Exporting a session
- Receiving a message

### History Limits

Control the maximum number of messages per session:

```yaml
sessions:
  max_history: 1000  # Keep last 1000 messages
```

When the limit is reached, oldest messages are archived.

### Session Timeout

Configure automatic session timeout:

```yaml
sessions:
  timeout_minutes: 60  # Timeout after 60 minutes of inactivity
```

Set to 0 to disable timeout.

## Examples

### Example 1: Multi-Project Development

Work on multiple projects simultaneously:

```bash
# Session 1: Project A
ricecoder
# Create session "project-a"
# Set context to /path/to/project-a
# Work on Project A

# Create Session 2: Project B
# Press Ctrl+N
# Create session "project-b"
# Set context to /path/to/project-b
# Work on Project B

# Switch between sessions
# Press Ctrl+S
# Select "project-a" or "project-b"
```

### Example 2: Sharing Code Review

Share a session for code review:

```bash
# In the TUI, press Ctrl+Shift+S
# Configure permissions:
#   - Read-only: Yes
#   - Include history: Yes
#   - Include context: Yes
# Set expiration: 24 hours
# Copy the link
# Send to teammate

# Teammate opens the link
# Views the code and conversation history
# Can import to create local copy for further work
```

### Example 3: Background Code Analysis

Run analysis while continuing work:

```bash
# In the TUI, press Ctrl+B
# Select "code-review" agent
# Agent analyzes code in background
# Continue working in active session

# Monitor progress
# Press Ctrl+Shift+B
# View agent status and output
# Agent completes and shows results
```

### Example 4: Session Export for Backup

Export a session for backup:

```bash
# In the TUI, press Ctrl+E
# Enter filename: "project-backup.json"
# Session exported with all context and history
# Can be restored later or shared with team
```

## Troubleshooting

### Issue: Session not saving

**Solution**: Check that the storage directory exists and is writable:

```bash
# Verify storage directory
ls -la ~/.ricecoder/sessions

# Check permissions
chmod 755 ~/.ricecoder/sessions
```

### Issue: Session limit reached

**Solution**: Close or archive a session before creating a new one:

```bash
# In the TUI, press Ctrl+W to close the active session
# Or press Ctrl+A to archive the active session
# Then create a new session with Ctrl+N
```

### Issue: Shared session link expired

**Solution**: Generate a new share link with a longer expiration:

```bash
# In the TUI, press Ctrl+Shift+S
# Set expiration to a longer duration
# Copy the new link
```

### Issue: Background agent not completing

**Solution**: Check agent status and logs:

```bash
# In the TUI, press Ctrl+Shift+B
# Select the agent
# View status and error messages
# Cancel if needed with C key
```

### Issue: Session context not persisting

**Solution**: Ensure context is saved before closing the session:

```bash
# In the TUI, verify context is set
# Press Ctrl+Shift+C to view context
# Make changes if needed
# Session auto-saves context
```

## Performance

- **Session Creation**: < 100ms
- **Session Switching**: < 50ms
- **Message Routing**: < 10ms per message
- **Session Persistence**: < 500ms for typical session
- **Background Agent Execution**: Non-blocking, runs in separate thread

## Limitations

- Maximum 5 concurrent sessions by default (configurable)
- Session history limited to 1000 messages by default (configurable)
- Shared session links expire after 24 hours by default (configurable)
- Background agents run sequentially, not in parallel
- Session export includes only JSON format

## See Also

- [Multi-Agent Framework](./Multi-Agent-Framework.md) - Agent execution and composition
- [TUI Interface](./TUI-Interface.md) - Terminal user interface guide
- [Configuration](./Configuration.md) - RiceCoder configuration
- [Architecture Overview](./Architecture-Overview.md) - System architecture
- [Contributing Guide](./Contributing.md) - How to contribute

---

*Last updated: December 4, 2025*