Neovim Setup Guide | Bootspring Docs

Complete guide to integrating Bootspring with Neovim for terminal-based development.

Overview#

Neovim is a hyperextensible text editor. Bootspring integrates through:

Terminal commands - Run Bootspring from within Neovim
Custom commands - Vim commands for common operations
Status line - Display project status
LSP integration - Enhanced completions
Telescope - Fuzzy finding agents and skills

Prerequisites#

Neovim 0.8+ installed
Bootspring CLI installed (npm install -g bootspring)
Node.js 18+ installed
Plugin manager (lazy.nvim, packer, or vim-plug)

Installing Neovim#

macOS#

brew install neovim

Linux#

# Ubuntu/Debian
sudo apt install neovim

# Fedora
sudo dnf install neovim

# Arch
sudo pacman -S neovim

Windows#

winget install Neovim.Neovim

Basic Configuration#

Initialize Bootspring#

cd your-project
bootspring init
bootspring generate

Neovim Lua Configuration#

Add to ~/.config/nvim/lua/bootspring.lua:

local M = {}

-- Configuration
M.config = {
  default_agent = "frontend-expert",
  auto_generate = false,
  show_notifications = true,
}

-- Setup function
function M.setup(opts)
  M.config = vim.tbl_deep_extend("force", M.config, opts or {})
  M.create_commands()
  M.create_keymaps()
end

-- Create user commands
function M.create_commands()
  -- Generate context
  vim.api.nvim_create_user_command("BootspringGenerate", function()
    M.generate()
  end, { desc = "Regenerate Bootspring context" })

  -- Check status
  vim.api.nvim_create_user_command("BootspringStatus", function()
    M.status()
  end, { desc = "Show Bootspring status" })

  -- Invoke agent
  vim.api.nvim_create_user_command("BootspringAgent", function(opts)
    M.invoke_agent(opts.args)
  end, { nargs = "+", desc = "Invoke Bootspring agent" })

  -- Apply skill
  vim.api.nvim_create_user_command("BootspringSkill", function(opts)
    M.apply_skill(opts.args)
  end, { nargs = 1, desc = "Apply Bootspring skill" })

  -- Quality check
  vim.api.nvim_create_user_command("BootspringQuality", function(opts)
    local preset = opts.args ~= "" and opts.args or "pre-commit"
    M.quality(preset)
  end, { nargs = "?", desc = "Run Bootspring quality check" })

  -- List agents
  vim.api.nvim_create_user_command("BootspringAgents", function()
    M.list_agents()
  end, { desc = "List available agents" })

  -- Start workflow
  vim.api.nvim_create_user_command("BootspringWorkflow", function(opts)
    M.start_workflow(opts.args)
  end, { nargs = 1, desc = "Start Bootspring workflow" })
end

-- Create keymaps
function M.create_keymaps()
  local keymap = vim.keymap.set
  local opts = { noremap = true, silent = true }

  -- Leader key mappings (assuming <leader> is space or \)
  keymap("n", "<leader>bg", ":BootspringGenerate<CR>",
    vim.tbl_extend("force", opts, { desc = "Generate context" }))
  keymap("n", "<leader>bs", ":BootspringStatus<CR>",
    vim.tbl_extend("force", opts, { desc = "Show status" }))
  keymap("n", "<leader>ba", ":BootspringAgent ",
    vim.tbl_extend("force", opts, { desc = "Invoke agent" }))
  keymap("n", "<leader>bq", ":BootspringQuality<CR>",
    vim.tbl_extend("force", opts, { desc = "Quality check" }))
  keymap("n", "<leader>bl", ":BootspringAgents<CR>",
    vim.tbl_extend("force", opts, { desc = "List agents" }))
end

-- Helper: Run command and handle output
function M.run_command(cmd, callback)
  local output = vim.fn.system(cmd)
  local success = vim.v.shell_error == 0

  if callback then
    callback(success, output)
  else
    if success then
      vim.notify(output, vim.log.levels.INFO)
    else
      vim.notify("Error: " .. output, vim.log.levels.ERROR)
    end
  end

  return success, output
end

-- Generate context
function M.generate()
  vim.notify("Generating Bootspring context...", vim.log.levels.INFO)
  M.run_command("bootspring generate", function(success, output)
    if success then
      vim.notify("Context generated successfully", vim.log.levels.INFO)
    else
      vim.notify("Failed to generate context: " .. output, vim.log.levels.ERROR)
    end
  end)
