claude-code.nvim

A seamless Neovim integration for Claude Code CLI that provides AI-assisted coding workflows with diff preview capabilities, similar to Cursor and Windsurf IDE integrations.

✨ Features

• 🔗 Tmux Integration: Automatically detects and communicates with Claude Code running in tmux panes
• 📁 File Sending: Send current file or visual selections to Claude for analysis
• 🔍 Diff Preview: View proposed changes in a side-by-side diff using diffview.nvim
• ✅ Change Management: Accept or reject Claude's proposed changes directly from Neovim
• ⌨️ Which-key Integration: Organized keybindings with <leader>a prefix for AI assistance
• 🎯 Smart Detection: Auto-detects Claude Code panes by process name and command
• 📋 Project Awareness: Context-aware suggestions for different project types

📦 Installation

Using lazy.nvim

{
  "yourusername/claude-code.nvim",
  dependencies = {
    "sindrets/diffview.nvim", -- For diff visualization
    "folke/which-key.nvim",   -- Optional: for organized keybindings
  },
  config = function()
    require("claude-code").setup({
      -- Configuration options (see Configuration section)
    })
  end,
  keys = {
    { "<leader>af", "<cmd>ClaudeCodeSendFile<cr>", desc = "Send file to Claude" },
    { "<leader>as", "<cmd>ClaudeCodeSendSelection<cr>", mode = "v", desc = "Send selection to Claude" },
    { "<leader>ac", "<cmd>ClaudeCodeSendCommand<cr>", desc = "Send command to Claude" },
    { "<leader>ad", "<cmd>ClaudeCodeShowDiff<cr>", desc = "Show Claude diff" },
    { "<leader>aa", "<cmd>ClaudeCodeAcceptDiff<cr>", desc = "Accept changes" },
    { "<leader>ar", "<cmd>ClaudeCodeRejectDiff<cr>", desc = "Reject changes" },
    { "<leader>at", "<cmd>ClaudeCodeTogglePane<cr>", desc = "Toggle Claude pane" },
    { "<leader>ai", "<cmd>ClaudeCodeInfo<cr>", desc = "Integration info" },
    { "<leader>ah", "<cmd>ClaudeCodeHelp<cr>", desc = "Help" },
    { "<leader>ap", "<cmd>ClaudeCodeProjects<cr>", desc = "Project suggestions" },
  },
}

Using packer.nvim

use {
  'yourusername/claude-code.nvim',
  requires = {
    'sindrets/diffview.nvim',
    'folke/which-key.nvim', -- Optional
  },
  config = function()
    require('claude-code').setup()
  end
}

Using vim-plug

Plug 'sindrets/diffview.nvim'
Plug 'folke/which-key.nvim'  " Optional
Plug 'yourusername/claude-code.nvim'

" In your init.vim or after plugin load:
lua require('claude-code').setup()

🚀 Quick Start

1. Install Claude Code CLI following the official guide
2. Start tmux and create a pane for Claude Code
3. Run Claude Code in the tmux pane: claude-code
4. Open Neovim in another tmux pane
5. Start coding and use <leader>af to send files to Claude!

⌨️ Keybindings

All keybindings use the <leader>a prefix (AI Assistant):

Keybinding	Command	Description
<leader>af	:ClaudeCodeSendFile	Send current file to Claude
<leader>as	:ClaudeCodeSendSelection	Send visual selection to Claude
<leader>ac	:ClaudeCodeSendCommand	Send custom command to Claude
<leader>ad	:ClaudeCodeShowDiff	Show diff preview of changes
<leader>aa	:ClaudeCodeAcceptDiff	Accept Claude's proposed changes
<leader>ar	:ClaudeCodeRejectDiff	Reject Claude's proposed changes
<leader>at	:ClaudeCodeTogglePane	Switch to Claude Code tmux pane
<leader>ai	:ClaudeCodeInfo	Show integration status info
<leader>ah	:ClaudeCodeHelp	Show help documentation
<leader>ap	:ClaudeCodeProjects	Show project-specific suggestions

🔧 Configuration

