⚙️ ccinspect

Claude Code Configuration Inspector

A CLI tool that inspects, validates, and visualizes Claude Code configurations across all layers (enterprise, user, project-shared, project-local) — and cross-references them against actual runtime behavior.

Scan · Lint · Blame · Audit · History · Diff · Restore · Recover

---

Goal of the project

Provide Claude Code users with full visibility and confidence that their configuration is correct, conflict-free, efficient, and behaving as intended — like a linter + debugger for your Claude Code setup.

The problem it solves

Claude Code has a complex, layered configuration system — settings files, CLAUDE.md memory files, rules, agents, skills, commands, MCP servers, hooks, and plugins — spread across multiple locations with precedence-based merging. As projects grow, it becomes hard to:

• Know what's actually in effect after all layers merge
• Spot contradictions between levels (e.g., allow at user level, deny at project level)
• Detect dead config (rules with globs matching nothing, orphan agents)
• Understand token budget impact (how much context is consumed at startup)
• Verify that configuration behaves as intended at runtime

Claude Code uses 30+ config files across 7+ locations — and when they conflict, debugging is painful.

ccinspect fixes that with next capabilities:

🔍 Discover — finds every config file across all scopes and shows sizes, tokens, git status 🧹 Lint — runs 52 rules catching security gaps, dead references, conflicts, and bloat 📋 Evidence — see exactly which lines triggered each detection 🔗 Blame — shows the effective config after all layers merge, with origin tracking and precedence badges ⚖️ Compare — diffs configurations across projects side-by-side 🗺️ Graph — visualizes config dependency graph with orphan and broken reference detection 🔬 Audit — cross-references your config against actual Claude Code runtime behavior 🩺 Diagnose — detects write-blindness, ghost agents, orphan confirmations, unused config 💰 Economics — token usage, cache efficiency, API-equivalent cost per session 📜 History — reconstructs config change timeline from git, transcripts, and disk — zero installation 🔀 Diff & Restore — compare any two config versions and roll back with lineage-aware ancestry 🔄 Recover — generates a paste-ready recovery prompt from interrupted sessions

Fully offline. No API keys. No hooks to install. Just point it at a project.

Quick start

npm install -g ccinspect

Restart Claude Code. That's it — ccinspect auto-registers as an MCP server.

Ask Claude Code naturally:

• "Check my config for issues"
• "Which agents are actually being used?"
• "Run a full health check"

Manual registration: cci setup or claude mcp add --scope user ccinspect -- npx -y ccinspect mcp serve

Without installing: npx ccinspect scan / npx ccinspect lint

Tip: cci and ccinspect are interchangeable — use whichever you prefer.

MCP integration

ccinspect exposes 8 tools via MCP (Model Context Protocol) so Claude Code can call them directly:

Tool	What it does
health_check	All-in-one: lint + scan + audit + history in a single call
lint	Run 52 rules against your config
scan	Discover all config files
audit	Config utilization from session transcripts
history	Config version timeline
diff	Compare two config versions
restore	Roll back to a previous version
blame	Show effective merged config with origins

The health_check tool groups findings per config file and surfaces co-occurrence patterns — ideal for Claude Code to diagnose and fix issues in one pass.

What it catches

$ cci lint

Settings (3 issues)
  ⚠ [settings/sandbox-recommended]     Sandbox is not enabled
  ⚠ [settings/deny-env-files]          Missing deny rules for .env files

Rules (3 issues)
  ⚠ [rules-dir/contradiction-keywords] Potential contradiction between rules
    │ architecture.md:100  "server components by default"
    │ frontend.md:46       "separate server components from client components"

Agents (2 issues)
  ✖ [agents/frontmatter-valid]         Missing required name field
  ℹ [agents/orphan-agent]              3 agents never referenced

Git (1 issue)
  ⚠ [git/local-settings-tracked]       settings.local.json tracked in git

$ cci audit

Agents     3 configured · 1 delegated · 2 never delegated
  ✓ test-runner     1 delegation across 1 session
  ○ nlp-reviewer    0 delegations (44 sessions searched)

MCP Servers   1 configured · 3 used
  ✓ taskmaster-ai   1 tool call
  ? deepwiki        2 tool calls (not in current config)

Discrepancies
  ℹ Agent "test-runner" bypassed in 9 of 10 matching sessions
    Matched commands: pytest
    → Add "MUST BE USED" to agent description

Static lint catches config mistakes. Runtime audit catches config that doesn't work in practice.

