agentscan

agentscan docs

agentscan 1.4.0 audits agent configuration on disk — 103 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 scan ~/.claude/skills, ~/.codex/skills, ~/.commandcode/skills, and ~/.agents/skills
--config <path>Config file path

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