claw-code/.guardrails/ide/vim-plugin/INSTALL.md

Guardrail Vim Plugin - Installation Guide

Real-time guardrail validation for Vim.

Requirements

• Vim 8.0+ or Neovim
• curl or wget for HTTP requests
• Running Guardrail MCP Server

Installation

Using vim-plug

Add to .vimrc:

Plug 'TheArchitectit/agent-guardrails-template', { 'rtp': 'ide/vim-plugin' }

Then run:

:PlugInstall

Using Vundle

Add to .vimrc:

Plugin 'TheArchitectit/agent-guardrails-template', {'rtp': 'ide/vim-plugin/'}

Then run:

:PluginInstall

Using pathogen.vim

cd ~/.vim/bundle
git clone --depth 1 https://github.com/TheArchitectit/agent-guardrails-template.git
cd agent-guardrails-template/ide/vim-plugin

Manual Installation

mkdir -p ~/.vim/pack/plugins/start
cd ~/.vim/pack/plugins/start
git clone --depth 1 https://github.com/TheArchitectit/agent-guardrails-template.git guardrail
cp -r guardrail/ide/vim-plugin/* guardrail/
rm -rf guardrail/ide guardrail/mcp-server guardrail/docs

Configuration

Add to .vimrc:

" Required settings
let g:guardrail_server_url = 'http://localhost:8095'
let g:guardrail_project_slug = 'your-project'

" Optional settings
let g:guardrail_api_key = 'your-api-key'
let g:guardrail_validate_on_save = 1
let g:guardrail_severity_threshold = 'warning'  " error, warning, info

Security Warning: Never commit API keys to version control. Use environment variables: let g:guardrail_api_key = $GUARDRAIL_API_KEY

Commands

Command	Description
:GuardrailValidate	Validate current file
:GuardrailValidateSelection	Validate visual selection
:GuardrailTestConnection	Test MCP server connection
:GuardrailConfigure	Open configuration

Key Mappings

Default mappings (can be disabled with g:guardrail_no_mappings = 1):

• <leader>gv - Validate file
• <leader>gs - Validate selection (visual mode)
• <leader>gc - Test connection

Customize:

nmap <leader>g <Plug>GuardrailValidate
vmap <leader>g <Plug>GuardrailValidateSelection

Status Line

Add to your status line:

set statusline+=%{guardrail#statusline#GetStatus()}

Or with airline/lightline:

let g:airline_section_x = airline#section#create(['guardrail'])

Quick Start

1. Install the plugin
2. Set required config in .vimrc:

   let g:guardrail_server_url = 'http://localhost:8095'
   let g:guardrail_project_slug = 'my-project'
   

3. Reload Vim or run :source ~/.vimrc
4. Test connection: :GuardrailTestConnection
5. Validate file: :GuardrailValidate

Troubleshooting

"Command not found"

• Plugin not loaded - check installation path
• Run :scriptnames to verify plugin loaded

"Connection failed"

• Check MCP server is running
• Verify g:guardrail_server_url
• Check :messages for errors

No diagnostics showing

• Check g:guardrail_project_slug is set
• Verify file is within project scope
• Check g:guardrail_severity_threshold

Compatibility

• Vim 8.0+ with +job support (for async)
• Vim 7.4+ (sync only)
• Neovim 0.3+