Claude Code for Neovim 🚀

A comprehensive Neovim plugin that transforms your coding experience with Claude AI's advanced capabilities. Get intelligent code suggestions, automated debugging, security analysis, test generation, and sophisticated refactoring—all seamlessly integrated into your Neovim workflow.

🎯 Competitive with Cursor AI - Featuring agentic workflows, multi-file editing, background processing, and advanced context understanding.

✨ Features

🔧 Code Writing & Generation

🎯 Smart Code Completion - Context-aware completions with deep codebase understanding
⚡ Function Generation - Create complete functions from natural language descriptions
📝 TODO Implementation - Automatically implement TODO comments with proper code
💡 Code Explanation - Get detailed explanations of complex code structures
🧬 Multi-file Context - Generate code that understands your entire project structure

🐛 Advanced Debugging & Analysis

🔍 Error Analysis - Deep error message analysis with intelligent explanations
🎯 Fix Suggestions - Get specific, actionable solutions for code issues
📊 Stack Trace Analysis - Comprehensive stack trace interpretation with root cause detection
🔧 Performance Debugging - Identify bottlenecks and optimization opportunities
⚠️ Security Vulnerability Scanning - OWASP Top 10 and security best practice checks

📋 Intelligent Code Review

🛡️ Security Analysis - Identify vulnerabilities with severity levels and fixes
⚡ Performance Review - Algorithm complexity and optimization suggestions
🏗️ Architecture Analysis - Design patterns and structural improvements
📏 Code Quality - Maintainability, readability, and best practice compliance
🔄 Dependency Analysis - Import/export relationship understanding

🧪 Smart Testing & Quality

🎯 Test Generation - Comprehensive unit tests with edge cases and assertions
🎭 Mock Objects - Generate appropriate mocks with configurable behaviors
📊 Coverage Analysis - Identify untested code paths and suggest test cases
🔗 Integration Tests - Support for end-to-end test scaffolding
🚀 Performance Tests - Generate benchmarking and load test scenarios

♻️ Advanced Refactoring

🔄 Extract Methods/Classes - Smart extraction with meaningful naming
⚡ Algorithm Optimization - Performance improvements and complexity reduction
📝 Intelligent Renaming - Context-aware variable and function renaming
🏗️ Architecture Refactoring - Dependency injection and design pattern application
🎨 Code Style Improvements - Language-specific conventions and formatting

🤖 Agentic Workflows (Cursor-like)

👥 Multi-Agent Support - Run multiple AI tasks concurrently
📋 Plan Mode - Generate and execute structured development plans
⏰ Background Agents - Long-running tasks with progress tracking
🔄 Task Queue Management - Prioritize and manage AI operations
🧠 Agent Communication - Context sharing between different AI agents

💬 Interactive Chat Panel

🎯 Persistent Sidebar - Cursor-style chat panel that stays open
📁 File Context Awareness - Automatically includes current file context
💾 Chat History - Persistent conversation history with threading
⌨️ Quick Toggle - Simple keymap to show/hide panel
🔄 Live Context Updates - Context updates automatically when switching files

🚀 Quick Start

Install the plugin using your favorite package manager
Set your API key: export ANTHROPIC_API_KEY="your-key"
Configure the plugin: require('claude-code').setup({})
Start coding with AI assistance!

-- Minimal setup
require('claude-code').setup({
  api = { key = vim.env.ANTHROPIC_API_KEY }
})

📦 Installation

Prerequisites

Neovim 0.8.0+ (0.9.0+ recommended)
Anthropic API key or Claude CLI installed
curl for API requests
Git for installation

Using lazy.nvim ⭐ Recommended

{
  'username/claude-code.nvim',
  event = "VeryLazy", -- Load on demand for better startup time
  dependencies = {
    "nvim-lua/plenary.nvim", -- Required for async operations
  },
  config = function()
    require('claude-code').setup({
      api = {
        key = vim.env.ANTHROPIC_API_KEY, -- Secure: use environment variable
        model = "claude-3-5-sonnet-20241022", -- Latest model
      },
      features = {
        completion = { enabled = true },
        code_review = { enabled = true },
        debugging = { enabled = true },
      }
    })
  end,
}

