nvim/docs/guides/ai-assistant.md

# AI Assistant Guide (opencode.nvim)

This guide covers using opencode.nvim for AI-assisted coding in Neovim.

## Overview

opencode.nvim provides AI assistance directly in Neovim:
- Ask questions about code
- Get explanations
- Generate code and tests
- Refactor and optimize
- Review changes
- Document code

## Quick Start

### Open AI Panel

```
<leader>kk    Toggle opencode panel
```

The panel opens on the right side (40% width).

### Ask a Question

```
<leader>ka    Ask opencode (prompts for input)
```

Or with file context:
```
<leader>kA    Ask about current file
```

## Key Bindings

### General

| Key | Mode | Action |
|-----|------|--------|
| `<leader>kk` | n | Toggle opencode panel |
| `<leader>ka` | n, v | Ask opencode |
| `<leader>kA` | n, v | Ask about current file |
| `<leader>kn` | n | New session |

### Code Understanding

| Key | Mode | Action |
|-----|------|--------|
| `<leader>ke` | n | Explain code near cursor |
| `<leader>kE` | v | Explain selection |

### Code Review

| Key | Mode | Action |
|-----|------|--------|
| `<leader>kr` | n | Review current file |
| `<leader>kg` | n | Review git diff |
| `<leader>kf` | n | Fix diagnostics/errors |
| `<leader>kq` | n | Fix quickfix items |

### Code Generation

| Key | Mode | Action |
|-----|------|--------|
| `<leader>ko` | v | Optimize selection |
| `<leader>kR` | v | Refactor selection |
| `<leader>kd` | v | Document selection |
| `<leader>kt` | v | Generate tests for selection |

### Harpoon Integration

| Key | Mode | Action |
|-----|------|--------|
| `<leader>kh` | n | Ask about harpooned files |
| `<leader>kH` | n | Analyze harpooned files |

## Common Workflows

### Understanding Code

1. Place cursor on complex code
2. `<leader>ke` - Explain code near cursor

Or for larger sections:
1. Select code in visual mode (`V`)
2. `<leader>kE` - Explain selection

### Fixing Bugs

1. See error in diagnostics
2. `<leader>kf` - Ask AI to fix
3. Review suggested fix
4. Apply or modify as needed

### Generating Tests

1. Select function to test (`V` for lines)
2. `<leader>kt` - Generate tests
3. Review generated tests
4. Adjust assertions as needed

### Refactoring

1. Select code to refactor (`V`)
2. `<leader>kR` - Request refactoring
3. Describe what you want (or let AI decide)
4. Review and apply

### Code Review

Before committing:
```
<leader>kg    Review git diff
```

AI will analyze your changes and suggest improvements.

### Documenting Code

1. Select function/class (`V`)
2. `<leader>kd` - Generate documentation
3. Review generated docs
4. Integrate into code

## Working with Multiple Files

### Harpoon Context

Mark related files with harpoon, then ask about them together:

1. Mark files: `<leader>H` on each file
2. `<leader>kh` - Ask about all harpooned files
3. AI has context of all marked files

Example question:
> "How does the user service interact with the database layer?"

### Analyze Architecture

```
<leader>kH    Analyze harpooned files
```

Good for understanding relationships between files.

## Effective Prompting

### Be Specific

Bad: "Fix this code"
Good: "This function throws an error when the array is empty. Add a guard clause."

### Provide Context

Bad: "Add error handling"
Good: "Add try-catch with proper error logging following our project's error handling pattern"

### Ask for Explanations

- "Explain why this regex works"
- "What are the edge cases here?"
- "Why might this be slow?"

### Request Alternatives

- "Show me 3 ways to implement this"
- "What's a more functional approach?"
- "How would you do this idiomatically in Go?"

## Session Management

### New Session

```
<leader>kn    Start fresh session
```

Clears context for a new topic.

### Continuing Conversations

The panel maintains conversation history. Follow up naturally:
1. Ask initial question
2. "Can you also handle the null case?"
3. "Now add tests for this"

## Integration with Workflow

### During Development

1. Write initial implementation
2. `<leader>ke` - Understand any complex parts
3. `<leader>kt` - Generate tests
4. `<leader>ko` - Optimize if needed

### During Code Review

1. `<leader>gd` - Open diffview
2. `<leader>kg` - AI review of changes
3. Address suggestions
4. Create PR

### While Debugging

1. Hit an error
2. `<leader>kf` - Ask AI to fix
3. Or `<leader>ke` - Understand the error first
4. Apply fix

## Tips

### Quick Explanations

`K` (hover) shows LSP docs, but for deeper understanding:
```
<leader>ke    AI explanation with context
```

### Iterative Refinement

1. Get initial suggestion
2. "Make it more concise"
3. "Add error handling"
4. "Use async/await instead"

### Learning Patterns

Ask AI to explain patterns:
- "Explain the repository pattern used here"
- "What design pattern would improve this?"
- "Show me the idiomatic way in this language"

### Code Generation Templates

For repetitive tasks:
1. `<leader>ka`
2. "Generate a CRUD API endpoint for User model following the pattern in user.controller.ts"

## Customization

### Panel Position

Configured in `lua/plugins/opencode.lua`:
```lua
opts = {
  window = {
    position = "right",  -- or "left", "top", "bottom"
    width = 0.4,         -- 40% of screen
  },
}
```

### Auto-reload

When AI edits files, they auto-reload:
```lua
auto_reload_buffers_on_edit = true,
```

## Troubleshooting

### Panel Not Opening

1. Check opencode is installed: `:Lazy`
2. Verify configuration in `lua/plugins/opencode.lua`

### Slow Responses

- Large files take longer
- Consider selecting specific sections instead of whole files

### Context Issues

If AI seems confused:
1. `<leader>kn` - New session
2. Provide clearer context
3. Select specific code rather than asking about whole file

### Not Understanding Codebase

Use harpoon to provide multi-file context:
1. Mark relevant files
2. `<leader>kh` - Include them in question