ricecoder

https://github.com/moabualruz/ricecoder/wiki

---

What is RiceCoder?

RiceCoder (rice) is a terminal-first, spec-driven coding assistant that understands your project before generating code. Unlike other AI coding tools, RiceCoder follows a research-first approach-analyzing your codebase, understanding your patterns, and generating code that fits your project's style.

Key Features

• 🔬 Research-First - Analyzes your project context before generating code
• 📋 Spec-Driven - Systematic, repeatable development from specifications
• 💻 Terminal-Native - Beautiful CLI/TUI that works anywhere
• 🔒 Offline-First - Local models via Ollama for privacy and offline work
• 🤖 Multi-Agent - Specialized agents for different tasks
• 🎨 Multi-Provider - OpenAI, Anthropic, Ollama, and more

---

Installation

Quick Start

Choose your preferred installation method:

Method	Command	Best For
Cargo	cargo install ricecoder	Rust developers, easy updates
Curl	curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash	Quick setup, any platform
Docker	docker pull moabualruz/ricecoder:latest	Isolated environments
npm	npm install -g ricecoder	Node.js developers
Homebrew	brew install ricecoder	macOS users
From Source	git clone ... && ./scripts/install.sh	Development, customization

Installation Methods

1. Cargo (Recommended)

Install from crates.io:

# Install
cargo install ricecoder

# Verify
rice --version

# Update
cargo install --force ricecoder

Requirements: Rust 1.75+ (Install Rust)

Platforms: Linux, macOS, Windows

---

2. Curl Script (Quick Setup)

Build and install from source with a single command:

# Linux/macOS - Standard installation
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash

# With custom prefix
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --prefix /usr/local

# Debug build
curl -fsSL https://raw.githubusercontent.com/moabualruz/ricecoder/main/scripts/install | bash -s -- --debug

# Verify
rice --version

Features:

• Detects OS and architecture automatically
• Builds from source with automatic compilation
• Verifies prerequisites (Rust, Cargo, Git)
• Automatic Rust toolchain update
• Installs to custom prefix or default location
• Automatic installation verification

Platforms: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon)

Troubleshooting: See Installation Troubleshooting

---

3. Docker

Run in a containerized environment:

# Pull image
docker pull moabualruz/ricecoder:latest

# Run
docker run --rm moabualruz/ricecoder:latest --version

# Run with workspace access
docker run -it -v $(pwd):/workspace moabualruz/ricecoder:latest chat

Features:

• Isolated environment
• No system dependencies
• Consistent across platforms
• Easy cleanup

Platforms: Any platform with Docker

Requirements: Docker (Install Docker)

---

4. npm (Node.js Developers)

Install via npm registry:

# Install globally
npm install -g ricecoder

# Verify
rice --version

# Update
npm install -g ricecoder@latest

Features:

• Familiar npm workflow
• Easy version management
• Works with Node.js projects

Platforms: Linux, macOS, Windows

Requirements: Node.js 14+ and npm

---

5. Homebrew (macOS)

Install via Homebrew:

# Install
brew install ricecoder

# Verify
rice --version

# Update
brew upgrade ricecoder

Features:

• Native macOS package manager
• Easy updates and uninstall
• Integrates with system

Platforms: macOS

Requirements: Homebrew (Install Homebrew)

---

6. Build from Source

Clone and build locally with automatic installation:

Using Installation Scripts (Recommended):

# Clone repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Linux/macOS - Automatic installation
chmod +x scripts/install.sh
./scripts/install.sh

# Windows (PowerShell)
.\scripts\install.ps1

# Windows (CMD)
scripts\install.bat

Installation Script Options:

# Linux/macOS
./scripts/install.sh --prefix /usr/local    # Custom prefix
./scripts/install.sh --debug                # Debug build
./scripts/install.sh --verbose              # Verbose output

# Windows (PowerShell)
.\scripts\install.ps1 -Prefix "C:\Program Files\ricecoder"
.\scripts\install.ps1 -Debug

Manual Build and Install:

# Clone repository
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Build and install
cargo install --path projects/ricecoder

# Verify
rice --version

Features:

• Latest development version
• Customizable build (release/debug)
• Full source access
• Automatic prerequisite checking
• Automatic Rust toolchain update
• Automatic PATH configuration

Platforms: Linux, macOS, Windows

Requirements: Rust 1.75+, Git, C compiler

See Also: Installation Guide - Comprehensive build and installation documentation

---

Platform Support Matrix

Platform	Arch	Cargo	Curl	Docker	npm	Homebrew	Source
Linux	x86_64	✅	✅	✅	✅	❌	✅
Linux	ARM64	✅	✅	✅	✅	❌	✅
macOS	Intel	✅	✅	✅	✅	✅	✅
macOS	Apple Silicon	✅	✅	✅	✅	✅	✅
Windows	x86_64	✅	❌	✅	✅	❌	✅
Windows	ARM64	✅	❌	✅	✅	❌	✅