end

-- Show status
function M.status()
  local success, output = M.run_command("bootspring status")
  if success then
    -- Open in floating window
    local buf = vim.api.nvim_create_buf(false, true)
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, vim.split(output, "\n"))

    local width = math.min(80, vim.o.columns - 4)
    local height = math.min(20, vim.o.lines - 4)

    vim.api.nvim_open_win(buf, true, {
      relative = "editor",
      width = width,
      height = height,
      col = (vim.o.columns - width) / 2,
      row = (vim.o.lines - height) / 2,
      style = "minimal",
      border = "rounded",
      title = " Bootspring Status ",
    })
  end
end

-- Invoke agent
function M.invoke_agent(args)
  local parts = vim.split(args, " ", { trimempty = true })
  local agent = parts[1] or M.config.default_agent
  local prompt = table.concat(vim.list_slice(parts, 2), " ")

  if prompt == "" then
    prompt = vim.fn.input("Prompt: ")
  end

  if prompt == "" then
    vim.notify("No prompt provided", vim.log.levels.WARN)
    return
  end

  vim.notify("Invoking " .. agent .. "...", vim.log.levels.INFO)

  local cmd = string.format('bootspring agent invoke %s "%s"', agent, prompt)
  local success, output = M.run_command(cmd)

  if success then
    -- Open result in split
    vim.cmd("vnew")
    local buf = vim.api.nvim_get_current_buf()
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, vim.split(output, "\n"))
    vim.bo[buf].filetype = "markdown"
    vim.bo[buf].buftype = "nofile"
    vim.bo[buf].modifiable = false
  end
end

-- Apply skill
function M.apply_skill(pattern)
  vim.notify("Applying skill: " .. pattern, vim.log.levels.INFO)
  M.run_command("bootspring skill apply " .. pattern)
end

-- Run quality check
function M.quality(preset)
  vim.notify("Running quality check: " .. preset, vim.log.levels.INFO)
  local success, output = M.run_command("bootspring quality " .. preset)

  if success then
    vim.notify("Quality check passed!", vim.log.levels.INFO)
  else
    -- Parse and show in quickfix
    vim.fn.setqflist({}, "r", { title = "Bootspring Quality", lines = vim.split(output, "\n") })
    vim.cmd("copen")
  end
end

-- List agents
function M.list_agents()
  local success, output = M.run_command("bootspring agent list")
  if success then
    local buf = vim.api.nvim_create_buf(false, true)
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, vim.split(output, "\n"))

    vim.api.nvim_open_win(buf, true, {
      relative = "editor",
      width = 60,
      height = 30,
      col = (vim.o.columns - 60) / 2,
      row = (vim.o.lines - 30) / 2,
      style = "minimal",
      border = "rounded",
      title = " Available Agents ",
    })
  end
end

-- Start workflow
function M.start_workflow(workflow)
  vim.notify("Starting workflow: " .. workflow, vim.log.levels.INFO)

  -- Open in terminal
  vim.cmd("terminal bootspring workflow start " .. workflow)
end

return M

Load in init.lua#

-- ~/.config/nvim/init.lua

-- Load Bootspring module
require("bootspring").setup({
  default_agent = "frontend-expert",
  auto_generate = false,
  show_notifications = true,
})

Plugin Manager Setup#

lazy.nvim#

-- ~/.config/nvim/lua/plugins/bootspring.lua
return {
  {
    dir = "~/.config/nvim/lua/bootspring.lua",
    config = function()
      require("bootspring").setup()
    end,
  },
}

packer.nvim#

use {
  "~/.config/nvim/lua/bootspring",
  config = function()
    require("bootspring").setup()
  end,
}

Telescope Integration#

Install Telescope#

-- lazy.nvim
{
  "nvim-telescope/telescope.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
}

Bootspring Telescope Extension#

Create ~/.config/nvim/lua/telescope/_extensions/bootspring.lua:

local pickers = require("telescope.pickers")
local finders = require("telescope.finders")
local conf = require("telescope.config").values
local actions = require("telescope.actions")
local action_state = require("telescope.actions.state")

local M = {}

