# VS Code Extension

**Status**: ✅ Complete

**Phase**: Phase 2

**Last Updated**: December 9, 2025

---

## Overview

The RiceCoder VS Code extension provides native integration with VS Code, enabling seamless access to ricecoder's AI-powered features directly in the editor. The extension communicates with ricecoder via JSON-RPC protocol and provides completion, diagnostics, hover information, and definition navigation.

---

## Installation and Setup

### Prerequisites

- VS Code 1.60 or later
- RiceCoder installed and running
- Node.js 14+ (for development)

### Installation

#### From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "RiceCoder"
4. Click Install
5. Reload VS Code

#### From Source

1. Clone the ricecoder repository:
   ```bash
   git clone https://github.com/moabualruz/ricecoder.git
   cd ricecoder/projects/ricecoder/extensions/vscode
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the extension:
   ```bash
   npm run build
   ```

4. Install in VS Code:
   ```bash
   npm run install-extension
   ```

### Configuration

The extension reads configuration from VS Code settings. Open settings (Ctrl+, / Cmd+,) and search for "ricecoder":

```json
{
  "ricecoder.enabled": true,
  "ricecoder.port": 8080,
  "ricecoder.host": "localhost",
  "ricecoder.timeout": 5000,
  "ricecoder.maxResults": 50,
  "ricecoder.features": {
    "completion": true,
    "diagnostics": true,
    "hover": true,
    "definition": true
  }
}
```

---

## Features and Usage

### Code Completion

Intelligent code completion suggestions powered by external LSP servers.

**How to Use**:
- **Automatic**: Completions appear automatically as you type
- **Manual**: Press Ctrl+Space (Cmd+Space on Mac) to trigger completion
- **Select**: Use arrow keys to navigate, Enter to select
- **Dismiss**: Press Escape to dismiss

**Features**:
- Snippet expansion with tab stops
- Type information and documentation
- Sorting by relevance
- Fallback to generic completion if LSP unavailable

**Example**:
```rust
// Type: fn
// Completions appear:
// - fn (keyword)
// - function_name (from LSP)
// - for_each (from LSP)
```

### Diagnostics

Real-time error and warning detection.

**How to Use**:
- Errors and warnings appear inline in the editor
- View all diagnostics in the Problems panel (Ctrl+Shift+M / Cmd+Shift+M)
- Click on diagnostic to navigate to issue
- Hover over diagnostic for details

**Features**:
- Error/warning/info levels
- Quick fixes (when available)
- Inline code actions
- Diagnostic filtering

**Example**:
```rust
let x: i32 = "string";  // Error: mismatched types
                        // Quick fix: Remove type annotation
```

### Hover Information

Symbol information on hover.

**How to Use**:
- Hover over any symbol to see information
- Click on links in hover to navigate
- Press Escape to dismiss

**Features**:
- Type information
- Documentation
- Source location
- Related symbols

**Example**:
```rust
let result = vec![1, 2, 3];
           // Hover shows: Vec<i32>
           // Documentation: A growable array type
