Claude Code

Configuration debugging and the .claude directory

Diagnose CLAUDE.md, settings, hooks, MCP, skills, permissions, local directories, data flow, and cleanup.

When rules are ignored, hooks do not run, MCP is missing, or skills/settings do not apply, inspect what Claude Code actually loaded instead of guessing.

#Start with these commands

Command	Inspect
/context	System prompt, memory, skills, subagents, MCP, messages
/memory	Loaded CLAUDE.md, rules, and auto memory
/skills	Project, user, and plugin skills
/hooks	Registered hooks and events
/mcp	Servers, connections, and approvals
/permissions	Sources of allow/ask/deny rules
/doctor	Schema, installation, duplicate subagent names
/status	Settings sources, policy, login, model
/debug <problem>	Enable logs and investigate with Claude

#Configuration locations

File	Purpose	Commit?
CLAUDE.md	Project conventions and commands	Yes
.claude/CLAUDE.md	Additional project memory	Yes
.claude/settings.json	Shared settings, permissions, hooks	Yes, without keys
.claude/settings.local.json	Personal project overrides	No
~/.claude/settings.json	User preferences, environment, permissions	No
.mcp.json	Project MCP servers	Yes, use environment references for secrets
~/.claude.json	App/login/project state and some MCP data	Do not hand-edit business settings here
.claude/commands/	Slash commands	Yes
.claude/skills/<name>/SKILL.md	Project skill	Yes
.claude/agents/	Custom subagents	Yes
.claude/output-styles/	Output styles	Project or user scope

~/.claude.json is not a settings file. Put permissions, hooks, and env in settings.json.

#Settings merging and precedence

Ordinary precedence:

Managed policy.
Command-line configuration; individual flags/environment variables have feature-specific precedence.
Project local settings.
Shared project settings.
User settings.

Permission lists merge. Conflicts follow deny → ask → allow, not simple replacement.

Symptom	Cause	Fix
User setting ignored	Project local key overrides it	Inspect /status sources
Hook absent	Written into a separate file or ~/.claude.json	Put it under hooks in settings
MCP absent	.mcp.json placed inside .claude	Move project MCP definition to repository root
MCP lacks environment	Settings env differs from server process configuration	Define server env in .mcp.json
Skill absent	Stored as .claude/skills/name.md	Use name/SKILL.md
Subdirectory memory absent	Loaded on demand	Read a file in that directory

#CLAUDE.md does not apply

/memory
/context all

If absent, check its location and launch directory. If present but ineffective, rules may be vague, conflicting, or too long.

More reliable instructions:

Name the actual test command.
State directory ownership, such as React components in src/components.
Enforce restrictions with permissions/hooks instead of prose alone.
Split large repositories by directory instead of making the root file encyclopedic.

#Hooks do not trigger

/hooks
claude --debug hooks

Symptom	Cause
Missing from /hooks	Settings not loaded or wrong key
Matcher misses	Case-sensitive tool name; use Bash, Edit, Write
Multiple-tool matcher fails	Use one regex string such as Edit	Write
Schema error	/doctor reports it and the hook is discarded
Unstable path	Use CLAUDE_PROJECT_DIR or an absolute path
Wrong exit behavior	Follow the event's JSON/stderr contract

#MCP is missing

claude mcp list
claude mcp get <name>
claude --debug mcp

Symptom	Action
Project server pending approval	Approve in /mcp
Server failed	Inspect stderr, command, args, env
Connected with zero tools	Reconnect and inspect debug output
OAuth failure	claude mcp login <name>
Relative paths fail in some directories	Use absolute paths
Many tools disrupt caching	Use supported tool search or split servers

#Compare against clean configuration

Safe mode disables most customizations:

claude --safe-mode

If the problem disappears, investigate CLAUDE.md, skills, plugins, hooks, MCP, custom commands, agents, output styles, and workflows.

For a clean directory:

mkdir -p /tmp/claude-clean
cd /tmp
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Notes:

Managed policy may still apply.
macOS credentials may remain in Keychain rather than being isolated by CLAUDE_CONFIG_DIR.
Linux/Windows may require credentials again; Passion8 uses its gateway variables.

#Organize .claude

Recommended layout:

.claude/
  settings.json
  settings.local.json
  commands/
    review.md
  skills/
    release-check/
      SKILL.md
  agents/
    qa-reviewer.md
  output-styles/
    concise.md

Avoid	Reason
.claude/.mcp.json	Project MCP belongs at repository root
.claude/skills/foo.md	A skill requires a directory and SKILL.md
.claude/hooks.json	Ordinary hooks belong in settings; plugins can have separate hook files
Real keys in project settings	Project files are easy to commit accidentally

#Data flow and local data

Claude Code sends required prompts, tool results, file excerpts, and MCP output to the selected provider. With Passion8, also consider gateway logging, billing, and retention policies.

Data	Location/destination	Consideration
Project files	Enter context after reads	Restrict sensitive paths
User settings/state	~/.claude and ~/.claude.json	Do not commit
Shell output	Current session context	Avoid secrets and excessive logs
MCP output	Current session context	Filter database/browser results
Telemetry	Controlled by OTel environment	Avoid raw API bodies
WebFetch domain checks	May use a safety check service	Account for outbound domains

For stricter projects:

Deny Read on .env and .env.*.
Ask or hook-check curl, wget, and database writes.
Never print full keys in hook stderr.
Collect only necessary monitoring fields; avoid OTEL_LOG_RAW_API_BODIES.

#Cache effects

Debugging often changes prompt prefixes:

Action	Effect on five-minute / one-hour caching
New session after editing CLAUDE.md	Changed prefix usually creates a cache entry
Change permissions	Often small, but changed tool availability can alter prefixes
Add/remove MCP server	Changed schemas can miss
Add/remove skills/plugins	Instructions or tools can change
Safe mode	Different prefix; unsuitable for normal hit-rate evaluation
Clean config directory	Useful diagnosis, not representative project caching

#Official references

PreviousInstallation and login troubleshooting NextCommand reference

Support

Need help?

For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

WeChat / QQ support is available at the bottom right.