# agentdoctor

> A linter for AI coding-agent configuration (.claude settings, hooks, permissions, MCP servers, skills, subagents, memory files). 72 rules across correctness, security, cost, hygiene, policy. Zero dependencies, no network calls, MIT. CLI: `npx @jqntn/agentdoctor`; machine-readable via `--json` (schema: https://jqntn.github.io/agentdoctor/schemas/report.schema.json), `--sarif`, `--list-rules --json`, `--explain <rule-id>`. Exit codes: 0 clean, 1 errors, 2 usage.

## For agents: audit and adopt

To audit a project: run `npx @jqntn/agentdoctor . --no-user --json`. Findings are sorted most-severe-first; each has `file`, `line`, `configPath` (the exact config key), `snippet` (the offending value, secrets redacted), and `help` (the fix). Apply fixes by editing the file at that location, then verify with `npx @jqntn/agentdoctor . --no-user --quiet` (exit 0 = clean). Suppress an intentional finding with an `agentdoctor-disable <rule-id>` comment in that file; never delete a deny rule to silence a finding.

To install permanently (each command writes one file, refuses to overwrite, safe unattended):

- `npx @jqntn/agentdoctor --init-ci` - GitHub Actions workflow: SARIF PR annotations + error gate
- `npx @jqntn/agentdoctor --init-skill` - installs the config-audit skill (audit-and-fix workflow + per-rule fix recipes) into this project
- Claude Code plugin (global): `/plugin marketplace add jqntn/agentdoctor` then `/plugin install agentdoctor` - adds the skill everywhere, invokable as /agentdoctor:config-audit
- `npx @jqntn/agentdoctor --init-agents` - adds a marked audit section to AGENTS.md, read by OpenAI Codex, Cursor, Gemini CLI and other coding agents
- `npx @jqntn/agentdoctor --write-baseline .agentdoctor-baseline.json` - only if findings exist today

## Docs

- [Getting started](https://jqntn.github.io/agentdoctor/docs/getting-started.md)
- [Configuration](https://jqntn.github.io/agentdoctor/docs/configuration.md)
- [Rule reference](https://jqntn.github.io/agentdoctor/docs/rules.md)
- [CI setup](https://jqntn.github.io/agentdoctor/docs/ci.md)
- [Baselines](https://jqntn.github.io/agentdoctor/docs/baselines.md)
- [Team policy](https://jqntn.github.io/agentdoctor/docs/policy.md)
- [Output formats](https://jqntn.github.io/agentdoctor/docs/output.md)
- [Programmatic API](https://jqntn.github.io/agentdoctor/docs/api.md)
- [For agents](https://jqntn.github.io/agentdoctor/docs/agents.md)
- [Architecture](https://jqntn.github.io/agentdoctor/docs/architecture.md)
- [FAQ](https://jqntn.github.io/agentdoctor/docs/faq.md)
- [Privacy](https://jqntn.github.io/agentdoctor/docs/privacy.md)

## Optional

- [Full documentation in one file](https://jqntn.github.io/agentdoctor/llms-full.txt)
- [Policy file JSON Schema](https://jqntn.github.io/agentdoctor/schemas/policy.schema.json)
- [Report JSON Schema](https://jqntn.github.io/agentdoctor/schemas/report.schema.json)
- [Repository](https://github.com/jqntn/agentdoctor)