cursor.vim

Cursor AI Integration for Vim and Neovim

Bring the power of Cursor's AI capabilities directly into your Vim or Neovim workflow

Warning

⚠️ ALPHA STATUS

This project is in alpha stage and is actively being developed. You may encounter bugs, breaking changes, and incomplete features. Use at your own risk and please report any issues you find!

Features

🤔 Ask - Get instant answers to coding questions with full context awareness
💬 Chat - Interactive conversational AI assistance with history management
✨ Apply - Seamlessly apply AI-generated code suggestions to your buffers
🎨 Modern UI - Beautiful floating windows and split layouts
⚡ Async - Non-blocking operations that keep your editor responsive
🔧 Configurable - Extensive configuration options and key mappings
🔀 Dual Support - Works with both Vim 9.0+ and Neovim 0.8+

Note: cursor.vim focuses on interactive AI assistance, not inline code completion. Use it alongside GitHub Copilot for the best development experience!

Philosophy

cursor.vim is designed to complement inline completion tools like GitHub Copilot, not replace them.

Use GitHub Copilot for: Real-time code suggestions as you type
Use cursor.vim for: Interactive Q&A, learning, debugging, and applying complex changes

Think of it as having both:

A co-pilot (GitHub Copilot) - suggests code while you fly ✈️
An instructor (cursor.vim) - answers questions and helps you learn 🎓

Feature Comparison

Feature	GitHub Copilot	cursor.vim
Inline code completion	✅	❌
Tab suggestions while typing	✅	❌
Interactive Q&A	❌	✅
Multi-turn conversations	❌	✅
Code explanation	Limited	✅
Apply code with preview	❌	✅
Chat history	❌	✅
Ask about selections	❌	✅
Works with Vim & Neovim	✅	✅

Recommendation: Install both! They work great together and serve different purposes.

Prerequisites

Choose one:

Neovim 0.8+ - Modern Neovim with Lua support
Vim 9.0+ - Modern Vim with job control and popup windows

Both require:

Cursor Agent CLI - Cursor Agent CLI installed and authenticated (cursor-agent command)
Node.js - Required by Cursor Agent CLI

Installation

Using vim-plug

Plug 'johnbrandborg/cursor.vim'

Using lazy.nvim

{
  'johnbrandborg/cursor.vim',
  config = function()
    require('cursor').setup({
      -- your config here (optional)
    })
  end
}

Using packer.nvim

use {
  'johnbrandborg/cursor.vim',
  config = function()
    require('cursor').setup()
  end
}

Manual Installation

# For Neovim
git clone --depth=1 https://github.com/johnbrandborg/cursor.vim.git \
  ~/.config/nvim/pack/cursor/start/cursor.vim

# For Vim
git clone --depth=1 https://github.com/johnbrandborg/cursor.vim.git \
  ~/.vim/pack/cursor/start/cursor.vim

Quick Start

Install the plugin using your preferred method
Install and authenticate with Cursor Agent CLI - the command is cursor-agent
Open Vim or Neovim and run :CursorSetup to verify installation
Start using cursor.vim!

Note: cursor.vim automatically detects your editor (Vim or Neovim) and loads the appropriate implementation.

" Ask a question
:CursorAsk How do I implement a binary search in Python?

" Open chat interface
:CursorChat

" Apply last AI response to buffer
:CursorApply

Configuration

cursor.vim comes with sensible defaults, but you can customize it to your liking.

Neovim Configuration (Lua)

require('cursor').setup({
  -- Path to cursor CLI executable
  cli_path = 'cursor-agent',

  -- Default AI model
  model = 'claude-sonnet-4',

  -- Timeout for CLI operations (milliseconds, 0 to disable)
  timeout = 60000,

  -- UI preferences
  ui = {
    -- Window type: 'float', 'split', 'vsplit'
    window_type = 'float',

    -- Floating window dimensions (percentage)
    float_width = 0.8,
    float_height = 0.8,

    -- Split size (lines/columns)
    split_size = 15,

    -- Border style: 'none', 'single', 'double', 'rounded', 'solid', 'shadow'
    border = 'rounded',
  },

  -- Chat preferences
  chat = {
    -- Save chat history
    save_history = true,

    -- Maximum context messages
    max_context = 20,

    -- History directory
    history_dir = vim.fn.stdpath('data') .. '/cursor_chat_history',
  },

  -- Key mappings (set to false to disable)
  mappings = {
    ask = '<leader>ca',
    chat = '<leader>cc',
    apply = '<leader>cy',
    status = '<leader>cs',
  },

  -- Debug mode
  debug = false,
})

