context-canvas-check

Does your Claude Code configuration actually apply?

Claude Code silently skips an agent file whose frontmatter is broken. It ignores a misspelled field, and it never loads project settings from a parent folder. context-canvas-check finds these, tells you what won't apply and why, and gives your coding agent the fixes: as a prompt, through a Claude Code plugin, or as an MCP server any agent can call.

npx context-canvas-check

From a real repository:

context-canvas-check · ~/code/my-project
76 errors, 28 notes

ERROR  Agent file Claude Code skips: 67 files
  Why: YAML error: the frontmatter block is not closed with ---.
  Fix: Add a closing --- line after the last frontmatter field.
  Docs: https://code.claude.com/docs/en/sub-agents
  Files:
    .claude/agents/analysis/code-analyzer.md
    ...

28 notes not shown (28 × Agent frontmatter field Claude Code ignores). Add --notes to list them.

What it checks

Every check traces to evidence. Each one maps to a public report of someone hit by the problem, and to Claude Code's documentation, linked in every finding. We tested whether this was worth building before building it: see the two pre-registered studies.

Related MCP server: mcp-permaudit

Fix it with your coding agent

npx context-canvas-check --prompt | pbcopy

--prompt turns the findings into instructions for Claude Code, Cursor or any other coding agent. Each problem comes with why, the fix and the docs link. Where the fix is mechanical, the exact edit (on line 4, replace allowed-tools: Read, Grep with tools: Read, Grep); where it's a choice, an instruction to ask first. No model writes the prompt: it's built from the findings by fixed rules, so the same findings always give the same text.

In Claude Code

/plugin marketplace add ianmacdowell13-byte/context-canvas-check
/plugin install context-canvas-check@context-canvas

The plugin:

• checks at session start, and tells Claude about errors and drift;

• checks each config file Claude edits. When the edit won't apply, Claude sees why and fixes it;

• adds the MCP server below, so Claude can check the project and get the fixes when asked.

For any agent: the MCP server

npx -y context-canvas-check mcp

Three read-only tools over stdio: check_config (findings as JSON, with exact edits), get_fix_instructions (the fix prompt, ending with "call check_config again to confirm") and explain_check. Without a path, they check the client's workspace root. They change nothing, not even the drift baseline, and send nothing.

In CI

npx context-canvas-check --no-user --strict

Exit codes: 0 with no errors, 1 with errors (or with warnings under --strict), 2 for usage errors. Add --json for machine-readable output.

Privacy

• Local only. The CLI, the plugin and the MCP server read files on your machine and send nothing anywhere.

• The drift baseline lives in ~/.context-canvas/. It holds rule names, hook commands and hashes, never secret values.

Limits

• Claude Code only.

• No managed settings or runtime state. Use /status, /hooks and /context in a session for what actually loaded.

• Behavior can change. Rules reflect Claude Code's documentation as of v2.1.283.

Repository

Licensed under Apache-2.0. See CONTRIBUTING.md and SECURITY.md.