Configuration

agentdoctor needs no config file to run. Everything is a CLI flag, an inline comment, or (for team standards) an agentdoctor.policy.json.

CLI reference

Flag	Effect
(default)	Human-readable report, colored when stdout is a TTY
`--json`	Machine-readable findings on stdout (format)
`--sarif`	SARIF 2.1.0 for GitHub code scanning and other CI
`--quiet`, `-q`	Print nothing; rely on the exit code
`--no-color` / `--color`	Force color off/on (also honours `NO_COLOR` and `FORCE_COLOR`)

Flag	Effect
`[path]`	Project root to audit (default: current directory)
`--no-user`	Skip `~/.claude`. Recommended in CI, where user scope does not exist
`--only <cat,...>`	Run only these categories or rule ids
`--disable <id,...>`	Skip specific rules or whole categories
`--min-severity <level>`	`error`, `warning`, or `info` (default)

Categories: correctness, security, cost, hygiene, policy.

agentdoctor --only security,correctness
agentdoctor --disable cost/no-cleanup-period,hygiene
agentdoctor --min-severity warning

Flag	Effect
`--max-warnings <n>`	Exit 1 if more than n warnings (errors always exit 1)
`--baseline <file>`	Suppress findings recorded in the baseline (guide)
`--write-baseline <file>`	Record current findings as accepted

Flag	Effect
`--policy <file>`	Policy file path (default: `agentdoctor.policy.json` at the root)
`--init-policy`	Write a starter policy file (guide)

Flag	Effect
`--init-ci`	Write `.github/workflows/agentdoctor.yml`: SARIF annotations + exit-code gate. Refuses to overwrite.
`--init-skill`	Install the config-audit skill (SKILL.md + fix recipes) for Claude Code. Refuses to overwrite.
`--init-agents`	Add a marked audit section to `AGENTS.md` for Codex, Cursor, Gemini CLI and every other tool that reads it. Creates or appends; refuses to duplicate.
`--badge`	Print README markdown for a badge showing the current grade
`--share`	Print a paste-ready score card: grade, counts, top rule ids. Never includes messages, paths, or snippets, so it is safe to share from private repos. Always exits 0.

Flag	Effect
`--list-rules`	The full catalogue (add `--json` for machine-readable)
`--explain <rule-id>`	What a rule checks, why it matters, how to suppress it
`--version`, `--help`	The usual

Put a comment anywhere in the offending file:

// agentdoctor-disable security/hook-unpinned-path

In JSON config, a comment works (agentdoctor's parser tolerates comments) — or use a string key that contains the directive:

{
  "// agentdoctor-disable security/hook-unpinned-path": "hooks come from vendored bin/",
  "hooks": { }
}

Accepted forms:

Suppressions are file-scoped by design: a suppression you can see next to the code it affects is one a reviewer can question.

To mark a credential-looking string as a deliberate placeholder:

agentdoctor-allow-secret

on the same line as the value.

permissions.deny-style hard skips: credential files are never read, regardless of flags.
--only narrows the rule set first.
--disable removes rules or categories from whatever --only left.
Inline agentdoctor-disable comments suppress findings per file.
--baseline suppresses previously accepted findings.
--min-severity filters what is left.

Suppressed counts are always reported in the summary, so a silenced finding is visible as a number even when its detail is not.