Skip to main content
Glama
context-canvas-check

context-canvas-check

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

Check

What won't apply

agent-not-loaded

Agent files Claude Code skips: frontmatter that doesn't parse or isn't closed, --- not on line 1, a name with :, no description, hooks written as a list

agent-unknown-field

Agent fields Claude Code ignores, such as allowed-tools where tools is meant, which leaves the agent with every tool

agent-reference-unresolved

A skill's agent: that doesn't resolve, including bare names for plugin agents, which are namespaced

settings-in-parent-folder

.claude/settings.json in a parent folder, which isn't loaded when a session starts in a subfolder

mcp-enabled-and-disabled

An MCP server listed as both enabled and disabled; disabled wins

allow-rule-protected-path

Allow rules for protected paths (.claude/, .git/, .husky/, .zshrc, ...), which pre-approve nothing

single-slash-path

Read(/Users/...): one leading slash anchors at the settings source, not the filesystem root

ask-rule-overrides-hook

Ask rules that still prompt when a PreToolUse hook allows the call

nested-claude-md

Subfolder CLAUDE.md files, which load only after Claude reads a file in that folder

config-drift

Hooks, permission rules, MCP servers and agents added, removed or changed since your last baseline

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: mcpscan

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.

Client

Setup

Claude Code

claude mcp add context-canvas-check -- npx -y context-canvas-check mcp

Cursor

.cursor/mcp.json: {"mcpServers": {"context-canvas-check": {"command": "npx", "args": ["-y", "context-canvas-check", "mcp"]}}}

VS Code

.vscode/mcp.json: {"servers": {"context-canvas-check": {"type": "stdio", "command": "npx", "args": ["-y", "context-canvas-check", "mcp"]}}}

Codex

~/.codex/config.toml: [mcp_servers.context-canvas-check] with command = "npx" and args = ["-y", "context-canvas-check", "mcp"]

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

Path

What

packages/cli

The CLI, the MCP server and the Claude Code plugin

packages/core

The checks, as pure functions

docs/research

The evidence behind every check

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Diagnose MCP servers — health checks, tool testing, token cost audits, conflict detection, and security scanning with 50+ prompt injection patterns. Works as CLI or MCP server inside Claude Desktop.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A read-only MCP server that lets an agent audit its own environment by discovering local MCP configurations and skill folders on Windows, macOS, and Linux and running offline static checks for prompt injection, hidden instructions, hardcoded secrets, dangerous commands, unpinned packages, and excessive filesystem or transport permissions. It exposes tools to scan everything discovered, list configurations, vet a single skill, or analyze supplied text, returning text, JSON, SARIF, or HTML findings with CI-friendly severity levels.
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an agent or MCP client to scan MCP server configs and AI-agent tool manifests on demand, exposing tools that list detection rules and report hidden prompt injections, data-exfiltration attempts, embedded secrets, deceptive Unicode, unpinned packages and shell-launching tools. Each finding comes with a severity and location so risky tool descriptions can be caught before an attacker exploits them.
      28 PyPI
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to inspect and diagnose their own MCP setup by exposing read-only tools that audit configured servers, report which coding agents have configs, surface misplaced or duplicated registrations, and list curated preset packs. It also powers CLI workflows for checking handshake, tool lint, and tool-surface quality scores of any stdio server.
      32 npm
      MIT