All Commands

npx asen init

Initializes Agentinel in your project. Auto-detects installed AI agents and writes the appropriate hook configurations. Also installs a Git pre-commit hook that scans your staged lockfile on every commit.

Flags

Example output

$ 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

Exit codes

Notes

• Running asen init multiple times is safe. It will merge hook config rather than overwrite it.
• The Git pre-commit hook calls npx asen check on every commit. This adds ~100ms to commit time.
• asen init respects the .agentinel.json mode setting when writing the hook runner command.

npx asen init --no-shim

Runs the standard init flow to wire up agent hooks and git hooks, but skips installing the global PATH shim that wraps package manager binaries.

Example output

$ npx asen init --no-shim
wrote .agentinel.json
registered the Claude Code PreToolUse hook in .claude/settings.json
installed the git pre-commit hook in .git/hooks

agentinel is set up. New npm packages will be checked before they land.
Default mode is strict. Set "mode": "warn" in .agentinel.json to only warn instead.

Exit codes

Notes

• The shim modifies your shell profile (~/.zshrc, ~/.bashrc, etc.) to prepend ~/.agentinel/bin to your PATH.
• If you want to manually revert the hook changes later, you can run npx asen uninstall.

npx asen check

Scans your staged lockfile dependencies against the OSV database and heuristics. Designed for use in CI/CD pipelines and Git pre-commit hooks. Exits with code 1 if any flagged packages are found.

Flags

Example output

$ npx asen check
checked 142 package(s), nothing suspicious

Exit codes

Notes

• When run in a CI environment (CI=true), output is automatically formatted for log readability.
• The pre-commit hook installed by asen init runs this command automatically on every git commit.
• Packages in your allowlist are skipped and counted as clean.

npx asen check <package-name>

Instantly scans a single named package against the OSV database and heuristics. Useful for quickly checking a package before manually installing it, or for scripting package validation.

Flags

Example output

$ npx asen check react-router-v7-fake
⚠️ agentinel warning: react-router-v7-fake is 1 day old and has 4 downloads.
This matches the profile of a slopsquatting or malicious package.

Exit codes

Notes

• This command makes one npm registry call to resolve the latest version number if --version is not specified.
• All other data (OSV lookup, heuristics) is resolved locally from the bundled DB.
• For unknown packages (ghost packages), the check exits immediately with a BLOCK signal.

npx asen allow <package-name> --reason <reason>

Adds a package to the allowlist in .agentinel.json with a required reason string. The entry includes an audit trail (who added it and when) and is committed to version control so the team has visibility.

Flags

Example output

$ npx asen allow my-internal-pkg --reason "Internal company package not on public npm"
allowlisted my-internal-pkg in .agentinel.json

Exit codes

Notes

• The --reason flag is required. Running asen allow without it will print an error and exit with code 1.
• The addedBy field is populated from git config user.email. If git is not configured, it falls back to the system username.
• Allowlisted packages bypass both OSV matching and heuristic checks, except for npm takedown markers, which always block regardless of the allowlist.

npx asen mode <warn|strict>

Switches Agentinel's operating mode in the .agentinel.json file.

Example output

$ npx asen mode strict
set mode to strict in .agentinel.json

Exit codes

npx asen uninstall

Completely removes all Agentinel hooks from your repository config files (.claude, .gemini, .github, etc.) and removes global shims.

Example output

$ npx asen uninstall
agentinel has been completely uninstalled from this repository.

Exit codes

npx asen unshim

Removes the global PATH shim installed by asen init --shim. Cleans up the shim binary and removes the PATH entry from your shell profile. The real package manager binaries are restored to their original positions.

Flags

Example output

$ npx asen unshim
removed /Users/user/.agentinel/bin
removed the PATH line from /Users/user/.zshrc

Exit codes

Notes

• Always use asen unshim rather than manually deleting the shim binary. Manual deletion leaves a dangling PATH entry in your shell profile.
• After running unshim, restart your shell session or source your shell profile for the change to take effect.
• asen unshim has no effect if the shim was never installed.