Skip to content
Back to News
guide
neovim
setup
beginner

CKB + Neovim: Semantic Code Intelligence for Terminal Warriors

By CKB Team

Neovim users value efficiency, customization, and keyboard-driven workflows. CKB fits right in—adding semantic code intelligence to your AI plugin without slowing you down.

This guide covers setting up CKB with Neovim's MCP-compatible AI plugins.

What You'll Get

With CKB connected, your Neovim AI can:

  • Find function callers instantly (semantic, not grep)
  • Show impact before you change code
  • Navigate by understanding, not just text matching
  • Identify code owners and reviewers

Prerequisites

Setup with avante.nvim

avante.nvim is a popular Cursor-like AI plugin with MCP support.

Step 1: Install CKB

npm install -g @tastehub/ckb

Step 2: Index Your Project

cd /your/project
ckb init

Step 3: Configure avante.nvim

In your Neovim config (init.lua or separate plugin config):

require('avante').setup({
  -- Your existing avante config...

  mcp = {
    servers = {
      ckb = {
        command = "npx",
        args = { "@tastehub/ckb", "mcp" },
      },
    },
  },
})

Step 4: Restart Neovim

Restart or source your config: :source %

Setup with codecompanion.nvim

codecompanion.nvim offers extensive customization and MCP support.

require('codecompanion').setup({
  adapters = {
    -- Your adapter config...
  },

  mcp = {
    servers = {
      ckb = {
        command = "npx",
        args = { "@tastehub/ckb", "mcp" },
      },
    },
  },
})

Setup with gp.nvim

gp.nvim is a flexible ChatGPT plugin:

require('gp').setup({
  -- Your existing config...

  mcp_servers = {
    ckb = {
      command = "npx",
      args = { "@tastehub/ckb", "mcp" },
    },
  },
})

Using CKB in Neovim

Chat Commands

Open your AI chat and query:

:AvanteChat
> What calls the handleRequest function?

AI: [uses CKB's getCallGraph]

handleRequest in internal/api/handler.go is called by:
- Router.ServeHTTP at router.go:45
- TestHandler at handler_test.go:23

Callees: validateInput, processData, sendResponse

Visual Selection + AI

Select code and invoke AI:

" Select a function with V, then:
:'<,'>AvanteAsk What's the impact of changing this?

AI: [uses prepareChange]

This function has 8 callers. Changing it affects:
- 3 controllers
- 12 tests
Risk: Medium

Custom Keymaps

Set up efficient keybindings:

-- Quick impact analysis
vim.keymap.set('n', '<leader>ai', function()
  local word = vim.fn.expand('<cword>')
  vim.cmd('AvanteAsk What is the impact of changing ' .. word .. '?')
end, { desc = 'Analyze impact' })

-- Find callers
vim.keymap.set('n', '<leader>ac', function()
  local word = vim.fn.expand('<cword>')
  vim.cmd('AvanteAsk What calls ' .. word .. '?')
end, { desc = 'Find callers' })

-- Explain symbol
vim.keymap.set('n', '<leader>ae', function()
  local word = vim.fn.expand('<cword>')
  vim.cmd('AvanteAsk Explain the ' .. word .. ' function')
end, { desc = 'Explain symbol' })

Preset Configuration

Choose a preset for your workflow:

mcp = {
  servers = {
    ckb = {
      command = "npx",
      args = { "@tastehub/ckb", "mcp", "--preset=core" },
    },
  },
},
Preset Tools Use
core 21 General development
review 27 Code review
refactor 33 Cleanup work
full 92 All capabilities

Neovim-Specific Workflows

Telescope Integration

If your AI plugin integrates with Telescope:

:Telescope ckb symbols
" Search symbols semantically

:Telescope ckb references
" Find references with context

Quickfix Integration

Some plugins can populate quickfix with CKB results:

:AvanteAsk Find all callers of handlePayment as a list

AI: [returns structured list]

" Jump to quickfix
:copen

LSP Complement

CKB complements Neovim's LSP:

LSP CKB
Go to definition Who calls this function
Find references Impact of changing this
Hover info Code ownership
Diagnostics Dead code detection

Workflow Example

" 1. I see a function I want to modify
" 2. Check callers (LSP or CKB)
:lua vim.lsp.buf.references()
" or
:AvanteAsk What calls this function?

" 3. Check impact
:AvanteAsk What's the impact of modifying this?

" 4. Make changes
" ... edit code ...

" 5. Verify
:AvanteAsk Did I break anything with these changes?

Project Configuration

Create .ckb/config.json in your project:

{
  "preset": "core",
  "exclude": [
    "vendor/**",
    "node_modules/**",
    "*.generated.go"
  ]
}

Performance Tips

Keep Index Fresh

Run the watcher in a tmux pane or background:

ckb watch

Or use an autocmd:

vim.api.nvim_create_autocmd("BufWritePost", {
  pattern = { "*.go", "*.ts", "*.py", "*.rs" },
  callback = function()
    vim.fn.jobstart({ "ckb", "index", "--incremental", "--quiet" })
  end,
})

Lazy Loading

Load MCP servers lazily to speed up Neovim startup:

require('avante').setup({
  mcp = {
    lazy = true,  -- Load servers on first use
    servers = { ... },
  },
})

Common Queries

What calls the main function?
What does handleRequest call?
Show me the authentication flow

Analysis

What's the impact of deleting this file?
Find dead code in this directory
What are the hotspots in this codebase?

Review

Who should review changes to this file?
What tests cover this function?
Find similar code to this function

Troubleshooting

Tools not available

  1. Check plugin supports MCP
  2. Verify config syntax
  3. Run :checkhealth for plugin diagnostics
  4. Check :messages for errors

CKB not found

Ensure npx can find CKB:

npx @tastehub/ckb --version

If not, install globally:

npm install -g @tastehub/ckb

Then use direct path:

command = "ckb",
args = { "mcp" },

Slow responses

  1. Use --preset=core for smaller tool set
  2. Check index status: ckb status
  3. Exclude large directories in config

Example Config (Complete)

-- In your plugin manager (lazy.nvim example)
{
  "yetone/avante.nvim",
  dependencies = { ... },
  config = function()
    require('avante').setup({
      provider = "claude",  -- or your preferred provider

      mcp = {
        servers = {
          ckb = {
            command = "npx",
            args = { "@tastehub/ckb", "mcp", "--preset=core" },
          },
        },
      },
    })

    -- Keymaps
    vim.keymap.set('n', '<leader>ac', ':AvanteChat<CR>', { desc = 'AI Chat' })
    vim.keymap.set('v', '<leader>aa', ':AvanteAsk<CR>', { desc = 'AI Ask' })
  end,
}

Next Steps

Links: