Skip to content

Sessions

Jump to bottom
Mo Abualruz edited this page Dec 9, 2025 · 2 revisions

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:

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:

# 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:

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

View all sessions:

# 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:

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

Archive a session:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

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:

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:

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:

sessions:
  max_history: 1000  # Keep last 1000 messages

When the limit is reached, oldest messages are archived.

Session Timeout

Configure automatic session timeout:

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

Last updated: December 4, 2025

Clone this wiki locally