FAQ#

Is my config uploaded anywhere?#

No. agentdoctor makes zero network calls — no telemetry, no update checks, no license pings. The entire run is local file reads. It also never opens credential files (.credentials.json, .netrc, private keys); they are excluded by path before anything reads them, and the summary reports how many were skipped.

Why did it find nothing?#

Probably because your config is small. A 10-line settings.json with two permission rules has little to get wrong, and agentdoctor is deliberately quiet on healthy setups — the test suite asserts zero findings on a well-configured project. The findings density rises with hooks, MCP servers, subagents, skills, and memory files.

Isn't this just a JSON schema?#

A schema catches type errors. It cannot tell you that Bash(*) is a bad idea, that your hook script does not exist on disk, that your deny rule names a tool that does not exist (and therefore blocks nothing), or that your CLAUDE.md costs real money per month. Most of the catalogue is semantic, not structural.

Why do you report warnings on things that are technically legal?#

Because the failure mode this tool exists for is config that is *legal and inert*. A misspelled hook event is valid JSON. It just never fires, and nothing tells you. When agentdoctor is unsure, it says info; when something is legal but almost certainly not what you meant, warning; when a guardrail provably does nothing or a real hazard is pre-approved, error.

A rule fired on something intentional. What now?#

Suppress it where it fired, visibly:

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

If you believe the rule is wrong in general, that is a bug — false positives are treated as more severe than false negatives. Open an issue with the config that triggered it.

How accurate are the cost estimates?#

The token counts are direct estimates from file size. The money figures are a *model*, and the message says so: they assume the memory file stays prompt-cached (it sits at the front of the prompt, which is exactly the content that caches) and state the request volume they assume. The uncached worst case is also shown where it matters. Assumptions live in src/rules/cost.js where you can disagree with them.

Does it modify my config?#

No. agentdoctor reports; you decide. Every finding includes what to change and why, but the edit is yours. The only file it ever writes is a baseline, and only when you pass --write-baseline.

Which harnesses does it understand?#

The .claude/ configuration surface (Claude Code and compatible tooling), .mcp.json MCP server definitions, and the CLAUDE.md/AGENTS.md memory-file convention. The rule engine is harness-agnostic — discovery is the only layer that knows file layouts — so support for other agent config formats is an issue away.

Does it work on Windows?#

Yes, with one deliberate gap: the two rules that inspect file permissions (security/world-writable-config and the permission half of security/hook-script-not-executable) do nothing on Windows. Node synthesizes POSIX mode bits there — every file reports 0666 — so the check would fire on everything while telling you nothing. Windows ACLs are a different model than this rule can speak to. Every other rule behaves identically across Linux, macOS and Windows, and paths in output always use forward slashes so a baseline recorded on one platform matches on another.

Why Node 20+? Why zero dependencies?#

Node 20 is the oldest LTS with everything the tool needs built in. Zero dependencies is a security decision, not an aesthetic one: a tool that warns you about unpinned supply chains should not install one.

Can I use it as a library?#

Yes — import { run } from '@jqntn/agentdoctor' and you get structured findings. See the API docs, including how to add organisation-specific rules.