Getting Started

Installation

Get Agentinel running in under two minutes. No account, API key, or server required.

Fully offline setup

Agentinel bundles the OSV database locally. There is no registration, no API key, and no outbound network call at scan time. The package itself is the only thing you need to install.

Prerequisites

Node.js 20 or higher installed on your machine
An npm-based project (package.json must exist)
At least one AI coding agent (Claude Code, Copilot CLI, Codex CLI, or Gemini CLI)

Step-by-step guide

Install the package

Install Agentinel as a dev dependency in your project. It ships with the bundled OSV database, so there are no extra downloads.

npm install --save-dev agentinel

Prefer pnpm or yarn? Both work fine: pnpm add -D agentinel

Run the init command

The asen init command auto-detects which AI agents you have installed and wires up the appropriate hooks. It also installs a Git pre-commit hook to scan your staged lockfile on every commit.

npx asen init

This writes .claude/settings.json (Claude Code), .agentinel.json, and a Git hook to your project root. It also installs a global PATH shim by default.

Verify the setup

After a successful asen init, you should see output similar to:

$ npx asen init

╭─ agentinel ──────────────────────────────╮
│  agentinel setup complete                │
│                                          │
│  New npm packages will be checked before │
│  they land.                              │
│                                          │
│  ✔ wrote .agentinel.json                 │
│  ✔ registered the Claude Code PreToolUse │
│  hook in .claude/settings.json           │
│  ✔ installed the git pre-commit hook in  │
│  .git/hooks                              │
│  ✔ wrote shims for npm, npx, pnpm, yarn, │
│  bun in /Users/user/.agentinel/bin       │
│  ✔ added the shims to PATH in            │
│  /Users/user/.zshrc                      │
│  ✔ Open a new terminal, or run `asen     │
│  unshim` to undo this.                   │
│                                          │
│  Default mode is strict. Set "mode":     │
│  "warn" in .agentinel.json to only warn  │
│  instead.                                │
╰──────────────────────────────────────────╯

Performance Tip:
The hook runs on every command, and resolving through npx each time is slow.
For faster hooks, add it to the repo and run init again:
  npm install --save-dev agentinel && npx asen init

Only the agents you have installed will appear in the hooks list.

Optional: Skipping the PATH shim

By default, asen init installs a global PATH shim that intercepts package manager calls system-wide before forwarding them to the real binaries. If you only want to wire up agent hooks and git hooks, you can skip this.

npx asen init --no-shim

Shim caveat

The PATH shim modifies your shell profile and replaces package manager commands globally. To remove it cleanly, run npx asen unshim.

Optional: CI/CD integration

Use npx asen check in your pipeline to scan staged lockfile dependencies before they land in production. Add it to your CI step:

# GitHub Actions example
- name: Scan dependencies with Agentinel
  run: npx asen check

The command exits with code 1 if any flagged packages are detected, causing the pipeline to fail.

Next steps

Configure Agentinel CLI Reference