Vim Configuration (Vimscript)

" Set configuration before plugin loads
let g:cursor_config = {
  \ 'cli_path': 'cursor-agent',
  \ 'model': 'claude-sonnet-4',
  \ 'timeout': 60000,
  \ 'ui': {
  \   'window_type': 'float',
  \   'float_width': 0.8,
  \   'float_height': 0.8,
  \   'split_size': 15,
  \   'border': 'rounded',
  \ },
  \ 'chat': {
  \   'save_history': v:true,
  \   'max_context': 20,
  \ },
  \ 'debug': v:false,
  \ }

To disable default key mappings entirely (works for both Vim and Neovim):

let g:cursor_no_default_mappings = 1

Usage

Ask Feature

Ask questions and get AI-powered answers with full context.

" Simple question
:CursorAsk How do I reverse a list in Python?

" Interactive mode (prompts for input)
:CursorAskInteractive
" Or use keymap: <leader>ca

" Ask about visual selection
" 1. Select code in visual mode
" 2. Press <leader>ca or run :CursorAskVisual

" Ask about current buffer
:CursorAskBuffer Explain this code

Chat Feature

Interactive conversational interface with context memory.

" Open chat window
:CursorChat
" Or use keymap: <leader>cc

" In chat window:
" - Type your message and press <Enter> to send
" - Press 'q' to close
" - Use <leader>cc to clear history

" Save chat history
:CursorChatSave my_session.json

" Load chat history
:CursorChatLoad ~/.local/share/nvim/cursor_chat_history/my_session.json

" Clear chat history
:CursorChatClear

" Close chat window
:CursorChatClose

Apply Feature

Apply AI-generated code directly to your buffers.

" Preview code blocks from last response
:CursorPreview

" Apply code from last response
:CursorApply
" Or use keymap: <leader>cy

" You'll be prompted to choose:
" - Replace entire buffer
" - Append to end
" - Insert at cursor

" Apply to new buffer
:CursorApplyNew

Status

Check plugin status and configuration.

:CursorStatus
" Or use keymap: <leader>cs

Commands Reference

Command	Description
`:CursorSetup`	Initialize plugin (called automatically)
`:CursorStatus`	Show plugin status
`:CursorAsk <question>`	Ask a question
`:CursorAskInteractive`	Ask with input prompt
`:CursorAskVisual`	Ask about visual selection
`:CursorAskBuffer`	Ask about current buffer
`:CursorChat`	Open chat interface
`:CursorChatClear`	Clear chat history
`:CursorChatSave [file]`	Save chat session
`:CursorChatLoad <file>`	Load chat session
`:CursorChatClose`	Close chat window
`:CursorApply`	Apply last AI response
`:CursorApplyNew`	Apply to new buffer
`:CursorPreview`	Preview code blocks

Default Key Mappings

Mode	Key	Action
Normal	`<leader>ca`	Ask (interactive)
Visual	`<leader>ca`	Ask about selection
Normal	`<leader>cc`	Open chat
Normal	`<leader>cy`	Apply code
Normal	`<leader>cs`	Show status

Examples

Example 1: Refactor Code

" 1. Select code you want to refactor
" 2. Press <leader>ca (or :CursorAskVisual)
" 3. Type: "Refactor this to use list comprehension"
" 4. Review the response
" 5. Press <leader>cy to apply changes

Example 2: Debug Assistance

" 1. Select buggy code
" 2. :CursorAskVisual Why isn't this working?
" 3. Get detailed explanation
" 4. Ask follow-up questions in :CursorChat

Example 3: Learn New Concepts

:CursorAsk Explain Python decorators with examples
" Review detailed explanation in floating window

Troubleshooting

Cursor CLI Not Found

:CursorStatus
" Check if CLI is detected