Using packer.nvim

use {
  'claude-code.nvim',
  config = function()
    require('claude-code').setup({
      api = {
        key = vim.env.ANTHROPIC_API_KEY,
      }
    })
  end
}

Using vim-plug

Plug 'claude-code.nvim'

Then in your init.lua:

require('claude-code').setup({
  api = {
    key = vim.env.ANTHROPIC_API_KEY,
  }
})

🔧 Configuration

API Setup

Getting Your Anthropic API Key

Sign up at Anthropic Console
Navigate to API Keys section
Create a new API key
Copy your key (starts with sk-ant-api03-...)

Set Your API Key (Recommended - Environment Variable)

# Add to your ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Reload your shell
source ~/.zshrc

Or Configure Directly in Setup

require('claude-code').setup({
  api = {
    key = "sk-ant-api03-your-key-here", -- Your actual API key
    model = "claude-3-5-sonnet-20241022", -- Latest Claude 3.5 Sonnet
    max_tokens = 8192, -- Maximum tokens (Claude 3.5 limit)
    temperature = 0.1, -- Lower for more deterministic code generation
    base_url = "https://api.anthropic.com/v1", -- Anthropic API endpoint
  }
})

Supported Models (as of Feb 2026)

Model	ID	Context Window	Best For
Claude 3.5 Sonnet	`claude-3-5-sonnet-20241022`	200K tokens	Recommended - Best balance of intelligence and speed
Claude 3.5 Haiku	`claude-3-5-haiku-20241022`	200K tokens	Fastest responses, good for simple tasks
Claude 3 Opus	`claude-3-opus-20240229`	200K tokens	Most capable, best for complex reasoning

💡 Tip: Claude 3.5 Sonnet is recommended for most coding tasks as it provides excellent code quality with fast response times.

Feature Configuration

require('claude-code').setup({
  features = {
    completion = {
      enabled = true,
      trigger_length = 2,
      max_context_lines = 100,
      debounce_ms = 500,
    },
    code_writing = {
      enabled = true,
      include_type_hints = true,
      include_docstrings = true,
      include_error_handling = true,
    },
    debugging = {
      enabled = true,
      explain_errors = true,
      suggest_fixes = true,
      analyze_stack_trace = true,
    },
    code_review = {
      enabled = true,
      check_security = true,
      check_performance = true,
      check_maintainability = true,
      max_file_size = 10000, -- lines
    },
    testing = {
      enabled = true,
      generate_edge_cases = true,
      include_mocks = true,
    },
    refactoring = {
      enabled = true,
      extract_methods = true,
      optimize_algorithms = true,
      improve_naming = true,
    },
  },
  
  -- Chat panel configuration
  chat_panel = {
    enabled = true,
    width = 50,              -- Panel width in columns
    position = "right",      -- "left" or "right"
    auto_close = false,      -- Auto-close after sending
    show_context_info = true, -- Show file context
    max_history = 50,        -- Max chat history entries
    keymaps = {
      toggle = "<leader>cp",        -- Toggle panel
      send = "<CR>",              -- Send message
      cancel = "<Esc>",           -- Cancel input
      clear_history = "<leader>cc", -- Clear history
    },
  }
})

UI Customization

require('claude-code').setup({
  ui = {
    float_border = "rounded", -- "none", "single", "double", "rounded", "solid", "shadow"
    float_width = 0.8,
    float_height = 0.6,
    progress_indicator = true,
    syntax_highlighting = true,
  }
})

Custom Keybindings

require('claude-code').setup({
  keymaps = {
    commands = {
      -- Code writing
      write_function = "<leader>cf",
      implement_todo = "<leader>ci",
      explain_code = "<leader>ce",
      
      -- Debugging
      debug_error = "<leader>cd",
      analyze_stack = "<leader>cs",
      suggest_fix = "<leader>cx",
      
      -- Code review
      review_code = "<leader>cr",
      review_file = "<leader>cR",
      security_check = "<leader>cS",
      
      -- Testing
      generate_tests = "<leader>ct",
      generate_mocks = "<leader>cm",
      
      -- Refactoring
      refactor_extract = "<leader>re",
      refactor_optimize = "<leader>ro",
      
      -- General
      claude_chat = "<leader>cc",
      claude_help = "<leader>ch",
    },
  }
})