```

### Definition Navigation

Navigate to symbol definitions.

**How to Use**:
- **Go to Definition**: F12 or Ctrl+Click
- **Peek Definition**: Ctrl+Shift+F10 or Alt+Click
- **Go to References**: Shift+F12
- **Back**: Alt+Left Arrow

**Features**:
- Jump to definition in same or different file
- Peek definition without leaving current file
- Find all references
- Navigation history

**Example**:
```rust
let x = my_function();  // F12 to jump to my_function definition
```

### Command Palette Integration

Access ricecoder commands from the command palette.

**How to Use**:
- Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
- Type "RiceCoder" to see available commands
- Select command to execute

**Available Commands**:
- `RiceCoder: Start` - Start ricecoder
- `RiceCoder: Stop` - Stop ricecoder
- `RiceCoder: Restart` - Restart ricecoder
- `RiceCoder: Show Status` - Show connection status
- `RiceCoder: Open Settings` - Open ricecoder settings
- `RiceCoder: Run Chat` - Open chat interface
- `RiceCoder: Generate Code` - Generate code
- `RiceCoder: Review Code` - Review current file

---

## Settings

### Basic Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `ricecoder.enabled` | boolean | true | Enable/disable extension |
| `ricecoder.host` | string | localhost | RiceCoder host |
| `ricecoder.port` | number | 8080 | RiceCoder port |
| `ricecoder.timeout` | number | 5000 | Request timeout (ms) |
| `ricecoder.maxResults` | number | 50 | Max completion results |

### Feature Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `ricecoder.features.completion` | boolean | true | Enable code completion |
| `ricecoder.features.diagnostics` | boolean | true | Enable diagnostics |
| `ricecoder.features.hover` | boolean | true | Enable hover info |
| `ricecoder.features.definition` | boolean | true | Enable definition nav |

### Advanced Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `ricecoder.debug` | boolean | false | Enable debug logging |
| `ricecoder.logLevel` | string | info | Log level (debug/info/warn/error) |
| `ricecoder.autoConnect` | boolean | true | Auto-connect on startup |
| `ricecoder.reconnectAttempts` | number | 5 | Max reconnection attempts |
| `ricecoder.reconnectDelay` | number | 1000 | Delay between reconnects (ms) |

### Language-Specific Settings

Configure settings per language:

```json
{
  "[rust]": {
    "ricecoder.features.completion": true,
    "ricecoder.timeout": 10000
  },
  "[typescript]": {
    "ricecoder.features.completion": true,
    "ricecoder.timeout": 5000
  },
  "[python]": {
    "ricecoder.features.completion": true,
    "ricecoder.timeout": 8000
  }
}
```

---

## Keyboard Shortcuts

### Default Shortcuts

| Shortcut | Command | Platform |
|----------|---------|----------|
| Ctrl+Space | Trigger Completion | Windows/Linux |
| Cmd+Space | Trigger Completion | Mac |
| F12 | Go to Definition | All |
| Ctrl+Shift+F10 | Peek Definition | Windows/Linux |
| Cmd+Shift+F10 | Peek Definition | Mac |
| Shift+F12 | Find References | All |
| Ctrl+Shift+M | Show Problems | Windows/Linux |
| Cmd+Shift+M | Show Problems | Mac |

### Custom Shortcuts

To customize shortcuts, open keyboard shortcuts (Ctrl+K Ctrl+S / Cmd+K Cmd+S) and search for "ricecoder":

```json
[
  {
    "key": "ctrl+alt+c",
    "command": "ricecoder.triggerCompletion"
  },
  {
    "key": "ctrl+alt+d",
    "command": "ricecoder.goToDefinition"
  }
]
```

---

## Troubleshooting

### Extension Not Connecting

**Problem**: "Failed to connect to RiceCoder"

**Solutions**:
1. Verify ricecoder is running:
   ```bash
   ricecoder --version
   ricecoder start
   ```

2. Check port configuration:
   - Default port is 8080
   - Verify port is not in use: `netstat -an | grep 8080`
   - Change port in settings if needed

3. Check firewall:
   - Ensure firewall allows localhost connections
   - Try connecting from terminal: `curl http://localhost:8080/health`

4. Check extension logs:
   - Open Output panel (Ctrl+Shift+U / Cmd+Shift+U)
   - Select "RiceCoder" from dropdown
   - Look for error messages

5. Restart extension:
   - Reload VS Code (Ctrl+Shift+P, "Reload Window")
   - Or restart VS Code completely

### Completions Not Appearing

**Problem**: Code completions are not showing

**Solutions**:
1. Verify completion is enabled:
   - Check `ricecoder.features.completion` is true
   - Check `ricecoder.enabled` is true

2. Check LSP server:
   - Verify LSP server is running for your language
   - Check ricecoder logs for LSP errors

3. Try manual trigger:
   - Press Ctrl+Space to manually trigger completion
   - If manual works, automatic trigger may be disabled

4. Check file type:
   - Ensure file has correct language mode
   - Click language indicator (bottom right) to change

5. Increase timeout:
   - LSP server may be slow
   - Increase `ricecoder.timeout` in settings

### Diagnostics Not Showing

**Problem**: Errors and warnings are not displayed

**Solutions**:
1. Verify diagnostics are enabled:
   - Check `ricecoder.features.diagnostics` is true
   - Check `ricecoder.enabled` is true

2. Check Problems panel:
   - Open Problems panel (Ctrl+Shift+M / Cmd+Shift+M)
   - Look for diagnostics there

3. Check file type:
   - Ensure file has correct language mode
   - Diagnostics may not be available for all languages

4. Check LSP server:
   - Verify LSP server is running
   - Check ricecoder logs for errors

5. Disable and re-enable:
   - Set `ricecoder.enabled` to false
   - Set `ricecoder.enabled` to true
   - Reload window

