How to Add AI Agent Safety to Neovim

SafeClaw by Authensor adds deny-by-default action gating to AI agents operating within Neovim. Whether you use Copilot, CodeCompanion, or a custom LLM plugin, SafeClaw intercepts agent actions, enforces your policy, and writes every decision to a hash-chained audit log. It supports both Claude and OpenAI providers and is verified by 446 tests.

Prerequisites

• Neovim 0.9+ with Lua configuration
• Node.js 18+
• A plugin manager (lazy.nvim, packer, or similar)

Step 1: Install SafeClaw

Open your terminal and run:

npx @authensor/safeclaw

This creates the .safeclaw/ directory with a default policy and audit store. SafeClaw runs as a sidecar process that your Neovim plugins communicate with.

Step 2: Configure SafeClaw in Your Neovim Init

Add the following to your ~/.config/nvim/lua/plugins/safeclaw.lua (or equivalent in your plugin setup):

return {
  {
    "authensor/safeclaw.nvim",
    config = function()
      require("safeclaw").setup({
        enabled = true,
        policy_path = vim.fn.getcwd() .. "/.safeclaw/policy.yaml",
        audit_log = true,
        hash_chain = true,
        notify_on_deny = true,
        float_window = true,
      })
    end,
  },
}

The float_window option displays SafeClaw deny/prompt decisions in a floating window rather than the command line, keeping your workflow clean.

Step 3: Write Your Policy File

Create .safeclaw/policy.yaml in your project:

version: 1
default: deny

rules:
  - action: file.read
    paths:
      - "src/**"
      - "lua/**"
    decision: allow

- action: file.write
    paths:
      - "src/**"
    decision: prompt

- action: shell.execute
    decision: deny

- action: network.request
    domains:
      - "api.openai.com"
      - "api.anthropic.com"
    decision: allow

Step 4: Add Keybindings for Audit Commands

Add these keybindings to your Neovim configuration for quick access to SafeClaw operations:

vim.keymap.set("n", "<leader>sa", function()
  vim.cmd("!npx @authensor/safeclaw audit --tail 10")
end, { desc = "SafeClaw: Show recent audit log" })

vim.keymap.set("n", "<leader>sv", function()
  vim.cmd("!npx @authensor/safeclaw audit --verify")
end, { desc = "SafeClaw: Verify audit chain" })

vim.keymap.set("n", "<leader>ss", function()
  vim.cmd("!npx @authensor/safeclaw status")
end, { desc = "SafeClaw: Show status" })

Press sa to see the last 10 audit entries, sv to verify the hash chain integrity, and ss to view the current policy summary.

Step 5: Integrate with Telescope (Optional)

If you use Telescope for fuzzy finding, add a SafeClaw audit log picker:

vim.keymap.set("n", "<leader>sf", function()
  require("telescope.builtin").live_grep({
    cwd = vim.fn.getcwd() .. "/.safeclaw",
    prompt_title = "SafeClaw Audit Search",
  })
end, { desc = "SafeClaw: Search audit logs" })

This lets you search through all audit log entries using Telescope's fuzzy matching interface.

Step 6: Test the Setup

Open Neovim in a project directory that has a .safeclaw/policy.yaml and trigger an AI agent action. For example, ask your AI plugin to write a new file outside the permitted paths. SafeClaw should deny the action and display a notification. Confirm the log entry:

npx @authensor/safeclaw audit --tail 3

You should see a deny decision with the action type, target path, timestamp, and hash chain reference.

Summary

SafeClaw integrates into Neovim through Lua configuration, keybindings, and optional Telescope integration. The deny-by-default model keeps AI agents locked down until you explicitly permit actions. Hash-chained audit logs provide tamper-evident records of every decision. SafeClaw is MIT licensed and open source.

Related Guides

• How to Add AI Agent Safety to Emacs
• How to Run AI Agents Safely from the Terminal
• How to Add AI Agent Safety to VS Code
• How to Send AI Agent Safety Alerts to Slack