🚀 Usage

Code Writing Commands

Command	Description	Keybinding
`:ClaudeWriteFunction`	Generate function from description	`<leader>cw`
`:ClaudeImplementTodo`	Implement TODO comment	`<leader>ci`
`:ClaudeExplainCode`	Explain selected code	`<leader>ce`

Debugging Commands

Command	Description	Keybinding
`:ClaudeDebugError`	Debug error message	`<leader>cd`
`:ClaudeAnalyzeStack`	Analyze stack trace	`<leader>cs`
`:ClaudeSuggestFix`	Suggest fix for code issue	`<leader>cf`

Code Review Commands

Command	Description	Keybinding
`:ClaudeReviewCode`	Review selected code	`<leader>cr`
`:ClaudeReviewFile`	Review entire file	`<leader>cR`
`:ClaudeSecurityCheck`	Security vulnerability check	`<leader>cS`

Testing Commands

Command	Description	Keybinding
`:ClaudeGenerateTests`	Generate tests for selected code	`<leader>ct`
`:ClaudeGenerateMocks`	Generate mock objects	`<leader>cm`
`:ClaudeTestCoverage`	Test coverage analysis	`<leader>cC`

Refactoring Commands

Command	Description	Keybinding
`:ClaudeRefactorExtract`	Extract method/class	`<leader>re`
`:ClaudeRefactorOptimize`	Optimize code	`<leader>ro`
`:ClaudeRefactorRename`	Intelligent rename suggestions	`<leader>rn`

Chat Panel Commands

Command	Description	Keybinding
`:ClaudeChatPanel`	Toggle persistent chat panel	`<leader>cp`
`:ClaudeClearHistory`	Clear chat panel history	-

General Commands

Command	Description	Keybinding
`:ClaudeChat`	Open Claude Code chat	`<leader>cc`
`:ClaudeHelp`	Show help	`<leader>ch`
`:ClaudeStatus`	Show plugin status	-
`:ClaudeToggleCompletion`	Toggle code completion	-

📝 Examples

Generate a Function

Use :ClaudeWriteFunction or <leader>cw
Describe what you want: "Create a binary search function that takes a sorted array and target value"
Claude Code will generate a complete, well-documented function with error handling

Implement TODO

Place cursor on or near a TODO comment:

# TODO: Add input validation for email addresses

Use :ClaudeImplementTodo or <leader>ci
Claude Code will implement the validation logic

Code Review

Select code or use entire file
Use :ClaudeReviewCode or <leader>cr
Get comprehensive feedback on security, performance, and maintainability

Debug Error

Use :ClaudeDebugError or <leader>cd
Paste your error message
Get detailed analysis and specific solutions

Generate Tests

Select a function or method
Use :ClaudeGenerateTests or <leader>ct
Get comprehensive tests including edge cases

Use Chat Panel (Cursor-style)

Press <leader>cp to toggle the chat panel
Press i, a, or o in the panel to start typing a message
Press <CR> to send your message to Claude
Chat history persists across sessions
File context is automatically included with each message
Press q to close the panel

🎨 UI Features

Floating Windows

Beautiful floating windows with rounded borders
Syntax highlighting for code responses
Easy navigation with q to close, y to copy content

Loading Indicators

Animated loading spinners during AI processing
Progress indicators for long-running operations
Cancellable requests with <Esc>

Code Application

Direct code application with <CR> or a key
Smart code insertion at cursor position
Undo-friendly operations

🔧 Troubleshooting

API Key Issues

# Check if API key is set and valid format
echo $ANTHROPIC_API_KEY
# Should start with: sk-ant-api03-

# Set API key temporarily
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Check plugin status
:ClaudeStatus

# Test API connection
:checkhealth claude_code

Common API Key Problems:

❌ Wrong format: Ensure key starts with sk-ant-api03-
❌ Expired key: Check Anthropic Console for key status
❌ Insufficient credits: Verify your account has available credits
❌ Rate limits: Wait a moment if you're hitting rate limits

