NeoCodeium Documentation

To prevent conflicts between NeoCodeium and nvim-cmp, use one of these two patterns:

Pattern 1: NeoCodeium as primary (manual cmp)

Set nvim-cmp to manual completion and clear NeoCodeium suggestions when the cmp menu opens. Use manual = false for NeoCodeium.

local cmp = require("cmp")
local neocodeium = require("neocodeium")

cmp.event:on("menu_opened", function()
    neocodeium.clear()
end)

neocodeium.setup({
    filter = function() 
        return not cmp.visible() 
    end,
})

cmp.setup({
    completion = {
        autocomplete = false,
    },
})

Pattern 2: nvim-cmp as primary (manual NeoCodeium)

Set NeoCodeium to manual = true. Create an autocommand to abort cmp when NeoCodeium completions are displayed.

local neocodeium = require("neocodeium")

neocodeium.setup({
  manual = true,
})

-- close cmp when ai completions are displayed
vim.api.nvim_create_autocmd("User", {
  pattern = "NeoCodeiumCompletionDisplayed",
  callback = function() require("cmp").abort() end,
})

The NeoCodeium server operates as a background process that communicates with Neovim via a local TCP port.

1. Process Spawning: The server is spawned with a manager_dir (created in the system temp directory).
2. Port Discovery: The server writes a file named after its port (e.g., 12345) into the manager_dir. The client uses find_port_file to scan this directory and identify the active port.
3. Connection: Once the port is found, the client establishes a TCP connection to 127.0.0.1:{port}.
4. Heartbeat: After a successful connection, the client automatically starts a heartbeat loop, sending a Heartbeat request every 10 seconds to keep the connection alive and monitor server health.
5. Events: The server lifecycle triggers several events that consumers can listen to:
   • NeoCodeiumServerConnecting
   • NeoCodeiumServerConnected
   • NeoCodeiumServerStopped

Use require("neocodeium").setup(options) to configure the plugin. Key options include:

• enabled (boolean): Whether the plugin is active. If false, the windsurf server won't start.
• bin (string|nil): Path to a custom windsurf server binary.
• manual (boolean): If true, autosuggestions are disabled; use cycle_or_complete() to show them manually.
• server (table): Contains api_url and portal_url for Enterprise mode.
• show_label (boolean): Whether to show the suggestion count in the line number column.
• debounce (boolean): If true, enables suggestions debounce.
• max_lines (number): Max lines parsed from loaded buffers (0 to disable non-current buffer parsing, -1 for all).
• silent (boolean): If true, suppresses non-important messages.
• disable_in_special_buftypes (boolean): If true, disables suggestions in special buftypes (e.g., nofile).
• log_level (string): One of "trace", "debug", "info", "warn", "error".
• single_line (table): Configuration for single-line mode. enabled (boolean) collapses multi-line suggestions into one line.
• filter (function): A function function(bufnr) end that returns true to enable or false to disable suggestions for a buffer.
• filetypes (table): A list of filetypes to disable suggestions for (e.g., { help = false, gitcommit = false }).
• root_dir (table): List of patterns to detect the workspace root directory.

-- NeoCodeium Configuration
require("neocodeium").setup({
  enabled = true,
  bin = nil,
  manual = false,
  server = {
    api_url = nil,
    portal_url = nil,
  },
  show_label = true,
  debounce = false,
  max_lines = 10000,
  silent = false,
  disable_in_special_buftypes = true,
  log_level = "warn",
  single_line = {
    enabled = false,
    label = "...",
  },
  filter = function(bufnr) return true end,
  filetypes = {
    help = false,
    gitcommit = false,
    gitrebase = false,
    ["."] = false,
  },
  root_dir = { ".bzr", ".git", ".hg", ".svn", "_FOSSIL_", "package.json" }
})

Use require("neocodeium").get_status() to retrieve the current state of the plugin and server. This returns two numbers:

1. Plugin Status:

• 0: Enabled
• 1: Globally disabled
• 2: Buffer is disabled
• 3: Buffer disabled by filetype
• 4: Buffer disabled by filter function
• 5: Buffer has wrong encoding (requires UTF-8 or LATIN-1)
• 6: Buffer is a special type

2. Server Status:

• 0: Server is on (running)
• 1: Connecting to the server
• 2: Server is off (stopped)

To ensure the statusline updates in real-time, invoke this function within an autocmd listening to NeoCodeiumServer* or NeoCodeium*Enabled/Disabled events.

local neocodeium = require("neocodeium")
local function get_neocodeium_status(ev) 
    local status, server_status = neocodeium.get_status()
    -- process data...
    if status == 0 then
        vim.api.nvim_buf_set_var(ev.buf, "neocodeium_status", "OK")
    else
        vim.api.nvim_buf_set_var(ev.buf, "neocodeium_status", "OFF")
    end
    vim.cmd.redrawstatus()
end

vim.api.nvim_create_autocmd("User", {
    pattern = {"NeoCodeiumServer*", "NeoCodeium*Enabled", "NeoCodeium*Disabled"}
    callback = get_neocodeium_status,
})

The neocodeium module provides several functions for controlling completions programmatically:

• accept(): Accepts the current suggestion.
• accept_word(): Accepts only the current word of the suggestion.
• accept_line(): Accepts only the current line of the suggestion.
• clear(): Clears the current suggestion.
• cycle(n): Cycles through suggestions by n items (use negative for reverse).
• cycle_or_complete(n): Cycles through suggestions; if none are visible, it attempts to show one (useful in manual mode).
• visible(): Returns whether the suggestion's virtual text is currently visible.

local neocodeium = require("neocodeium")

-- Accepts the suggestion
neocodeium.accept()

-- Accepts only part of the suggestion if the full suggestion doesn't make sense
neocodeium.accept_word()
neocodeium.accept_line()

-- Clears the current suggestion
neocodeium.clear()

-- Cycles through suggestions by `n` (1 by default). 
-- Use a negative value to cycle in reverse order
neocodeium.cycle(n)

-- Same as `cycle()`, but also tries to show a suggestion if none is visible.
-- Mostly useful with the enabled `manual` option
neocodeium.cycle_or_complete(n)

-- Checks if a suggestion's virtual text is visible or not (useful for some complex mappings)
neocodeium.visible()