Runtime analysis

# What config was actually used? Any issues?
cci audit

# Session statistics and token costs
cci logs stats
cci logs stats --cost

# Recover from an interrupted session
cci session-recover

Fully offline. Reads Claude Code's existing session data. No hooks to install.

Config versioning

# See full config change history (from git, transcripts, and disk)
cci history CLAUDE.md

# Compare any two versions
cci diff v3 v8 CLAUDE.md

# Compare a version to current disk state
cci diff v5 current .claude/settings.json

# Roll back to a previous version
cci restore v3 CLAUDE.md

Zero installation. Reconstructs history retroactively from git commits and Claude Code session transcripts on first run.

Which command do I need?

cci scan — "What do I have?" — Discovers every config file across all scopes, shows sizes, token counts, and git status. Flags when a user-level file is shadowed by a project-level equivalent. Doesn't look inside files — just the inventory.

cci lint — "What's wrong?" — Runs 52 rules checking for dead globs, contradictions, dangerous permissions, oversized files, stale imports, and more. The quality gate.

cci blame — "What's actually in effect?" — After all layers merge, shows which permissions apply, which env vars win, which MCP servers are active — and which file is responsible. The answer to "I set X but it's not working."

cci graph — "How do things connect?" — Which agents reference which skills, which rules apply to which paths, what imports what. The dependency map.

cci compare — "How do two projects differ?" — Side-by-side diff of configurations across directories.

cci audit — "Is my config actually working at runtime?" — Cross-references your static configuration against what actually happened in Claude Code sessions. Shows which agents were delegated to, which rules loaded, which MCP servers were called — and which were never used. Detects write-blindness, ghost delegations, and orphan confirmations. The runtime reality check.

cci logs stats — "What does my Claude Code usage look like?" — Session statistics: tool distribution, file activity, delegations, token usage. Add --cost for API-equivalent pricing breakdown with cache efficiency analysis.

cci session-recover — "My session crashed. What was I doing?" — Parses the last session to extract the task in progress, files modified, last successful checkpoint, and any errors. Generates a paste-ready recovery prompt to continue in a new session.

cci history — "What changed and when?" — Reconstructs config change history from git commits, Claude Code transcript edits, and disk state. Shows a git-log-style timeline with source badges, lineage tracking, and token counts. Zero installation — full history on first run.

cci diff — "What's different between two versions?" — Colored unified diff between any two config versions, including current disk state.

cci restore — "Take me back." — Roll back a config file to any previous version with lineage-aware ancestry. Creates a safety snapshot before writing — nothing is ever lost.

cci session-handover — "Bring a new session up to speed." — Generates a status summary from git diff, test results, and typecheck. Add --transcript for task narrative, tool usage, and git correlation from the previous session.

Commands

Command	Description
cci scan	Discover and inventory all config files with sizes, token counts, and git status. Use --all to include config locations that don't exist yet
cci lint [target]	Run 52 rules — pass a directory or a single config file
cci blame	Show effective config after all layers merge, with origin tracking
cci blame settings	Show raw settings key-value pairs with source badges
cci compare <dir1> <dir2>	Compare configurations across projects side-by-side
cci info	Show runtime info — CLI version, active model, auth method
cci session-handover	Generate status.md from git diff, test results, and typecheck
cci graph	Visualize config dependency graph — text, mermaid, HTML, or JSON output
cci audit	Config utilization audit — which config was actually used at runtime
cci logs stats [--cost]	Session statistics and token economics from transcript data
cci history [path]	Show config version timeline — git-log style with source badges and lineage
cci diff <v1> <v2> [path]	Compare two config versions with colored unified diff
cci restore <version> [path]	Roll back config to a previous version with safety snapshot
cci session-recover	Generate a recovery prompt from the last interrupted session
cci mcp serve	Start MCP server for Claude Code integration (stdio transport)
cci setup	Register MCP server globally — --project for .mcp.json, --status to check

Scan output: When a user-global agent, skill, or command is shadowed by a project-level equivalent of the same name, cci scan dims the entry and marks it (inactive) — so you can see why a global config isn't taking effect.

Single-file mode

Lint individual config files without scanning an entire project:

cci lint CLAUDE.md
cci lint .claude/settings.json
cci lint .claude/agents/researcher.md

The file is auto-classified by name and path. Only rules relevant to that file type run — cross-file and project-level rules are skipped. Output shows the detected type:

