# 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](https://github.com/SimaAlexandru99/agentscan#readme).

## Quickstart

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

### npx

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

### bunx

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

### From a checkout

```bash
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

| Flag | Meaning |
| --- | --- |
| `--json` | JSON report (alias for --output json) |
| `--output <format>` | human (default) · json · prompt |
| `--copy` | Also copy the report to the system clipboard |
| `--no-color` | Never colour, even on a terminal (NO_COLOR=1 does the same) |
| `--quiet` | Summary line only |
| `--verbose` | Show 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 |
| `--global` | Also 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.

```bash
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).

```bash
npx @chimix/agentscan@latest --output prompt
```

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

```bash
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:

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

Or run it directly:

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

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