Performance Issues

Reduce max_context_lines in completion settings
Increase debounce_ms for completion
Disable features you don't use

Error Messages

Check :ClaudeStatus for configuration issues
Ensure you have curl installed
Verify internet connectivity

🚀 Performance & Best Practices

Optimization Tips

Context Management: Use smaller max_context_lines for faster responses
Feature Toggling: Disable unused features to reduce memory usage
Request Batching: Group related operations together
Caching: Responses are cached automatically for repeated queries

Security Best Practices

# Store API key securely in your shell profile
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"' >> ~/.zshrc

# Or use a secrets manager (recommended for teams)
echo 'export ANTHROPIC_API_KEY=$(pass anthropic/api-key)' >> ~/.zshrc

# Or use macOS Keychain
echo 'export ANTHROPIC_API_KEY=$(security find-generic-password -s "anthropic-api" -w)' >> ~/.zshrc

# For development, use .env files (add to .gitignore!)
echo 'ANTHROPIC_API_KEY=sk-ant-api03-your-key-here' > .env
echo '.env' >> .gitignore

⚠️ Security Reminders:

🚫 Never commit API keys to version control
🔒 Use environment variables instead of hardcoding
🔄 Rotate keys regularly for better security
📋 Monitor usage in Anthropic Console

🆚 Comparison with Cursor AI

Feature	Claude Code Neovim	Cursor AI
Multi-Agent Workflows	✅ Concurrent agents	✅ Up to 8 agents
Plan Mode	✅ Structured dev plans	✅ Editable plans
Background Processing	✅ Long-running tasks	✅ Isolated environments
Context Understanding	✅ Deep codebase analysis	✅ Project-wide context
Security Analysis	✅ OWASP Top 10 + custom	✅ General security
Test Generation	✅ Edge cases + mocks	✅ Basic test generation
Refactoring	✅ Advanced patterns	✅ Basic refactoring
Cost	🆓 Open Source	💰 Paid tiers
Customization	✅ Highly configurable	⚠️ Limited customization
Vim Integration	✅ Native Neovim	❌ VS Code fork only

🧪 Testing & Development

Running Tests

# Install dependencies
make install

# Run tests
make test

# Run with coverage
make test-coverage

# Lint code
make lint

# Format code
make format

Development Setup

# Clone the repository
git clone https://github.com/username/claude-code.nvim.git
cd claude-code.nvim

# Install development dependencies
make install

# Run tests in watch mode
make test-watch

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contributing Steps

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

Areas We Need Help With

🐛 Bug fixes and stability improvements
📚 Documentation and tutorials
🧪 Test coverage expansion
🌐 Internationalization support
⚡ Performance optimizations
🎨 UI/UX improvements

📊 Roadmap

Q1 2026: Multi-modal support (images, voice)
Q2 2026: Local model support (Ollama integration)
Q3 2026: Team collaboration features
Q4 2026: Plugin ecosystem and extensions

🆘 Support & Community

📖 Documentation: Full docs
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
💌 Email: maintainers@example.com

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Anthropic for the amazing Claude AI
Neovim community for the excellent plugin ecosystem
Cursor AI for inspiration on agentic workflows
All contributors who make this project better

⭐ Star us on GitHub if this plugin helps you code better! ⭐

Made with ❤️ by the Claude Code Neovim community

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
lua/claude-code		lua/claude-code
plugin		plugin
tests		tests
.busted		.busted
.editorconfig		.editorconfig
.gitignore		.gitignore
.luacheckrc		.luacheckrc
.stylua.toml		.stylua.toml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MODERN_CHAT_PANEL.md		MODERN_CHAT_PANEL.md
Makefile		Makefile
README.md		README.md
chat_debug_helper.lua		chat_debug_helper.lua
debug_chat_panel.lua		debug_chat_panel.lua
test_chat_panel.lua		test_chat_panel.lua
test_fixes.lua		test_fixes.lua
test_modern_chat.lua		test_modern_chat.lua
test_trim_fix.lua		test_trim_fix.lua

Latest commit

History

Folders and files

Repository files navigation