⚡ Single-file mode: researcher.md (agent)
  Cross-file and project-level rules skipped

Detected types: memory (CLAUDE.md), settings (settings.json), MCP (.mcp.json), rule (rules/.md), agent (agents/.md), skill (SKILL.md), command (commands/*.md)

What does cci audit find?

cci audit reads Claude Code's session data to answer questions your static config can't. No API keys, no hooks — fully offline.

Are my agents being used?

Agent researcher had 8 delegations across 5 sessions. Agent smith had 0 delegations in 135 sessions — safe to remove.

Are my rules actually loading?

Rule testing.md was loaded in 92/148 sessions. But in 3 sessions, matching files were Edited without being Read first — the rule never loaded.

This is write-blindness: path-scoped rules only load when Claude Reads a matching file. If Claude Edits the file directly, your rule instructions aren't in context. ccinspect is the only tool that detects this.

Which MCP servers are in use?

MCP server github had 34 tool calls. Server filesystem is configured but was never called. Server taskmaster-ai was used at runtime but is not in your current config.

What about Agent Teams?

14 ephemeral agents created via Agent Teams across 3 sessions — shown as an informational summary, not false warnings.

Which files get the most attention?

High-churn files, read-only references, files edited without reading, and test correlation — what percentage of edited source files had corresponding test activity.

How much does it cost?

cci logs stats --cost shows API-equivalent token costs with cache breakdown, startup context analysis, and per-model pricing. Subscription plan users see a note that they're not billed per-token.

Common flags

--project-dir <path>   Target a different project directory
--format json|md       Machine-readable output (default: terminal)
--exclude <glob>       Skip paths from scan/lint
--all                  Show all possible config locations, including files that don't exist yet
-v, --verbose          Expanded output with all issues and full evidence

Rule categories

Category	Rules	What it checks
memory	9	CLAUDE.md quality — size, token budget, imports, sections, stale refs, TODOs
settings	9	Permission security, dangerous allows, field validation, sandbox config
cross-level	4	Conflicts across config layers — permissions, env vars, MCP, plugins
rules-dir	7	Rule file quality — dead globs, overlaps, frontmatter, contradictions, empty/large files, overly-broad globs
agents	5	Agent frontmatter, skill references, description overlap, orphan detection
skills	9	Skill frontmatter, agent references, orphan detection, symlinks, typos, size, naming, descriptions
commands	2	Command frontmatter validity, migration advisory to skills
budget	1	Startup token budget estimation
mcp	2	MCP server environment variable validation, deprecated SSE transport
git	1	Local-only files accidentally tracked in git
plugins	1	Plugin references point to installed plugins
naming	1	Config file casing — detects files Claude Code won't recognize

Configuration

Excluding paths

Create a .ccinspectignore file in your project root (same syntax as .gitignore):

node_modules/
dist/
vendor/

Or use the --exclude CLI flag:

cci lint --exclude "vendor/**"

Advanced config

ccinspect supports .ccinspect.json for rule enable/disable, severity overrides, and threshold tuning. See documentation/configuration.md for the full schema.

What it scans

ccinspect discovers and analyzes these Claude Code configuration surfaces:

• Settings — ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, managed policies
• Memory — CLAUDE.md at enterprise, global, project, local, and subdirectory levels; MEMORY.md auto-memory
• Rules — .claude/rules/*.md (project) and ~/.claude/rules/*.md (user-global)
• Agents — .claude/agents/*.md and ~/.claude/agents/*.md
• Skills — .claude/skills/**/SKILL.md (project) and ~/.claude/skills/**/SKILL.md (user-global)
• Commands — .claude/commands/*.md and ~/.claude/commands/*.md
• MCP — .mcp.json and managed MCP configs
• Hooks — Hook definitions in settings files
• Plugins — Plugin enable/disable across scopes
• Transcripts — ~/.claude/projects/<project>/ JSONL session files (for cci audit, cci logs stats, cci session-recover)

Development

git clone https://github.com/fedius01/ccinspect.git
cd ccinspect
npm install
npm run test
npm run dev -- scan

Project structure

src/
  cli/        CLI entry point and commands
  core/       Scanner, resolver, linter, transcript analyzer engines
  parsers/    Typed parsers for each config format, including JSONL transcripts
  rules/      Individual lint rules by category
  types/      Shared TypeScript interfaces
  utils/      Token counting, git helpers, OS paths, transcript discovery
tests/        Vitest test suite (1500+ tests)
documentation/         Configuration

License

MIT