### Hover Information Not Working

**Problem**: Hover tooltips are not appearing

**Solutions**:
1. Verify hover is enabled:
   - Check `ricecoder.features.hover` is true
   - Check `ricecoder.enabled` is true

2. Try hovering on different symbols:
   - Some symbols may not have hover info
   - Try hovering on function names, variables, types

3. Check LSP server:
   - Verify LSP server is running
   - Check ricecoder logs for errors

4. Increase timeout:
   - Hover may be timing out
   - Increase `ricecoder.timeout` in settings

### Definition Navigation Not Working

**Problem**: "Go to Definition" is not working

**Solutions**:
1. Verify definition navigation is enabled:
   - Check `ricecoder.features.definition` is true
   - Check `ricecoder.enabled` is true

2. Try different symbols:
   - Some symbols may not have definitions
   - Try on function names, class names, variable declarations

3. Check LSP server:
   - Verify LSP server is running
   - Check ricecoder logs for errors

4. Use Find References instead:
   - Shift+F12 to find all references
   - May help locate definition

### Performance Issues

**Problem**: Completions or diagnostics are slow

**Solutions**:
1. Check system resources:
   - Monitor CPU and memory usage
   - Close other applications if needed

2. Increase timeout:
   - LSP server may be slow
   - Increase `ricecoder.timeout` in settings

3. Reduce max results:
   - Decrease `ricecoder.maxResults` in settings
   - Fewer results = faster processing

4. Check LSP server:
   - LSP server may be overloaded
   - Try restarting ricecoder

5. Disable unused features:
   - Disable features you don't use
   - Reduces processing overhead

### Extension Crashes

**Problem**: Extension crashes or becomes unresponsive

**Solutions**:
1. Check extension logs:
   - Open Output panel (Ctrl+Shift+U / Cmd+Shift+U)
   - Select "RiceCoder" from dropdown
   - Look for error messages

2. Disable and re-enable:
   - Disable extension in Extensions panel
   - Reload VS Code
   - Re-enable extension

3. Reinstall extension:
   - Uninstall extension
   - Reload VS Code
   - Reinstall extension

4. Check for updates:
   - Update VS Code to latest version
   - Update extension to latest version

5. Report issue:
   - If problem persists, report on GitHub
   - Include logs and reproduction steps

---

## Advanced Usage

### Debugging

Enable debug logging to troubleshoot issues:

```json
{
  "ricecoder.debug": true,
  "ricecoder.logLevel": "debug"
}
```

Then check Output panel (Ctrl+Shift+U / Cmd+Shift+U) for detailed logs.

### Custom Configuration

Create a `.ricecoder/vscode-settings.json` file in your project:

```json
{
  "features": {
    "completion": true,
    "diagnostics": true,
    "hover": true,
    "definition": true
  },
  "timeout": 5000,
  "maxResults": 50,
  "languages": {
    "rust": {
      "timeout": 10000
    },
    "typescript": {
      "timeout": 5000
    }
  }
}
```

### Workspace Settings

Configure settings per workspace in `.vscode/settings.json`:

```json
{
  "ricecoder.enabled": true,
  "ricecoder.port": 8080,
  "ricecoder.features": {
    "completion": true,
    "diagnostics": true,
    "hover": true,
    "definition": true
  }
}
```

---

## Performance Tips

### Optimize Completion Performance

1. Reduce max results:
   ```json
   {
     "ricecoder.maxResults": 25
   }
   ```

2. Increase timeout for slow LSP servers:
   ```json
   {
     "ricecoder.timeout": 10000
   }
   ```

3. Disable unused features:
   ```json
   {
     "ricecoder.features.diagnostics": false
   }
   ```

### Optimize Diagnostics Performance

1. Disable real-time diagnostics:
   - Diagnostics will only run on save

2. Increase diagnostic delay:
   - Diagnostics will run less frequently

3. Disable for large files:
   - Diagnostics can be slow on large files

---

## See Also

- [IDE Integration Guide](./IDE-Integration.md) - General IDE integration documentation
- [Terminal Editor Integration Guide](./Terminal-Editor-Integration.md) - vim/neovim/emacs setup
- [Configuration Guide](./Configuration.md) - Configuration options
- [Troubleshooting Guide](./Troubleshooting.md) - General troubleshooting

---

*Last updated: December 9, 2025*