-- Agent picker
M.agents = function(opts)
  opts = opts or {}

  local output = vim.fn.system("bootspring agent list --json")
  local agents = vim.fn.json_decode(output)

  pickers.new(opts, {
    prompt_title = "Bootspring Agents",
    finder = finders.new_table({
      results = agents,
      entry_maker = function(entry)
        return {
          value = entry,
          display = entry.name .. " - " .. entry.description,
          ordinal = entry.name,
        }
      end,
    }),
    sorter = conf.generic_sorter(opts),
    attach_mappings = function(prompt_bufnr)
      actions.select_default:replace(function()
        actions.close(prompt_bufnr)
        local selection = action_state.get_selected_entry()
        local prompt = vim.fn.input("Prompt: ")
        if prompt ~= "" then
          require("bootspring").invoke_agent(selection.value.name .. " " .. prompt)
        end
      end)
      return true
    end,
  }):find()
end

-- Skill picker
M.skills = function(opts)
  opts = opts or {}

  local output = vim.fn.system("bootspring skill list --json")
  local skills = vim.fn.json_decode(output)

  pickers.new(opts, {
    prompt_title = "Bootspring Skills",
    finder = finders.new_table({
      results = skills,
      entry_maker = function(entry)
        return {
          value = entry,
          display = entry.name,
          ordinal = entry.name,
        }
      end,
    }),
    sorter = conf.generic_sorter(opts),
    attach_mappings = function(prompt_bufnr)
      actions.select_default:replace(function()
        actions.close(prompt_bufnr)
        local selection = action_state.get_selected_entry()
        require("bootspring").apply_skill(selection.value.name)
      end)
      return true
    end,
  }):find()
end

-- Workflow picker
M.workflows = function(opts)
  opts = opts or {}

  local workflows = {
    { name = "preseed", description = "Idea to documentation" },
    { name = "seed", description = "Project scaffolding" },
    { name = "feature-development", description = "Full feature lifecycle" },
    { name = "security-audit", description = "Security review" },
    { name = "mvp", description = "MVP generation" },
  }

  pickers.new(opts, {
    prompt_title = "Bootspring Workflows",
    finder = finders.new_table({
      results = workflows,
      entry_maker = function(entry)
        return {
          value = entry,
          display = entry.name .. " - " .. entry.description,
          ordinal = entry.name,
        }
      end,
    }),
    sorter = conf.generic_sorter(opts),
    attach_mappings = function(prompt_bufnr)
      actions.select_default:replace(function()
        actions.close(prompt_bufnr)
        local selection = action_state.get_selected_entry()
        require("bootspring").start_workflow(selection.value.name)
      end)
      return true
    end,
  }):find()
end

return require("telescope").register_extension({
  exports = {
    agents = M.agents,
    skills = M.skills,
    workflows = M.workflows,
  },
})

Telescope Keymaps#

vim.keymap.set("n", "<leader>fa", ":Telescope bootspring agents<CR>", { desc = "Find agents" })
vim.keymap.set("n", "<leader>fk", ":Telescope bootspring skills<CR>", { desc = "Find skills" })
vim.keymap.set("n", "<leader>fw", ":Telescope bootspring workflows<CR>", { desc = "Find workflows" })

Lualine Integration#

Status Line#

-- ~/.config/nvim/lua/plugins/lualine.lua
require("lualine").setup({
  sections = {
    lualine_x = {
      {
        function()
          local status = vim.fn.system("bootspring status --json 2>/dev/null")
          if vim.v.shell_error == 0 then
            local data = vim.fn.json_decode(status)
            if data and data.initialized then
              return "󰊤 " .. (data.project or "bootspring")
            end
          end
          return ""
        end,
        cond = function()
          return vim.fn.filereadable("bootspring.config.js") == 1
        end,
      },
    },
  },
})

Which-Key Integration#

-- ~/.config/nvim/lua/plugins/which-key.lua
require("which-key").register({
  ["<leader>b"] = {
    name = "+bootspring",
    g = { ":BootspringGenerate<CR>", "Generate context" },
    s = { ":BootspringStatus<CR>", "Show status" },
    a = { ":BootspringAgent ", "Invoke agent" },
    q = { ":BootspringQuality<CR>", "Quality check" },
    l = { ":BootspringAgents<CR>", "List agents" },
    w = { ":BootspringWorkflow ", "Start workflow" },
  },
})

Terminal Integration#

Toggleterm#

