agentscan

agentscan docs

agentscan 2.0.0 audits agent configuration on disk — 143 checks. Scans are read-only and never open a network connection. Spec-required checks cite a published spec line; heuristics stay at info and are labeled. Full behavior lives in the README.

Quickstart

Run against any project. It reads that project, writes nothing, and never leaves your machine.

npx

cd ~/your-project
npx @chimix/agentscan@latest
# or explicitly:
npx @chimix/agentscan check

bunx

bunx --bun @chimix/agentscan
# or after install:
bun add -d @chimix/agentscan
bunx agentscan check

From a checkout

git clone --depth=1 https://github.com/SimaAlexandru99/agentscan
cd agentscan && bun install
bun run src/cli.ts check ~/your-project

The package is scoped @chimix/agentscan because npm rejects the bare name. The command you type stays agentscan.

Flags for check

FlagMeaning
--jsonJSON report (alias for --output json)
--output <format>human (default) · json · prompt
--copyAlso copy the report to the system clipboard
--no-colorNever colour, even on a terminal (NO_COLOR=1 does the same)
--quietSummary line only
--verboseShow KEEP + info-severity findings, and print each finding's id
--fail-on <level>never (default) · warning · error
--fail-under <0-100>Fail when the score drops below this floor
--globalAlso open documented user locations: Claude, Codex, Command Code, Cursor hooks and mcp.json, Gemini settings, Copilot mcp-config.json, Kiro, Devin CLI, Antigravity, and Cline, Roo, Kilo, and Junie skill directories. The README coverage matrix lists every path.
--config <path>Config file path

2.0.0 accepts only printed rule ids in ignoreRules, ignoreFindings, and explain. thresholds.skillDescriptionBytes and thresholds.skills are rejected; the listing budget is thresholds.skillListingChars.

v1 does not write the tree — no apply, no skill delete/install. Findings may suggest shell commands; you run them yourself.

Skill

Agents forget the audit. Copy skills/agentscan into the project so they run it before editing hooks or claiming a guard is on.

cp -R skills/agentscan .cursor/skills/agentscan
# or: .agents/skills/agentscan
# or: .claude/skills/agentscan

When

  • Hook, skill, MCP, or AGENTS.md work
  • Someone says a guard is on and you have not verified the script
  • A PR touches .claude/, .agents/, .mcp.json, or skills-lock.json

Do

From the repo root. Findings are facts. Do not skip claude.hook.missing-script (error).

npx @chimix/agentscan@latest --output prompt

No project handy — demo builds a throwaway fixture, prints the report, and deletes it:

npx @chimix/agentscan@latest demo

Don't

  • Write the scanned tree
  • Guess with the model whether a hook is valid
  • Compare a skill's frontmatter name to its directory, or validate model ids

CI

The Action runs from its own checkout, so it uses the ref you pin rather than whatever is on npm:

- uses: SimaAlexandru99/agentscan@v1
  with:
    fail-on: error        # never | warning | error
    output: human         # human | json | prompt

Or run it directly:

- name: agentscan
  run: bunx agentscan check --fail-on error

Default failOn is never so local runs stay non-blocking until you opt in.

← Back to agentscan