nvim/CURSOR_COMPLETION.md

# Cursor Autocompletion for Neovim

This setup integrates Cursor's AI-powered autocompletion into Neovim using `cursor-agent` CLI and `nvim-cmp`.

## Features

- **AI-powered completions**: Get intelligent code completions powered by Cursor's AI
- **Context-aware**: Uses surrounding code context (last 30 lines) for better suggestions
- **Integrated with nvim-cmp**: Works seamlessly with other completion sources (LSP, snippets, buffer, etc.)
- **Prioritized suggestions**: Cursor completions appear at the top of the completion menu

## Setup

The integration is already configured! Just make sure:

1. **cursor-agent CLI is installed and authenticated**:
   ```bash
   cursor-agent status
   ```
   If not authenticated, run:
   ```bash
   cursor-agent login
   ```

2. **Restart Neovim** to load the new configuration

3. **Install plugins** (if using lazy.nvim, they'll auto-install):
   ```vim
   :Lazy sync
   ```

## Usage

1. **Start typing** in any file
2. **Press `<C-Space>`** to trigger completion manually, or wait for automatic triggers
3. **Look for `[Cursor]`** in the completion menu to see AI suggestions
4. **Navigate** with `<Tab>`/`<S-Tab>` and **accept** with `<Enter>`

## Configuration

### Keybindings

Default keybindings (can be customized in `lua/config/plugin/cmp.lua`):
- `<C-Space>` - Trigger completion
- `<Tab>` - Next completion item / Expand snippet
- `<S-Tab>` - Previous completion item / Jump snippet backward
- `<Enter>` - Confirm completion
- `<C-e>` - Close completion menu

### Adjusting Completion Behavior

Edit `lua/plugins/cmp-cursor.lua` to customize:
- **Context window**: Change `line_num - 30` to adjust how many lines of context are sent
- **Minimum trigger length**: Change `#before_cursor:gsub('%s+', '') < 3` to require more/less context
- **Timeout**: Change `8000` (8 seconds) to adjust how long to wait for completions

### Disabling Cursor Completions

To temporarily disable Cursor completions, comment out the cursor source in `lua/config/plugin/cmp.lua`:

```lua
sources = cmp.config.sources({
  { name = 'nvim_lsp' },
  -- { name = 'cursor', source = cursor_completion_source }, -- Disabled
  { name = 'luasnip' },
}, {
```

## How It Works

1. When you trigger completion, the plugin captures:
   - Current line up to cursor position
   - Last 30 lines of context
   - File content

2. It sends a prompt to `cursor-agent --print` asking for completion suggestions

3. The AI response is parsed and formatted as completion items

4. These appear in the nvim-cmp completion menu with `[Cursor]` label

## Troubleshooting

**No Cursor completions appearing:**
- Check `cursor-agent status` to ensure you're authenticated
- Verify `cursor-agent` is in your PATH: `which cursor-agent`
- Check Neovim messages: `:messages` for any errors

**Completions are slow:**
- This is expected - AI completions take 2-8 seconds
- Consider increasing the minimum trigger length to reduce API calls
- The timeout is set to 8 seconds

**Completions don't make sense:**
- The AI uses context from your file - ensure you have meaningful code before the cursor
- Try typing more context before triggering completion

## Notes

- Cursor completions use API credits from your Cursor account
- Completions are generated on-demand, not cached
- The integration works best with code files (not plain text)
- For best results, ensure your code is syntactically correct before requesting completions