CI npm npm bundle size License

Zero-dependency, <2ms safety guardrails for AI agents.

Vigil validates what AI agents do, not what they say. Drop it in front of any tool-calling agent to catch destructive commands, data exfiltration, SSRF, injection attacks, and more — before they execute.

npm install vigil-agent-safety

Or via ClawdHub (for Clawdbot users):

npx clawhub install vigil

import { checkAction } from 'vigil-agent-safety';
const result = checkAction({
 agent: 'my-agent',
 tool: 'exec',
 params: { command: 'rm -rf /' },
});
console.log(result.decision); // "BLOCK"
console.log(result.rule); // "destructive"
console.log(result.reason); // "Destructive command: matched pattern..."

22 battle-tested rules. All pattern-based. All under 2ms.

Existing safety tools (Llama Guard, ShieldGemma) filter content — what agents say. Vigil validates actions — what agents do. Content safety ≠ action safety.

# Check a tool call
npx vigil-agent-safety check --tool exec --params '{"command":"rm -rf /"}'
# JSON output for scripting
npx vigil-agent-safety check --tool exec --params '{"command":"ls"}' --json
# List policy templates
npx vigil-agent-safety policies

Exit codes: 0=ALLOW, 1=BLOCK, 2=ESCALATE

import { checkAction } from 'vigil-agent-safety';
const result = checkAction({
 agent: 'my-agent', // optional
 tool: 'exec', // tool being called
 params: { command: '...' }, // tool parameters
 role: 'developer', // optional
 context: ['...'], // optional
});
// result: { decision, rule, confidence, risk_level, reason, latencyMs }

import { configure } from 'vigil-agent-safety';
configure({
 mode: 'warn', // 'enforce' | 'warn' | 'log'
 onViolation: (result, input) => {
 console.log(`[vigil] ${result.decision}: ${result.reason}`);
 },
});

import { loadPolicy } from 'vigil-agent-safety';
const policy = loadPolicy('moderate'); // 'restrictive' | 'moderate' | 'permissive'
// Or load custom: loadPolicy('./my-policy.json')

See examples/ for complete integration patterns:

• basic.ts — Minimal usage
• express-middleware.ts — HTTP middleware
• mcp-wrapper.ts — MCP server wrapper
• circleci-mcp.ts — CircleCI CI/CD safety (protected branches, secret access, rate limiting)
• langchain-callback.ts — LangChain integration
• openclaw-extension.ts — OpenClaw/Clawdbot agent extension
• generic-hook.ts — Generic before-tool-call hook

Vigil v0.1.0 ships with pattern-based rules — fast, predictable, zero dependencies. Here's what's coming:

• Custom YAML policy files for org-specific rules
• Per-agent permission scoping (agent X can only call tools Y, Z)
• Allowlist/blocklist for paths, domains, commands
• MCP Proxy — drop-in safety layer for any MCP server. Zero code changes, just a config update. Works with Claude Desktop, Cursor, Windsurf, and any MCP client.

• Hosted API with dashboard and warn-mode analytics
• Structured JSON audit logs for compliance
• Team policies with role-based access
• See what your agents are actually doing: "47 risky actions blocked this week across 3 agents"

• Published false positive/negative rates across standard threat datasets
• Optional cloud ML classification for ambiguous cases (rules first, ML as fallback)
• Plugin architecture for custom rule functions
• vigil report CLI for security posture snapshots

• Fine-tuned safety model on HuggingFace for GPU users
• Catches attacks that bypass pattern matching (obfuscation, indirect injection)
• Same API — checkAction() automatically upgrades, no code changes

v1.0 ships when Vigil has 100+ production users, external benchmarks, and proven accuracy. Not before.

Want to influence the roadmap? Open an issue or star the repo to show interest.

Vigil is free and open source. If it saves you time or keeps your agents safe, consider supporting the project:

• ⭐ Star this repo — helps others discover Vigil
• 💖 Sponsor on GitHub — recurring support
• 🪙 Crypto donations:
  • EVM: 0x3AA32976b514F4caaad1e8C69fD55d0E89B50a0e
  • BTC: bc1qzqz9pnrngtq9y4tt9e7vznknxn4dtmphe2pppn
  • SOL: 8ag7B9DvnUdrgmbYnYxhAv25jwcLjzyoWt8uzYGd5XSC

Every bit helps us keep building open source security tools.

Apache 2.0 — Built by HexIT Labs