Neovim Integration

Pair code with Ada directly in Neovim! Context-aware AI assistance with memory and biomimetic intelligence.

Overview

ada.nvim is a Neovim plugin that brings Ada’s conversational AI into your editor. It uses the Model Context Protocol (MCP) to communicate with Ada’s brain, providing:

• 💬 Chat Buffer - Dedicated conversation window

• 🔍 Code Explanation - Understand what code does

• 💡 Smart Suggestions - Get improvement ideas

• 🐛 Debug Help - Explain errors and suggest fixes

• 🧠 Context-Aware - Ada sees your code and project

• 🔒 Privacy-First - Runs locally, no cloud

• ⚡ Fast - Efficient MCP protocol with streaming

Architecture

The plugin follows Ada’s adapter pattern:

┌─────────────────┐
│  Neovim (Lua)   │
│  - Plugin UI    │
│  - Commands     │
└────────┬────────┘
         │ stdio (JSON-RPC)
         ▼
┌─────────────────┐
│  ada-mcp server │
│  - MCP protocol │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│  Ada Brain API  │
│  - RAG context  │
│  - Memory       │
│  - Biomimetics  │
└─────────────────┘

Key Components:

1. Plugin (Lua) - Neovim interface, user commands

2. MCP Server (Python) - Protocol translation layer

3. Brain API (Python) - Core Ada intelligence

Installation

Prerequisites

• Neovim 0.8+ (with Lua support)

• Ada v1 running locally with MCP server

• Python 3.13+ with ada-mcp package installed

Install ada.nvim

Using lazy.nvim:

{
  dir = '~/Code/ada-v1/ada.nvim',  -- Adjust path
  config = function()
    require('ada').setup({
      ada_mcp_command = {vim.fn.expand('~/.venv/bin/ada-mcp')},
      chat_window_width = 80,
      auto_start_server = true,
    })
  end
}

Manual installation:

-- In init.lua
vim.opt.runtimepath:append('~/Code/ada-v1/ada.nvim')
require('ada').setup()

Configuration

require('ada').setup({
  -- Command to start ada-mcp server
  ada_mcp_command = {'/path/to/ada-mcp'},

  -- Width of chat window
  chat_window_width = 80,

  -- Auto-start MCP server on Neovim launch
  auto_start_server = true,
})

Usage

Commands

Command	Description
:AdaChat	Open chat buffer
:AdaAsk <msg>	Send message (with code context)
:AdaExplain	Explain selected code
:AdaSuggest	Get improvement suggestions
:AdaDebug	Debug error on current line
:AdaStart	Manually start MCP server
:AdaStop	Stop MCP server

Workflow Examples

Basic Chat:

:AdaChat
:AdaAsk How do I parse JSON in Python?

Explain Code:

1. Select code in visual mode (V)

2. :AdaExplain

Get Suggestions with Context:

1. Select code in visual mode

2. :AdaAsk Can this be optimized?

Debug Help:

1. Place cursor on error line

2. :AdaDebug

Keybindings

Recommended keybindings:

-- Open Ada chat
vim.keymap.set('n', '<leader>ac', ':AdaChat<CR>', { desc = 'Ada Chat' })

-- Ask with visual selection
vim.keymap.set('v', '<leader>aa', ':AdaAsk ', { desc = 'Ask Ada' })

-- Explain selected code
vim.keymap.set('v', '<leader>ae', ':AdaExplain<CR>', { desc = 'Explain Code' })

-- Get suggestions
vim.keymap.set('v', '<leader>as', ':AdaSuggest<CR>', { desc = 'Suggest Improvements' })

-- Debug help
vim.keymap.set('n', '<leader>ad', ':AdaDebug<CR>', { desc = 'Debug Help' })

Chat Buffer

The chat buffer has special keybindings:

Key	Action
i	Send message (prompts for input)
I	Send message (prompts for input)
q	Close chat window

Context Awareness

Ada sees your code! When you use commands like :AdaAsk or :AdaExplain with a visual selection, Ada receives:

• Selected code

• File path and name

• Programming language

• Cursor position

• Surrounding context

Example: Selecting Python code and running :AdaExplain sends:

Explain what this code does:

Context from my_script.py (line 42):
```python
def calculate_fibonacci(n):
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)
```

Ada can then provide language-specific, context-aware explanations!

MCP Protocol

The plugin uses the Model Context Protocol (MCP) for communication:

Why MCP?

• Standard: Well-defined protocol for AI tool interactions

• Efficient: Lightweight stdio communication

• Extensible: Easy to add new tools/capabilities

• Local: No network required

Protocol Flow:

1. Plugin starts ada-mcp server via stdio

2. Handshake: initialize request

3. Plugin sends tools/call requests

4. Server forwards to Ada brain via HTTP

