agentcurfew doctor

agentcurfew doctor finds configuration that agents ignore or that does not do what it seems to: a file with the wrong name or key, a setting that another file overrides, a deprecated format. Every finding names its source.

Levels: error (it does not work), warning (it probably does not), info. The command exits with 1 at --fail-on, or doctor.failOn of the policy, or warning by default.

invalid-policy

agentcurfew.policy.json follows the schema. Level error.

A policy that does not follow schema.json is not applied: agentcurfew scan, lock and verify stop instead of guessing what it meant. Every problem is listed with the path to the field.

Fix: Correct each field named; the schema describes every setting, and editors that read $schema can check the file as it is typed.

Sources: https://unpkg.com/agentcurfew/schema.json.

unparsable-config

Every agent configuration file can be parsed. Level error.

Lists configuration files and frontmatter that are not valid JSON, TOML or YAML. agentcurfew reads nothing from such a file, so none of its components are checked or locked, and an agent that reads it may ignore all of it or refuse to start.

Fix: Correct the syntax of the file; the agent's own error message usually names the line.

Sources: https://www.rfc-editor.org/rfc/rfc8259, https://toml.io/en/v1.0.0, https://yaml.org/spec/1.2.2/.

misnamed-file

No file is named almost like one an agent reads. Level warning.

Looks in the folders where agents read configuration (the project root, .claude, .cursor, .vscode, .gemini, .github and the others of the knowledge base) for files whose name is close to one an agent reads, but not the same: a different case, a different extension (.jsonc for .json) or one or two letters off. The agent ignores such a file without a word.

Fix: Rename the file to the name the agent reads, or delete it.

Sources: the knowledge base entries named in each finding.

wrong-servers-key

MCP files use the key their agents read. Level error.

VS Code reads servers in .vscode/mcp.json, while .mcp.json and most other agents use mcpServers and Codex uses mcp_servers. A file written with the key of another format lists no server for the agents that read it.

Fix: Rename the top-level key to the one the agent reads; the message names it.

Sources: the knowledge base entries named in each finding.

missing-mcp-type

Remote servers in .mcp.json say their type. Level error.

Claude Code reads an entry of .mcp.json with no type as a local stdio server, so a remote server given only a url never connects. The knowledge base records this from the MCP page of Claude Code.

Fix: Add "type": "http" (or "sse" for an older server) to the entry.

Sources: https://code.claude.com/docs/en/mcp.

local-overrides-project

No project file silently overrides another. Level warning.

Reports a permission setting written with different values in two project files of the same agent, such as .claude/settings.local.json and .claude/settings.json, and names the file that wins by the agent's documented precedence. The other value looks set but has no effect. Lists, which some agents merge across files, are not compared.

Fix: Keep the setting in one file, or make sure the winning value is the one meant; settings.local.json is usually not committed, so it differs between machines.

Sources: the knowledge base entries named in each finding.

conflicting-mcp-server

No MCP server is defined twice in different ways. Level warning.

Reports a server name defined in two project files that the same agent reads, with different definitions. Which one wins is not documented for every agent, so the server that runs may not be the one reviewed.

Fix: Keep one definition, or give the servers different names.

Sources: the knowledge base entries named in each finding.

deprecated-format

No deprecated file or setting is used. Level warning.

Reports files and settings that the agent's own documentation or code calls legacy or deprecated, as listed in the knowledge base: for example .cursorrules for Cursor and tools.exclude for Gemini CLI. They may stop working in a new version without notice. A deprecation known only from code is reported as info.

Fix: Move the content to the replacement named in the message.

Sources: the knowledge base entries named in each finding.

unknown-hook-event

Every hook names an event its agent knows. Level warning.

Reports hooks filed under an event name that none of the agents reading the file lists in the knowledge base, such as post-tool-use for PostToolUse. Claude Code skips such entries ("only individual entries fail, such as a malformed permission rule or an unknown hook event name"), so the hook never runs and the check it was meant to make does not happen.

Fix: Rename the event to one the agent lists; the message names the closest one.

Sources: https://code.claude.com/docs/en/settings.

stale-policy-entry

Every entry of the policy still matches something. Level info.

Reports exceptions that match no finding, and entries of skills.allowSources and mcp.allowServers that match no skill or server of the project. A stale entry is harmless today, but allows whatever matches it later without a review.

Fix: Remove the entry, or narrow it to what the project uses.

Sources: https://unpkg.com/agentcurfew/schema.json.

agentcurfew-hook-missing

The agentcurfew hook finds agentcurfew. Level warning.

The hook that agentcurfew init --hook writes runs node_modules/agentcurfew/dist/cli.js of the project. When that file is missing, because agentcurfew is not a dev dependency or the dependencies are not installed, node cannot start it and Claude Code goes on without the check, so writes to agent files are no longer asked about.

Fix: Install agentcurfew as a dev dependency (npm install --save-dev agentcurfew) and run the install before starting the agent, or remove the hook.

Sources: https://code.claude.com/docs/en/hooks.

depcurfew-hook-missing

A project with depcurfew.json has the depcurfew hook. Level warning.

The project has a depcurfew policy, but the Claude Code settings of the project have no depcurfew hook, so the agent can install packages without depcurfew checking them first. agentcurfew does not check installs: that is the hook of depcurfew.

Fix: Add the hook from the README of depcurfew (section Claude Code) to .claude/settings.json; it runs next to the agentcurfew hook.

Sources: https://github.com/DevXord/depcurfew#claude-code.

depcurfew-hook-broken

The depcurfew hook finds depcurfew. Level warning.

The depcurfew hook runs node_modules/depcurfew/dist/cli.js of the project. When that file is missing, the hook checks nothing; with onFailure "block" it instead blocks every command of the tools it covers, including the install that would bring depcurfew.

Fix: Install depcurfew (npm ci, or npm install --save-dev depcurfew) before the agent starts, as the README of depcurfew describes, or fix the path in the hook.

Sources: https://github.com/DevXord/depcurfew#claude-code.

hooks-disabled

No project setting turns the hooks off. Level warning.

disableAllHooks set to true in a Claude Code settings file of the project turns off every hook of the user, the project, local settings and plugins, the status line and the file suggestion command, for everyone who opens the repository. Hooks that guard the agent, such as the ones of depcurfew and agentcurfew, then check nothing, while their entries still look in place. It is an error when the same file holds such a hook.

Fix: Remove disableAllHooks from the project settings. To turn hooks off for one run, pass --settings '{"disableAllHooks": true}' instead.

Sources: https://code.claude.com/docs/en/settings-reference#disableallhooks.