-- ~/.config/nvim/lua/plugins/toggleterm.lua
require("toggleterm").setup({
  size = 20,
  open_mapping = [[<c-\>]],
  direction = "horizontal",
})

-- Bootspring terminal
local Terminal = require("toggleterm.terminal").Terminal

local bootspring = Terminal:new({
  cmd = "bootspring status && exec $SHELL",
  direction = "float",
  float_opts = {
    border = "curved",
  },
})

vim.keymap.set("n", "<leader>bt", function()
  bootspring:toggle()
end, { desc = "Bootspring terminal" })

Auto Commands#

Auto-Generate on Save#

vim.api.nvim_create_autocmd("BufWritePost", {
  pattern = { "*.ts", "*.tsx", "*.js", "*.jsx" },
  callback = function()
    if vim.fn.filereadable("bootspring.config.js") == 1 then
      -- Only if auto_generate is enabled
      if require("bootspring").config.auto_generate then
        require("bootspring").generate()
      end
    end
  end,
})

Project Detection#

vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    if vim.fn.filereadable("bootspring.config.js") == 1 then
      vim.notify("Bootspring project detected", vim.log.levels.INFO)
    end
  end,
})

LSP Integration#

Custom Source for nvim-cmp#

-- Add Bootspring suggestions to completion
local source = {}

source.new = function()
  return setmetatable({}, { __index = source })
end

source.get_trigger_characters = function()
  return { "@" }
end

source.complete = function(self, request, callback)
  local items = {}

  -- Add agent completions
  local agents = { "frontend-expert", "backend-expert", "database-expert", "security-expert" }
  for _, agent in ipairs(agents) do
    table.insert(items, {
      label = "@bootspring-agent: " .. agent,
      kind = vim.lsp.protocol.CompletionItemKind.Reference,
    })
  end

  -- Add skill completions
  local skills = { "patterns/api-endpoint", "patterns/react-component", "patterns/prisma-crud" }
  for _, skill in ipairs(skills) do
    table.insert(items, {
      label = "@bootspring-skill: " .. skill,
      kind = vim.lsp.protocol.CompletionItemKind.Snippet,
    })
  end

  callback({ items = items })
end

require("cmp").register_source("bootspring", source.new())

Treesitter#

Highlight CLAUDE.md#

-- Add markdown highlighting for CLAUDE.md
vim.api.nvim_create_autocmd({ "BufRead", "BufNewFile" }, {
  pattern = "CLAUDE.md",
  callback = function()
    vim.bo.filetype = "markdown"
  end,
})

Troubleshooting#

Commands Not Working#

# Verify Bootspring is installed
bootspring --version

# Check PATH
echo $PATH | tr ':' '\n' | grep -E "(npm|node)"

# Test command directly
bootspring status

Lua Module Not Found#

-- Check module path
print(vim.inspect(package.path))

-- Ensure file exists
:!ls ~/.config/nvim/lua/bootspring.lua

Terminal Issues#

-- Use jobstart for async commands
vim.fn.jobstart("bootspring generate", {
  on_stdout = function(_, data)
    vim.notify(table.concat(data, "\n"))
  end,
  on_exit = function(_, code)
    if code == 0 then
      vim.notify("Done!")
    end
  end,
})

Performance#

-- Cache agent list
local cached_agents = nil
local function get_agents()
  if not cached_agents then
    local output = vim.fn.system("bootspring agent list --json")
    cached_agents = vim.fn.json_decode(output)
  end
  return cached_agents
end

Complete Configuration#

Full init.lua Example#

-- ~/.config/nvim/init.lua

-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git", "clone", "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable", lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

-- Leader key
vim.g.mapleader = " "

-- Plugins
require("lazy").setup({
  -- Telescope
  {
    "nvim-telescope/telescope.nvim",
    dependencies = { "nvim-lua/plenary.nvim" },
  },
  -- Lualine
  { "nvim-lualine/lualine.nvim" },
  -- Which-key
  { "folke/which-key.nvim" },
  -- Toggleterm
  { "akinsho/toggleterm.nvim" },
})

-- Load Bootspring
require("bootspring").setup({
  default_agent = "frontend-expert",
  auto_generate = false,
})

-- Basic options
vim.opt.number = true
vim.opt.relativenumber = true
vim.opt.expandtab = true
vim.opt.shiftwidth = 2