Legend: ✅ Supported | ❌ Not available | ⚠️ Limited support

---

System Requirements

Minimum:

• OS: Linux, macOS, or Windows
• RAM: 512 MB
• Disk: 100 MB

Recommended:

• OS: Linux (Ubuntu 18.04+), macOS (10.13+), Windows 10+
• RAM: 2 GB
• Disk: 500 MB
• Terminal: Modern terminal emulator (iTerm2, Windows Terminal, GNOME Terminal)

For Building from Source:

• Rust 1.75+ (Install Rust)
• Git
• C compiler (gcc, clang, or MSVC)

---

Verification

After installation, verify it works:

# Check version
rice --version

# Show help
rice --help

# Initialize project
rice init

# Test connection (if configured)
rice chat --test

---

Installation Troubleshooting

"Command not found: rice"

Solution:

1. Restart your terminal
2. Check PATH: echo $PATH
3. Verify installation: which rice or where rice (Windows)
4. Reinstall if needed

See Installation Setup Guide for detailed troubleshooting.

---

"Permission denied"

Solution:

1. Check file permissions: ls -la ~/.cargo/bin/rice
2. Fix permissions: chmod +x ~/.cargo/bin/rice
3. Ensure directory is in PATH

---

"Checksum verification failed" (Curl)

Solution:

1. Re-run installation script
2. Check network connection
3. Try alternative installation method

---

"Docker image not found"

Solution:

1. Pull image: docker pull moabualruz/ricecoder:latest
2. Check Docker is running: docker ps
3. Verify internet connection

---

Uninstallation

Remove RiceCoder:

# Cargo
cargo uninstall ricecoder

# npm
npm uninstall -g ricecoder

# Homebrew
brew uninstall ricecoder

# Docker
docker rmi moabualruz/ricecoder:latest

# From source
cd ricecoder && cargo uninstall --path projects/ricecoder

Remove configuration:

# Remove global config
rm -rf ~/.ricecoder/

# Remove project config
rm -rf .agent/

Getting Started

After installation, initialize your first project:

# Initialize project
rice init

# Start interactive chat
rice chat

# Generate code from a spec
rice gen --spec my-feature

# Review code
rice review src/main.rs

For detailed setup instructions, see Installation Setup Guide.

---

Next Steps

1. Quick Start Guide - Your first project (5 minutes)
2. Configuration Guide - Set up AI providers
3. CLI Commands - Learn all commands
4. Spec-Driven Development - Master specs

---

Why RiceCoder?

Feature	RiceCoder	Others
Terminal-native	✅	❌ IDE-focused
Spec-driven development	✅	❌ Ad-hoc
Offline-first (local models)	✅	❌ Cloud-only
Research before coding	✅	❌ Generate immediately
Multi-agent framework	✅	⚠️ Limited

---

Community

Join our community to discuss RiceCoder, ask questions, and share ideas:

• Discord Server - Real-time chat and community support
• GitHub Discussions - Async discussions and Q&A
• GitHub Issues - Bug reports and feature requests

---

Documentation

Complete documentation is available in the RiceCoder Wiki:

Core Guides

• Quick Start Guide - Get started in 5 minutes
• CLI Commands Reference - All available commands
• Configuration Guide - Configure RiceCoder
• TUI Interface Guide - Terminal UI navigation and shortcuts
• AI Providers Guide - Set up OpenAI, Anthropic, Ollama, and more
• Local Models Setup - Use Ollama for offline-first development
• Spec-Driven Development - Systematic development with specs

Phase 2 Features

• Code Generation - Generate code from specs with AI enhancement and validation
• Multi-Agent Framework - Specialized agents for code review, testing, documentation, and refactoring
• Workflows & Execution - Declarative workflows with state management, approval gates, and risk scoring
• Execution Plans - Risk scoring, approval gates, test integration, pause/resume, and rollback
• Sessions - Multi-session support with persistence, sharing, and background agent execution
• Modes - Code/Ask/Vibe modes with Think More extended reasoning
• Conversation Sharing - Share sessions with team members via shareable links with read-only access

Phase 3 Features

• LSP Integration - Language Server Protocol for IDE integration with multi-language semantic analysis
• Code Completion - Context-aware code completion with intelligent ranking and ghost text
• Hooks System - Event-driven automation with hook chaining and configuration

Phase 5 Foundation Features

