Claude Code · Part 8

Claude Code — Part 8 — Common Claude Code Issues and Fixes

A standing reference for the runtime problems that show up after installation: settings that will not apply, hooks that never fire, sluggish performance, and the diagnostic commands that narrow any of it down fast.

By K Shankar R Karanth AI Tools Series Part 8

Quick idea: Almost every “Claude ignored my config” problem traces back to a file loading from the wrong place, a hook matcher written incorrectly, or one settings scope silently overriding another.

/doctor

Automated setup checkup: installation health, invalid settings files, duplicate names, proposed fixes.

/context

Shows exactly what loaded into the current session, broken down by category.

–safe-mode

Launches with every customisation disabled, the fastest way to confirm whether your setup is the cause.

Introduction

Part 2 covered installation problems. This post picks up where that one leaves off: Claude Code runs fine, but something you configured, a CLAUDE.md rule, a hook, a permission, does not seem to be doing what you expected. This is a reference to come back to, not something to read start to finish.

Start Here: Diagnostic Commands

Before assuming a bug, check what Claude Code actually loaded. These commands answer that directly, inside a running session.

Command	Shows
`/context`	Everything occupying the context window: system prompt, memory files, skills, subagents, MCP tools
`/memory`	Which CLAUDE.md and rules files actually loaded
`/hooks`	Every active hook, grouped by event
`/mcp`	Connected MCP servers and their status
`/permissions`	Resolved allow and deny rules currently in effect
`/doctor`	Setup checkup with proposed fixes; run `claude doctor` from the shell if a session will not even start
`/status`	Which settings sources are active, including whether managed settings apply

Key rule: If a file is missing from /memory or /hooks, Claude Code never read it. Fix the location before suspecting the content.

Configuration Not Applying

Most configuration surprises come down to a small set of location and syntax mistakes.

Symptom	Likely Cause	Fix
Hook never fires	`matcher` is a JSON array instead of a string	Use one string with `\|` to match multiple tools: `"Edit\|Write"`, not `["Edit","Write"]`.
Hook never fires	`matcher` value is lowercase, such as `"bash"`	Matching is case-sensitive. Use the real tool name: `Bash`, `Edit`, `Write`, `Read`.
Hook never fires	Hooks were written to a standalone file instead of `settings.json`	There is no separate hooks file for project or user config. Hooks live under the `"hooks"` key inside `settings.json`.
Permissions, hooks, or env variables set globally are ignored	Configuration was added to `~/.claude.json` instead of `~/.claude/settings.json`	`~/.claude.json` holds app state and UI toggles, a different file. `permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`.
A setting in `settings.json` seems ignored	The same key is also set in `settings.local.json`	Local overrides project, which overrides user. Check the more specific scope first.
Skill does not appear in `/skills`	File is at `.claude\skills\name.md` instead of inside a folder	Use a folder with `SKILL.md` inside it: `.claude\skills\name\SKILL.md`.
Skill appears but Claude never invokes it on its own	The skill has `disable-model-invocation: true`, or the description does not match how you phrase the request	Check the badge in `/skills`. A “user-only” label means only `/name` triggers it, by design.
Subdirectory CLAUDE.md instructions seem ignored	Subdirectory files load on demand, not at session start	They load only once Claude reads a file in that subdirectory, not when the session launches.
A deny rule like `Bash(rm *)` does not block a destructive command	Prefix rules match the literal command string, not the underlying executable, so `/bin/rm` or `find -delete` slip past	Add explicit patterns for each variant, or use a PreToolUse hook for a real guarantee instead of a permission rule.

Performance and Stability

Symptom	Likely Cause	Fix
High CPU or memory on a large codebase	Context has built up over a long session	Run `/compact` regularly, restart between major tasks, and add large build directories to `.gitignore`.
`Autocompact is thrashing` error	A file or tool output immediately refills the context window right after compaction	Ask Claude to read the oversized file in smaller chunks, or move the work to a subagent so it runs in its own context.
Session seems frozen	A command is genuinely stuck	Press Ctrl+C to cancel. If unresponsive, close the terminal and restart; run `claude --resume` in the same directory to pick the session back up.
Garbled text in an editor’s integrated terminal	The terminal’s GPU renderer is misrendering glyphs	Run `/terminal-setup` inside Claude Code to turn off GPU acceleration for the integrated terminal.
File search or `@file` mentions find nothing	The bundled ripgrep binary is not running on this system	Install ripgrep for your platform (`winget install BurntSushi.ripgrep.MSVC` on Windows) and set `USE_BUILTIN_RIPGREP=0`.
Fewer search results than expected on WSL	Cross-filesystem disk read penalties when the project lives under `/mnt/c/`	Move the project to the Linux filesystem, or run Claude Code natively on Windows instead.

Testing Against a Clean Configuration

When a problem is hard to pin down, rule out your own configuration entirely rather than guessing which file is responsible.

# Launch with every customisation disabled: CLAUDE.md, skills,
# plugins, hooks, MCP servers, custom commands and agents
claude --safe-mode

If the problem disappears in safe mode, something in your setup caused it, and the tables above narrow down which surface to check. If it persists even there, point Claude Code at an empty configuration directory entirely.

# Bypass everything under the usual config directory
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Important: Managed settings deployed by an organisation still apply in both safe mode and a clean config directory, since they live at a system path outside the user’s own configuration.

Final Thoughts

Nearly every configuration problem in Claude Code is a location or syntax issue, not a mysterious bug: a file in the wrong place, a matcher spelled wrong, or two scopes disagreeing about the same key. The diagnostic commands exist specifically to make that visible instead of guessable, and --safe-mode is the fastest way to confirm whether the problem is your setup at all.

With installation and everyday configuration covered, the last piece of the foundations series is connecting Claude Code to systems outside your local machine.

Key takeaway: Run /context, /memory, or /hooks before assuming a bug. If the file or hook is not listed there, Claude Code never loaded it, and that is almost always a location or syntax problem you can fix in seconds.

Next in this series

Next, we connect Claude Code to systems outside your local machine with MCP: what it is, how to add a server, and what it actually buys an IT engineer.