5. Responses stream back through MCP

Tools Available:

• ada_chat - Send message, get response

• ada_search_memory - Search Ada’s memory store

• ada_add_memory - Add new memory

• ada_health - Check Ada brain status

Resources Available:

• Ada documentation (from .ai/ folder)

• System status

• Configuration info

Troubleshooting

MCP Server Won’t Start

Check Ada is running:

docker compose ps
# Should show brain, chroma, ollama running

Verify ada-mcp is installed:

python -m ada_mcp --help
# Should show MCP server help

Check logs:

:messages

No Response from Ada

Restart MCP server:

:AdaStop
:AdaStart

Verify Ada brain is accessible:

curl http://localhost:8000/v1/healthz

Check stderr output:

Look for MCP server errors in Neovim messages.

Chat Buffer Issues

Close and reopen:

:AdaChat

Check buffer list:

:buffers
:buffer <number>

Reset plugin:

:AdaStop
:lua package.loaded['ada'] = nil
:lua require('ada').setup()

Advanced Usage

Custom Workflow Integration

Create custom commands for your workflow:

-- Custom command: Explain function under cursor
vim.api.nvim_create_user_command('AdaExplainFunction', function()
  -- Use treesitter to get function
  local ts_utils = require('nvim-treesitter.ts_utils')
  local node = ts_utils.get_node_at_cursor()

  while node do
    if node:type():match('function') then
      local text = vim.treesitter.get_node_text(node, 0)
      vim.cmd('AdaAsk Explain this function: ' .. text)
      return
    end
    node = node:parent()
  end

  vim.notify('No function found', vim.log.levels.WARN)
end, {})

Async Context Loading

For large codebases, pre-load context:

-- Pre-load project context in background
vim.defer_fn(function()
  local mcp = require('ada.mcp_client')
  mcp.send_request('tools/call', {
    name = 'ada_chat',
    arguments = {
      message = 'Load project context for: ' .. vim.fn.getcwd()
    }
  }, function() end)  -- Fire and forget
end, 2000)  -- 2 seconds after startup

Integration with LSP

Combine Ada with Language Server Protocol:

-- Use LSP diagnostics for better debug help
vim.api.nvim_create_user_command('AdaDebugWithLSP', function()
  local diagnostics = vim.diagnostic.get(0)  -- Current buffer
  local current_line = vim.fn.line('.')

  -- Find diagnostic at cursor
  for _, diag in ipairs(diagnostics) do
    if diag.lnum + 1 == current_line then
      local message = string.format(
        'Debug this %s error: %s',
        diag.severity,
        diag.message
      )
      vim.cmd('AdaAsk ' .. message)
      return
    end
  end

  vim.notify('No LSP diagnostic at cursor', vim.log.levels.WARN)
end, {})

Performance Tips

Cache Control:

Ada caches persona and other stable context. You can force refresh:

-- Force Ada to reload context
vim.api.nvim_create_user_command('AdaRefresh', function()
  require('ada.mcp_client').send_request('tools/call', {
    name = 'ada_chat',
    arguments = { message = '__refresh_context__' }
  }, function() end)
end, {})

Lazy Loading:

Only load plugin when needed:

{
  dir = '~/Code/ada-v1/ada.nvim',
  lazy = true,
  cmd = {'AdaChat', 'AdaAsk', 'AdaExplain', 'AdaSuggest', 'AdaDebug'},
  config = function()
    require('ada').setup()
  end
}

Philosophy

Why Neovim?

• Terminal-native: Fits hacker workflow

• Extensible: Lua makes it hackable

• Private: Everything local, no cloud

• Fast: Efficient protocol, minimal overhead

Why MCP?

• Standard: Well-defined protocol

• Simple: Easy to extend and debug

• Modular: Separate concerns cleanly

• Future-proof: Industry standard for AI tools

Adapter Pattern:

Neovim is just one adapter! Ada’s architecture supports:

• CLI (terminal REPL)

• Web UI (browser)

• Matrix (chat rooms)

• Neovim (editor)

• MCP (IDE integration)

All adapters are equal peers, communicating via Brain API.

See Also

• Ada Adapters - Adapter pattern architecture

• Adapter Development Guide - Build your own adapter

• Biomimetic Features - Ada’s memory enhancements

• API Usage Guide - Direct API usage

Contributing

ada.nvim is part of the Ada v1 project. Contributions welcome!

GitHub: https://github.com/luna-system/ada

Areas to explore:

• More commands (rename, refactor, etc.)

• Better treesitter integration

• Telescope integration (search memories)

• Status line indicators

• Rich UI with nui.nvim

• Auto-completion integration

—

Last Updated: 2025-12-17 Version: v1.6.0 Status: Production-ready, actively developed

Built with 🔥 by the Ada community