• Enhanced Tools - Webfetch, Patch, Todo, Web Search with hybrid MCP provider architecture
• Webfetch Tool - Fetch web content with timeout and truncation
• Patch Tool - Apply unified diffs with conflict detection
• Todo Tool - Persistent task management
• Web Search Tool - Search with free APIs or local MCP servers
• Refactoring Engine - Safe refactoring with multi-language support
• Markdown Configuration - Markdown-based configuration system
• Keybind Customization - Custom keybind profiles and management

Phase 6 Infrastructure Features

• Orchestration - Multi-project workspace management with cross-project operations
• Domain-Specific Agents - Specialized agents for frontend, backend, DevOps, data engineering, mobile, and cloud
• Learning System - User interaction tracking and personalized recommendations

Phase 7 Integration Features

• GitHub Integration - GitHub API integration, PR/Issue creation, repository analysis (✅ Complete)
• Conversation Sharing - Share sessions with shareable links and read-only access (✅ Complete)
• Team Collaboration - Team workspaces, shared knowledge base, permissions (✅ Complete)
• IDE Integration - VS Code, JetBrains, Neovim plugins with external LSP-first architecture (✅ Complete)
• Installation Methods - Curl, package managers, Docker, binaries for all platforms (✅ Complete)
• Theme System - Built-in and custom themes with hot-reload support (✅ Complete)
• Image Support - Drag-and-drop images with AI analysis, caching, and terminal display (✅ Complete)

Additional Resources

• FAQ - Frequently asked questions
• Troubleshooting Guide - Common issues and solutions
• Architecture Overview - System design and architecture

---

Development Status

Current Release: Alpha v0.1.7 ✅

Status: Phase 7 complete with all integration features validated and released. GitHub integration, team collaboration, IDE plugins, installation methods, theme system, and image support now available.

Release Strategy

RiceCoder follows a phased release strategy with extended Alpha testing before production release:

• Alpha (v0.1.1) ✅ - Phase 1: Foundation features
• Alpha (v0.1.2) ✅ - Phase 2: Enhanced features
• Alpha (v0.1.3) ✅ - Phase 3: MVP features
• Alpha (v0.1.4) ✅ - Phase 4: Polished and hardened
• Alpha (v0.1.5) ✅ - Phase 5: Foundation features
• Alpha (v0.1.6) ✅ - Phase 6: Infrastructure features
• Alpha (v0.1.7) ✅ - Phase 7: Integration features (current)
• Alpha (v0.1.8) 📋 - Phase 8: Production readiness (planned)

Why Extended Alpha? We're gathering user feedback, identifying edge cases, optimizing performance, and hardening security before the production release.

Phase 1: Alpha Foundation ✅ COMPLETE (v0.1.1)

Status: 11/11 features complete, 500+ tests, 82% coverage, zero clippy warnings

• CLI Foundation - Commands, shell completion, beautiful UX
• AI Providers - OpenAI, Anthropic, Ollama, 75+ providers
• TUI Interface - Terminal UI with themes and syntax highlighting
• Spec System - YAML/Markdown specs with validation
• File Management - Safe writes, git integration, backups
• Templates & Boilerplates - Template engine with substitution
• Research System - Project analysis and context building
• Permissions System - Fine-grained tool access control
• Custom Commands - User-defined shell commands
• Local Models - Ollama integration for offline-first development
• Storage & Config - Multi-level configuration hierarchy

Phase 2: Beta Enhanced Features ✅ COMPLETE (v0.1.2)

Status: 7/7 features complete, 900+ tests, 86% coverage, zero clippy warnings

• Code Generation - Spec-driven code generation with AI enhancement, validation, conflict detection, and rollback
• Multi-Agent Framework - Specialized agents for code review, testing, documentation, and refactoring
• Workflows - Declarative workflow execution with state management, approval gates, and risk scoring
• Execution Plans - Risk scoring, approval gates, test integration, pause/resume, and rollback
• Sessions - Multi-session persistence, sharing, and background agent execution
• Modes - Code/Ask/Vibe modes with Think More extended reasoning
• Conversation Sharing - Share sessions with team members via shareable links with read-only access and permission-based filtering

Timeline: Completed December 8, 2025

Phase 3: Beta MVP Features ✅ COMPLETE (v0.1.3)

Status: 3/3 features complete, 544 tests, 86% coverage, zero clippy warnings

• LSP Integration - Language Server Protocol for IDE integration with multi-language semantic analysis
• Code Completion - Tab completion and ghost text suggestions with context awareness
• Hooks System - Event-driven automation with hook chaining and configuration

Timeline: Completed December 5, 2025

Phase 4: Alpha Validation and Hardening ✅ COMPLETE (v0.1.4)

Status: 7/7 feature areas complete, 1000+ tests, 85%+ coverage, zero clippy warnings