require("claude-code").setup({
  tmux = {
    claude_pane = nil, -- Auto-detect or specify pane ID (e.g., "%1")
    capture_height = 50, -- Lines to capture from Claude pane
  },
  diff = {
    temp_dir = vim.fn.stdpath("cache") .. "/claude-code",
    auto_close_diff = false, -- Auto-close diff after accepting/rejecting
  },
  keymaps = {
    -- Customize keybindings (defaults shown)
    send_file = "<leader>af",
    send_selection = "<leader>as",
    send_command = "<leader>ac",
    show_diff = "<leader>ad",
    accept_diff = "<leader>aa",
    reject_diff = "<leader>ar",
    toggle_pane = "<leader>at",
  },
})

🎯 Workflow Examples

🐛 Bug Fixing

1. Open problematic file in Neovim
2. <leader>af - Send file to Claude with: "Find and fix the bug in this component"
3. <leader>ad - Review proposed fix in diff view
4. <leader>aa - Accept the fix if it looks good

🔄 Code Refactoring

1. Select complex function (visual mode)
2. <leader>as - Send selection with context
3. <leader>ac - "Refactor this function to improve readability"
4. <leader>ad - Compare old vs new implementation
5. <leader>aa - Apply the refactored version

📝 Documentation Generation

1. <leader>af - Send component file
2. <leader>ac - "Add comprehensive JSDoc comments"
3. <leader>ad - Review generated documentation
4. <leader>aa - Accept documentation additions

See more examples in the full documentation

🔍 Practical Use Case Scenarios

Click to expand detailed use cases

⚡ Performance Optimization

1. Select slow React component render method
2. <leader>as - Send selection
3. <leader>ac - "Optimize this component for better performance"
4. <leader>ad - Compare optimized version
5. <leader>aa - Apply performance improvements

🧪 Test Generation

1. Open function/component that needs tests
2. <leader>af - Send file to Claude
3. <leader>ac - "Generate comprehensive unit tests"
4. <leader>ad - Review generated test file
5. <leader>aa - Accept and create test file

🔒 Security Review

1. Open API route file
2. <leader>af - Send to Claude
3. <leader>ac - "Review for security vulnerabilities"
4. <leader>ad - See proposed security improvements
5. <leader>aa - Apply security fixes

🎯 TypeScript Improvements

1. Select poorly typed function
2. <leader>as - Send selection
3. <leader>ac - "Improve TypeScript types and interfaces"
4. <leader>ad - Review type improvements
5. <leader>aa - Apply better typing

🚀 Migration Assistance

1. Open legacy component
2. <leader>af - Send to Claude
3. <leader>ac - "Migrate to modern React hooks"
4. <leader>ad - See modernized version
5. <leader>aa - Apply modern patterns

🛠️ Requirements

• Neovim >= 0.8.0
• tmux - For pane communication
• Claude Code CLI - Get it from Anthropic
• diffview.nvim - For diff visualization (auto-installed)

📋 Tmux Setup

The integration automatically detects Claude Code panes by:

1. Looking for processes named "claude-code" or "claude_code"
2. Searching for panes with "claude" in the title or command
3. Falling back to manual configuration if needed

Manual Pane Configuration

If auto-detection fails, specify the pane ID:

require("claude-code").setup({
  tmux = {
    claude_pane = "%1", -- Replace with your Claude pane ID
  }
})

Find your pane ID with: tmux list-panes

🐛 Troubleshooting

Claude Pane Not Detected

• Use <leader>ai to check detection status
• Ensure Claude Code is running in tmux
• Manually specify pane ID in configuration

Diff Not Showing

• Ensure diffview.nvim is installed
• Check that Claude responded with file changes
• Use <leader>ai to verify tmux communication

Commands Not Working

• Verify tmux session is active
• Check Claude Code is responsive in its pane
• Review output with <leader>ai

🤝 Contributing

Contributions are welcome! Please feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests
• 📖 Improve documentation

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Claude Code CLI by Anthropic
• diffview.nvim for diff visualization
• which-key.nvim for keybinding organization
• Inspired by Cursor and Windsurf IDE integrations

---

⭐ Star this repo if you find it useful!