Getting Started
Introduction
A zero-config, locally-run security guardrail for AI coding agents. No account. No API key. No network calls.
What is Agentinel?
Agentinel is an open-source security tool that sits between your AI coding agent and your package manager. When an agent like Claude Code, GitHub Copilot, or Gemini CLI decides to install an npm package, Agentinel intercepts that decision before npm ever executes it.
It checks the requested package against a bundled local copy of the Open Source Vulnerabilities (OSV) database, which covers 216,000+ known malicious or vulnerable packages. If the package is flagged, Agentinel blocks it, logs the reason, and returns a structured payload back to the agent.
Everything runs entirely offline on your machine. There is no server, no telemetry, and no subscription.
The problem: slopsquatting
Large language models are powerful code generators, but they have a well-documented tendency to hallucinate package names. An LLM might confidently generate an install command for a package that does not exist on the npm registry, like react-router-v7-beta or express-middleware-cors-fix.
This creates a class of attack called slopsquatting: an attacker pre-registers commonly hallucinated package names on npm. When an AI agent installs that package, the attacker's malicious preinstall scripts execute immediately, compromising your development environment before you ever see the output.
Why AI agents are uniquely vulnerable
Traditional developers read package names before running install commands. Agentic workflows execute install commands autonomously, without a human reviewing each one. This removes the last line of defense.
The "Fail Open" philosophy
Agentinel is designed around one core principle: it must never silently break your workflow. If for any reason Agentinel cannot scan a package (corrupted DB, unexpected error), it will fail open, meaning the install is allowed to proceed rather than cryptically blocking your agent.
This is an intentional trade-off. We believe a security tool that breaks builds erodes trust and gets disabled. Agentinel should be invisible when things are fine and loud when there is a real threat.
What "fail open" means in practice
The scanner wraps all OSV lookups and heuristic checks in a try-catch. Any internal exception yields an ALLOW decision with a warning logged to stderr, not a silent failure.
Who is Agentinel for?
Agentinel is for any developer who uses an AI coding agent that can autonomously run shell commands. This includes:
- Claude Code: Anthropic's terminal coding agent. Hooks into PreToolUse events via hooks.json.
- GitHub Copilot CLI: Microsoft's command-line Copilot. Hooks into beforeCommand lifecycle.
- OpenAI Codex CLI: OpenAI's autonomous CLI agent. Hooks into preExec events.
- Gemini CLI: Google's Gemini terminal agent. Hooks into preToolCall events.
If you are running any of these tools with autonomous install permissions, Agentinel is the fastest way to add a meaningful security layer without changing your development workflow.
100% Local
All checks run on-device. Zero network calls at scan time.
Extensive DB
A massive list of malicious and vulnerable packages indexed.
Ultra-low latency
Intercepts are incredibly fast to minimize slowdown.