" If not, set custom path in config:
require('cursor').setup({
  cli_path = '/path/to/cursor-agent'
})

Authentication Issues

Ensure Cursor Agent CLI is authenticated:

cursor-agent auth login

Timeout Errors

The cursor-agent CLI can take 30-60 seconds to respond. If you get timeout errors (exit code 143), increase the timeout:

require('cursor').setup({
  timeout = 120000  -- 2 minutes for complex queries
})

Or disable timeout entirely (not recommended):

require('cursor').setup({
  timeout = 0  -- No timeout
})

Debug Mode

Enable debug logging:

require('cursor').setup({
  debug = true
})

Architecture

cursor.vim is built with a dual modular architecture supporting both Vim and Neovim:

cursor.vim/
├── plugin/cursor.vim          # Auto-detects Vim/Neovim and loads appropriate implementation
├── lua/cursor/                # Neovim implementation (Lua)
│   ├── init.lua              # Main module
│   ├── config.lua            # Configuration
│   ├── cli.lua               # Cursor CLI interface (libuv)
│   ├── ask.lua               # Ask feature
│   ├── chat.lua              # Chat feature
│   ├── apply.lua             # Code application
│   └── ui.lua                # UI components
└── autoload/cursor/           # Vim implementation (Vimscript)
    ├── init.vim              # Main module
    ├── config.vim            # Configuration
    ├── cli.vim               # Cursor CLI interface (job_start)
    ├── ask.vim               # Ask feature
    ├── chat.vim              # Chat feature
    ├── apply.vim             # Code application
    └── ui.vim                # UI components

Both implementations provide feature parity - all commands and features work identically in Vim and Neovim.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Why Use cursor.vim with GitHub Copilot?

cursor.vim and copilot.vim serve different but complementary purposes:

GitHub Copilot excels at:

Inline code suggestions as you type
Autocomplete for repetitive patterns
Fast, context-aware completions

cursor.vim excels at:

Interactive Q&A and explanations
Multi-turn conversations with context
Debugging and learning
Applying complex code changes with preview
Explicit code generation on demand

Together, they provide:

🚀 Faster coding - Copilot for quick completions
🧠 Better understanding - cursor.vim for learning and debugging
🎯 More control - cursor.vim for explicit, reviewed changes
💪 Complete workflow - Cover all aspects of AI-assisted development

Many developers use both: Copilot for day-to-day completions, and cursor.vim when they need to think through problems or learn new concepts.

Implementation Details

cursor.vim provides two complete implementations:

Feature	Neovim (Lua)	Vim (Vimscript)
Async Operations	`vim.loop` (libuv)	`job_start()`
Floating Windows	`nvim_open_win()`	`popup_create()`
JSON Handling	`vim.json.*`	`json_encode/decode()`
Configuration	Lua tables	Dictionary variables

Both implementations are maintained in parallel and provide identical functionality.

Future Enhancements

License

MIT License - see LICENSE file for details

Acknowledgments

Inspired by copilot.vim
Built for Cursor AI integration
Powered by Neovim

Links

Made with ❤️ for the Vim community

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
autoload/cursor		autoload/cursor
doc		doc
examples		examples
lua/cursor		lua/cursor
plugin		plugin
syntax		syntax
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TESTING.md		TESTING.md
VIM_SUPPORT_SUMMARY.md		VIM_SUPPORT_SUMMARY.md

Latest commit

History

Folders and files

Repository files navigation

cursor.vim

Features

Philosophy

Feature Comparison

Prerequisites

Installation

Using vim-plug

Using lazy.nvim

Using packer.nvim

Manual Installation

Quick Start

Configuration

Neovim Configuration (Lua)

Vim Configuration (Vimscript)

Usage

Ask Feature

Chat Feature

Apply Feature

Status

Commands Reference

Default Key Mappings

Examples

Example 1: Refactor Code

Example 2: Debug Assistance

Example 3: Learn New Concepts

Troubleshooting

Cursor CLI Not Found

Authentication Issues

Timeout Errors

Debug Mode

Architecture

Contributing

Why Use cursor.vim with GitHub Copilot?

Implementation Details

Future Enhancements

License

Acknowledgments

Links

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages