User Guide

User Guide

Status: ✅ Complete

Last Updated: December 5, 2025

---

Overview

This comprehensive user guide covers everything you need to know to use RiceCoder effectively. Whether you're a beginner or experienced developer, you'll find practical guidance and examples.

Table of Contents

• Getting Started
• Basic Usage
• Advanced Features
• Workflows
• Best Practices
• Tips and Tricks
• Troubleshooting

---

Getting Started

Installation

See Installation & Setup for detailed installation instructions for your platform.

Quick install:

cargo install ricecoder

Initial Setup

1. Initialize your project:

   rice init

2. Configure your AI provider:

   rice config set provider openai
   rice config set model gpt-4
   rice config set api-key YOUR_API_KEY

3. Start chatting:

   rice chat

First Steps

1. Ask a question:

   r[ > What does this code do?
   

2. Generate code:

   r[ > Generate a Rust function that validates email addresses
   

3. Review code:

   r[ > Review this code for security issues
   

---

Basic Usage

Interactive Chat

Start an interactive chat session:

rice chat

Navigation:

• Arrow Keys: Scroll through messages
• Page Up/Down: Scroll faster
• Tab: Switch between input and message area
• Enter: Send message
• Ctrl+C: Exit chat

Chat Modes:

• Code Mode (default): Focus on code generation and implementation
• Ask Mode: Focus on questions and explanations
• Vibe Mode: Creative and exploratory mode
• Think More: Extended reasoning mode

Switch modes:

rice chat --mode ask
rice chat --mode vibe
rice chat --mode think-more

Code Generation

Generate code from a specification:

# Create a specification
rice spec create my-feature

# Edit the specification files
# .agent/specs/my-feature/requirements.md
# .agent/specs/my-feature/design.md
# .agent/specs/my-feature/tasks.md

# Generate code
rice gen --spec my-feature

# Preview changes
rice gen --spec my-feature --preview

# Auto-approve changes
rice gen --spec my-feature --auto-approve

Code Review

Get AI-powered code reviews:

# Review a file
rice review src/main.rs

# Review with focus
rice review src/main.rs --focus security
rice review src/main.rs --focus performance

# Get detailed review
rice review src/main.rs --detailed

Configuration

Manage your configuration:

# Show current configuration
rice config show

# Set a value
rice config set provider openai
rice config set model gpt-4

# Get a specific value
rice config get provider.name

# Reset to defaults
rice config reset

# Validate configuration
rice config validate

---

Advanced Features

Spec-Driven Development

RiceCoder supports spec-driven development for systematic, repeatable development:

1. Write Requirements:

   # .agent/specs/my-feature/requirements.md
   
   ## Requirement 1
   
   **User Story**: As a user, I want to...
   
   ### Acceptance Criteria
   
   1. WHEN ... THEN ...
   2. WHILE ... THEN ...

2. Design Solution:

   # .agent/specs/my-feature/design.md
   
   ## Architecture
   
   [Design details]
   
   ## Data Models
   
   [Data model definitions]

3. Plan Implementation:

   # .agent/specs/my-feature/tasks.md
   
   - [ ] 1. Implement core logic
   - [ ] 2. Add tests
   - [ ] 3. Update documentation

4. Generate Code:

   rice gen --spec my-feature

See Spec-Driven Development Guide for detailed instructions.

Sessions

Save and resume your work:

# List sessions
rice session list

# Save current session
rice session save my-session

# Load a session
rice session load my-session

# Delete a session
rice session delete my-session

# Clean up old sessions
rice session cleanup --older-than 30d

LSP Integration

Enable Language Server Protocol for IDE integration:

# Start LSP server
rice lsp start

# Check status
rice lsp status

# View logs
rice lsp logs

# Stop LSP server
rice lsp stop

Configure LSP servers:

# .agent/config.yaml
lsp:
  enabled: true
  servers:
    rust: "rust-analyzer"
    typescript: "typescript-language-server"
    python: "pylsp"

Code Completion

Enable context-aware code completion:

# Enable completion
rice completion enable

# Check status
rice completion status

# Configure completion
rice config set completion.context_lines 50
rice config set completion.max_suggestions 10

Hooks

Automate tasks with event-driven hooks:

# List hooks
rice hooks list

# Enable a hook
rice hooks enable on-file-save

# Disable a hook
rice hooks disable on-file-save

# Test a hook
rice hooks test on-file-save

# View hook logs
rice hooks logs

Configure hooks:

# .agent/config.yaml
hooks:
  - name: "on-file-save"
    event: "file_saved"
    action: "run_command"
    command: "cargo test"
    enabled: true

---

Workflows

Typical Development Workflow

1. Start a session:

   rice chat --session my-project

2. Ask questions about your project:

   r[ > What's the structure of this project?
   r[ > How does the authentication work?
   

3. Create a specification for a new feature:

   rice spec create new-feature

4. Generate code from the specification:

   rice gen --spec new-feature --preview

5. Review the generated code:

   rice review src/new_feature.rs --focus quality

6. Save your session:

   rice session save my-project

Code Review Workflow

1. Review a file:

   rice review src/main.rs --detailed

2. Get specific feedback:

   rice review src/main.rs --focus security
   rice review src/main.rs --focus performance

3. Ask follow-up questions:

   rice chat
   r[ > How can I improve the error handling?

4. Generate improved code:

   rice gen --spec improvements --preview

Refactoring Workflow

1. Analyze current code:

   rice chat
   r[ > What parts of this code could be refactored?

2. Create refactoring specification:

   rice spec create refactoring

3. Generate refactored code:

   rice gen --spec refactoring --preview

4. Review changes:

   rice review src/refactored.rs

---

Best Practices

Writing Good Specifications

1. Be Clear and Specific:

   • Use concrete examples
   • Define acceptance criteria
   • Specify constraints and requirements

2. Include Context:

   • Explain the problem
   • Describe the desired outcome
   • Provide relevant background

3. Use Proper Format:

   • Follow EARS pattern for requirements
   • Use YAML or Markdown
   • Include examples

Effective Code Generation

1. Provide Good Context:

   • Include relevant code snippets
   • Explain your project structure
   • Describe your coding style

2. Review Generated Code:

   • Always review before applying
   • Check for correctness
   • Verify it matches your style

3. Iterate and Refine:

   • Ask follow-up questions
   • Request improvements
   • Regenerate if needed

Using AI Providers Effectively

1. Choose the Right Provider:

   • OpenAI/Anthropic: Best quality, cloud-based
   • Ollama: Local, private, offline-capable

2. Select Appropriate Models:

   • GPT-4: Best quality, slower, more expensive
   • GPT-3.5-Turbo: Good quality, faster, cheaper
   • Claude 3 Opus: Excellent quality, good reasoning
   • Local models: Fast, private, free

3. Manage Costs:

   • Use local models for development
   • Use cloud models for complex tasks
   • Monitor API usage

Session Management

1. Organize Sessions:

   • Use descriptive session names
   • Save sessions for important work
   • Clean up old sessions regularly

2. Preserve Context:

   • Keep related conversations together
   • Reference previous sessions
   • Build on past work

---

Tips and Tricks

Keyboard Shortcuts

Shortcut	Action
Ctrl+C	Exit chat
Ctrl+L	Clear screen
Tab	Switch between input and messages
Arrow Up/Down	Scroll messages
Page Up/Down	Scroll faster
Enter	Send message

Useful Commands

# Get help
rice --help
rice chat --help
rice gen --help

# Show version
rice --version

# Show system info
rice info --system

# Show logs
rice info --logs

# Validate configuration
rice config validate

# Show configuration
rice config show

Performance Tips

1. Use Local Models:

   rice config set provider ollama
   rice config set model mistral

2. Reduce Context Size:

   rice config set completion.context_lines 30

3. Enable Caching:

   rice config set cache.enabled true

Customization

1. Custom Commands:

   # .agent/config.yaml
   commands:
     - name: "test"
       command: "cargo test"
       description: "Run tests"

2. Custom Hooks:

   # .agent/config.yaml
   hooks:
     - name: "on-save"
       event: "file_saved"
       action: "run_command"
       command: "cargo fmt"

3. Custom Configuration:

   # .agent/config.yaml
   ricecoder:
     provider: "openai"
     model: "gpt-4"
     timeout_ms: 30000

---

Troubleshooting

Common Issues

Issue: API key not recognized

• Solution: Check configuration: rice config show
• Solution: Regenerate API key from provider's dashboard

Issue: Chat not responding

• Solution: Check network connection
• Solution: Verify API provider is online
• Solution: Check API quota

Issue: Code generation produces errors

• Solution: Review specification for clarity
• Solution: Provide more context
• Solution: Try a different model

Issue: Performance is slow

• Solution: Use local models (Ollama)
• Solution: Reduce context size
• Solution: Close other applications

See Troubleshooting Guide for more detailed help.

Getting Help

• Documentation: RiceCoder Wiki
• FAQ: Frequently Asked Questions
• Troubleshooting: Troubleshooting Guide
• GitHub Issues: Report bugs
• GitHub Discussions: Ask questions

---

See Also

• Quick Start Guide - Get started in 5 minutes
• Installation & Setup - Installation instructions
• Configuration Guide - Configuration options
• CLI Commands Reference - All available commands
• Spec-Driven Development Guide - Master specs
• FAQ - Frequently asked questions
• Troubleshooting Guide - Solve common problems

---

Last updated: December 5, 2025