• Performance Optimization - Profiling, caching, memory optimization
• Security Hardening - Security audit, best practices, hardening
• User Experience Polish - Error messages, onboarding, accessibility
• Documentation & Support - Comprehensive docs, guides, support resources
• External LSP Integration - Integration with external LSP servers (rust-analyzer, tsserver, pylsp)
• Final Validation - Comprehensive testing, validation, community feedback
• Alpha Release - v0.1.4 released and available

Timeline: Completed December 5, 2025

Phase 5: Foundation Features ✅ COMPLETE (v0.1.5)

Status: 7/7 features complete, 1100+ tests, 85%+ coverage, zero clippy warnings

• Enhanced Tools - Webfetch, Patch, Todo, Web Search with hybrid MCP provider architecture
• Webfetch Tool - Fetch web content with timeout and truncation
• Patch Tool - Apply unified diffs with conflict detection
• Todo Tools - Persistent task management
• Web Search Tool - Search with free APIs or local MCP servers
• Refactoring System - Safe refactoring with multi-language support
• Markdown Configuration - Markdown-based configuration system
• Keybind Customization - Custom keybind profiles and management

Timeline: Completed December 5, 2025

Phase 6: Infrastructure Features ✅ COMPLETE (v0.1.6)

Status: 3/3 features complete, 1200+ tests, 85%+ coverage, zero clippy warnings

• Orchestration - Multi-project workspace management with cross-project operations
• Domain-Specific Agents - Specialized agents for frontend, backend, DevOps, data engineering, mobile, and cloud
• Learning System - User interaction tracking and personalized recommendations

Timeline: Completed December 6, 2025

Phase 7 (v0.1.7) - Integration Features ✅ COMPLETE

Status: 7/7 features complete, 1300+ tests, 88% coverage, zero clippy warnings

• GitHub Integration - GitHub API integration and PR/Issue creation
• Conversation Sharing - Share sessions with shareable links and read-only access
• Team Collaboration - Team workspaces and shared knowledge base
• IDE Integration - VS Code, JetBrains, Neovim plugins with external LSP-first architecture
• Installation Methods - Curl, package managers, Docker, binaries for all platforms
• Theme System - Built-in and custom themes with hot-reload support
• Image Support - Drag-and-drop images with AI analysis, caching, and terminal display

Timeline: Completed December 9, 2025

Image Support ✅ COMPLETE

RiceCoder now supports drag-and-drop image support with AI analysis, intelligent caching, and terminal display:

Features:

• Drag-and-Drop: Simply drag images into the terminal to include them in your prompts
• Multi-Format Support: PNG, JPG, GIF, and WebP formats
• AI Analysis: Automatic image analysis via your configured AI provider (OpenAI, Anthropic, Ollama, etc.)
• Smart Caching: Cached analysis results with 24-hour TTL and LRU eviction (100 MB limit)
• Terminal Display: Beautiful image rendering in the terminal with ASCII fallback for unsupported terminals
• Automatic Optimization: Large images (>10 MB) are automatically optimized before analysis
• Session Integration: Images are stored in session history for persistence and sharing

Usage:

# Start interactive chat
rice chat

# Drag and drop an image into the terminal
# The image will be analyzed and included in your prompt

# Example: Ask about an image
# "What's in this screenshot?"
# "Analyze this diagram"
# "Review this design mockup"

Configuration:

Image support is configured in projects/ricecoder/config/images.yaml:

images:
  # Supported formats
  formats:
    - png
    - jpg
    - jpeg
    - gif
    - webp
  
  # Display settings
  display:
    max_width: 80          # Max width for terminal display
    max_height: 30         # Max height for terminal display
    placeholder_char: "█"  # ASCII placeholder character
  
  # Cache settings
  cache:
    enabled: true
    ttl_seconds: 86400     # 24 hours
    max_size_mb: 100       # LRU limit
  
  # Analysis settings
  analysis:
    timeout_seconds: 10    # Provider timeout
    max_image_size_mb: 10  # Optimization threshold
    optimize_large_images: true

Performance:

• Drag-and-drop detection: < 100ms
• Format validation: < 500ms
• Image analysis: < 10 seconds
• Cache lookup: < 50ms
• Display rendering: < 200ms

Supported Providers:

• OpenAI (GPT-4 Vision)
• Anthropic (Claude 3 Vision)
• Google (Gemini Vision)
• Ollama (with vision models)
• Zen (with vision support)

See Image Support Guide for detailed documentation.

Production (v1.0.0) 📋 PLANNED

After Phase 7 completion - Production release with all features validated and hardened

See Development Roadmap for details.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

---

License

This project is licensed under CC BY-NC-SA 4.0.

• ✅ Free for personal and non-commercial use
• ✅ Fork, modify, and share
• ❌ Commercial use requires a separate license

---

Acknowledgments

Built with ❤️ using Rust.

Inspired by Aider, OpenCode, and Claude Code.

---