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:

opts = {
  window = {
    position = "right",  -- or "left", "top", "bottom"
    width = 0.4,         -- 40% of screen
  },
}

Auto-reload

When AI edits files, they auto-reload:

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