Neovim Integration

AI Safety validation for Neovim using the THSP protocol.

Features

Requirements

Installation

lazy.nvim (recommended)

{
  'sentinel-seed/sentinel',
  opts = {
    semantic_mode = true,
    llm_provider = 'openai',
    -- openai_api_key = 'sk-...', -- or use OPENAI_API_KEY env var
  },
}

packer.nvim

use {
  'sentinel-seed/sentinel',
  config = function()
    require('sentinel').setup({
      semantic_mode = true,
      llm_provider = 'openai',
    })
  end
}

vim-plug

Plug 'sentinel-seed/sentinel'

" In your init.lua or after/plugin:
lua require('sentinel').setup({})

Manual

git clone https://github.com/sentinel-seed/sentinel \
  ~/.local/share/nvim/site/pack/plugins/start/sentinel

Configuration

require('sentinel').setup({
  -- Analysis mode: true = semantic (LLM), false = heuristic
  semantic_mode = true,

  -- LLM provider: 'openai' or 'anthropic'
  llm_provider = 'openai',

  -- API keys (can also use environment variables)
  openai_api_key = nil,    -- or set OPENAI_API_KEY
  anthropic_api_key = nil, -- or set ANTHROPIC_API_KEY

  -- Auto-analyze on text change
  auto_analyze = false,

  -- Debounce delay for auto-analyze (ms)
  debounce_ms = 500,

  -- Filetypes to analyze
  filetypes = { '*' },

  -- Enable default keymaps
  default_keymaps = false,

  -- Default keymap bindings (if default_keymaps = true)
  keymaps = {
    analyze = '<leader>sa',
    analyze_buffer = '<leader>sA',
    insert_seed = '<leader>si',
    clear = '<leader>sc',
    toggle = '<leader>st',
  },

  -- Diagnostic severity for each gate
  severity = {
    truth = vim.diagnostic.severity.ERROR,
    harm = vim.diagnostic.severity.ERROR,
    scope = vim.diagnostic.severity.WARN,
    purpose = vim.diagnostic.severity.WARN,
  },

  -- Show virtual text for diagnostics
  virtual_text = true,
})

Commands

Keymappings

Using mappings (recommended)

vim.keymap.set('n', '<leader>a', '<Plug>(SentinelAnalyze)')
vim.keymap.set('v', '<leader>a', '<Plug>(SentinelAnalyze)')
vim.keymap.set('n', '<leader>A', '<Plug>(SentinelAnalyzeBuffer)')
vim.keymap.set('n', '<leader>si', '<Plug>(SentinelInsertSeed)')
vim.keymap.set('n', '<leader>sc', '<Plug>(SentinelClear)')
vim.keymap.set('n', '<leader>st', '<Plug>(SentinelToggle)')

Available mappings

The THSP Protocol

The THSP protocol validates content through four gates:

All gates must pass for content to be considered safe.

Analysis Modes

Semantic Mode (default)

Uses OpenAI or Anthropic LLMs for deep semantic understanding.

require('sentinel').setup({
  semantic_mode = true,
  llm_provider = 'openai', -- or 'anthropic'
})

Set your API key via environment variable:

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."

Heuristic Mode

Pattern-based analysis that works offline.

require('sentinel').setup({
  semantic_mode = false,
})

Health Check

Verify your installation:

:checkhealth sentinel

Alignment Seeds

Insert alignment seeds to configure AI behavior:

:SentinelInsertSeed standard  " Full THSP protocol (~4K tokens)
:SentinelInsertSeed minimal   " Compact version (~2K tokens)

Running Tests

Tests require plenary.nvim.

# Install plenary.nvim for testing
git clone https://github.com/nvim-lua/plenary.nvim \
  ~/.local/share/nvim/site/pack/testing/start/plenary.nvim

# Run all tests
cd packages/neovim
nvim --headless -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/minimal_init.lua'}"

Links

• GitHub Repository
• Documentation
• PyPI Package
• npm Package