Claude Code, all the layers, in plain English

A friendly walk-through of every file Claude Code looks at, where it lives, how layers stack, and what wins on conflict. Every claim cites the official Anthropic doc URL or the NotebookLM notebook it came from. Use the buttons in the top-right to switch theme or export your notes.

Quick glossary

The big picture — what's where

Two homes. Color coded:

• Blue = user-global (your machine, every project)
• Green = project-scoped (one repo)
• Grey = internal (Claude Code manages it; you don't edit by hand)

The two-tree mental model. Pretty much every Claude Code config file has this same shape: a personal copy at ~/.claude/, a team copy at <project>/.claude/, and sometimes a .local.-suffixed personal-on-this-project copy. The interesting part is what happens when both copies exist — see "Layering rules" below.

The catalog — every file, plain English

Click any row to expand. Required vs optional, locations, tiny example.

# My project

- Always use 2-space indent
- API handlers live in `src/api/handlers/`
- Run `npm test` before committing

{
  "permissions": { "allow": ["Bash(npm test)"] },
  "model": "opus"
}

---
description: Deploy the app to production. Use when user says deploy.
disable-model-invocation: true
---

1. Run tests
2. Build
3. Push to deploy target

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- All endpoints validate input
- Use the standard error format

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "osascript -e 'display notification ...'" }]
    }]
  }
}

{
  "plansDirectory": ".claude/plans"
}

Layering rules — what wins on conflict

This is the hot zone. Different mechanisms have different rules. The quick-reference matrix:

Full details for each row below.

1. CLAUDE.md walk-up — concatenation, not override

Rule: All of these are concatenated, not overridden. Order in context: filesystem root → CWD (most specific last). Most-specific instructions get higher attention because they're nearest the conversation.¹

Conflict? Claude may pick one arbitrarily. Manage it by writing more-specific instructions in deeper-scoped files.

2. @import — relative paths, max 5 hops

• Both relative and absolute paths allowed.¹
• Relative paths resolve from the file containing the import (NOT from CWD).
• @~/path works.
• Max recursion depth: 5 hops.
• First time Claude encounters external imports in a project, it pops an approval dialog. If you decline, imports stay disabled (no nag).

3. Settings — 5 layers, fixed scopes (NO walk-up)

Merge rule:²

• Arrays (e.g. permissions.allow) — concatenated and deduplicated. Lower-priority scopes can ADD without overriding.
• Scalars (e.g. "model": "opus") — highest-priority scope wins. Lower-priority value is ignored.
• Objects — deep-merged (especially in managed-settings drop-ins).

4. Skills precedence — Personal beats Project ⚠️

If a skill name exists in both ~/.claude/skills/ and .claude/skills/, the personal one wins. This is the opposite of "more-specific wins."³

5. Agents precedence — Project beats User ⚠️

For agents, more-specific (project) wins.⁴ Standard intuition. But again — opposite direction from skills.

6. Rules precedence — Project beats User

User-level rules (~/.claude/rules/) load before project rules (.claude/rules/), giving project rules higher priority on conflict.¹ Same direction as agents.

7. MCP scope hierarchy — Local > Project > User

Three scopes; matched by name (or by endpoint URL for plugins/connectors). Local is the default when you run claude mcp add without --scope.⁵

The trap: Local AND User scope MCP servers both live in ~/.claude.json (your home), not in .claude/. Only Project-scope lives in .mcp.json.

8. Hooks layering — all fire in parallel, no override

Hooks live inside settings.json, so they technically inherit settings layering. But the way hooks combine is different from how scalar settings combine.

Rule: when the same hook event has handlers at multiple levels (user, project, local, managed, plus plugin and skill/agent frontmatter), all matching hooks fire in parallel. They merge rather than override. Identical hook commands are auto-deduplicated.¹³

What this means in practice: if you've got a notification hook on Stop in your user settings, and a teammate added a different Stop hook to the project's .claude/settings.json, both fire when Claude stops. Project hooks ADD to user hooks; they don't replace them.

9. Plans (plansDirectory) — single location, configurable

Plan-mode files save to a single directory at a time. Default: ~/.claude/plans/.¹³ You change it with the plansDirectory setting in any settings.json (so the standard 5-layer settings precedence picks the winner — no walk-up, no concatenation across multiple plan directories).

10. Custom commands (~/.claude/commands/ or .claude/commands/)

Still fully supported. Live at user-global OR project. New work should be skills, but old commands keep working.³

Conflict rule: if both a command and a skill share the same name, skill wins.¹³ Otherwise, more-specific (project) wins over user-global for same-name commands.

11. .env loading — varies by tool, not by Claude

Claude Code itself does NOT auto-read any .env file. The ~/.env convention you use (with get-secret) is a community/safety pattern, not a Claude Code feature. Some other CLIs (Gemini CLI specifically) DO read project-level .env directly.⁹

Three concrete scenarios

Walk-throughs so the abstract rules become muscle memory.

Multi-CLI parity (Claude / Gemini / Codex / OpenCode)

If you run multiple CLIs side-by-side, here's the cross-reference.⁹

Other walk-up surprises:

• Gemini's GEMINI.md walks UP and DOWN. CWD up to project root, plus subdirectories down to depth 200. Claude Code only walks up.¹⁴
• Codex walks TOP-DOWN. Project root → CWD, with files closer to CWD overriding. Different mental model from Claude's "ancestors load first."¹⁵
• OpenCode walks up to nearest .git. So your repo boundary is automatic.¹⁶

If you want one source of truth for project context:

• AGENTS.md as a universal context file — adopted natively by OpenCode and Codex. Claude Code does NOT auto-read it,¹ but you can @AGENTS.md from your CLAUDE.md and Gemini's @-import in GEMINI.md to share the same source.

Multi-CLI integration — making them call the same stuff

The parity table above lays out what each CLI looks for. This section answers: can I write something once and have all four CLIs use it? Short version — natively, no. The CLIs do not share directories.⁹ But there are five well-traveled bridge patterns.

Pattern 1 — Symlinks (single source of truth)

Pick one CLI's skill directory as canonical, then symlink the others into it.⁹

# Make Claude's skills the canonical home
mkdir -p ~/.claude/skills
ln -s ~/.claude/skills ~/.gemini/skills
ln -s ~/.claude/skills ~/.codex/skills

Now every skill you author at ~/.claude/skills/<name>/SKILL.md appears in all three CLIs. Same trick works for agents/, rules/ (where the CLI has an equivalent), and any custom config folder.

Caveat: the YAML frontmatter fields differ between CLIs. disable-model-invocation is Claude-specific. A skill that uses Claude-only fields will work in Claude but be partly ignored elsewhere. Keep skills written to the lowest-common-denominator frontmatter (name, description, body) for portability.

Pattern 2 — ~/.agents/skills/ as the universal home (officially recognized by 3 of 4 CLIs)

Updated finding: earlier research called this a community-only convention. Per the dedicated Gemini, Codex, and OpenCode notebooks, all three CLIs natively load skills from ~/.agents/skills/ and walk up to find .agents/skills/ in your project tree.¹⁴¹⁵¹⁶ Only Claude Code doesn't — that's the gap.

Setup: drop a skill at ~/.agents/skills/<name>/SKILL.md. It's instantly visible to Gemini, Codex, and OpenCode. To make Claude see it too, symlink:

ln -s ~/.agents/skills ~/.claude/skills/_shared

Now Claude sees a _shared namespace whose contents are the universal skill set; the other CLIs see them at the canonical ~/.agents/skills/ path.

Trade-off: still need that one symlink for Claude. Frontmatter compatibility caveat from Pattern 1 still applies — Claude-only frontmatter fields are ignored when the same skill loads in Gemini/Codex.

Pattern 3 — AGENTS.md as universal context (the cleanest bootstrap)

Write your shared rules in AGENTS.md at the project root. Then have every CLI's specific file import it.⁹

# In AGENTS.md (the universal source of truth)
- Use 2-space indentation
- API handlers live in src/api/handlers/
- Never commit .env files

# In CLAUDE.md
@AGENTS.md

# Claude-specific instructions below
- Use plan mode for changes under src/billing/

# In GEMINI.md (Gemini reads its own file by default — point it at AGENTS.md)
@AGENTS.md

OpenCode and Codex already use AGENTS.md natively. Claude's @import syntax pulls it into CLAUDE.md.¹ Gemini supports its own @ imports in GEMINI.md. One file, four CLIs.

Pattern 4 — Universal MCP servers

All four major CLIs support MCP.⁹ Instead of writing CLI-specific skills, connect every CLI to the same MCP servers. The capabilities you build live in the MCP server (any language), not in the CLI's skill folder.

• Claude: add to .mcp.json or ~/.claude.json
• Gemini: add to ~/.gemini/settings.json under mcpServers
• Codex: add to ~/.codex/config.toml under [mcp_servers.*]
• OpenCode: add to opencode.json under "mcp"

This is the most portable option for tool-shaped capabilities (database queries, API calls, search). Skills are good for prompts and playbooks; MCP is good for tools.

Pattern 5 — CLI-to-CLI bridge (one CLI as MCP server for another)

Wrap one CLI inside an MCP server so another CLI can call it.⁹ Example: run a tiny gemini_mcp_server.py that exposes a consult_gemini tool, then add it to Claude's MCP. Now Claude can ask Gemini for a second opinion mid-task.

Useful for: validation passes, multi-model voting, model-shopping. Heavier setup than the other patterns but doesn't require you to translate skills across formats.

Power-user orchestrators (mention only)

• Overstory — ov sling <task> --runtime claude|gemini|codex dispatches the same task definition into different CLI runtimes inside isolated git worktrees.⁹
• Bifrost — model routing proxy. bifrost cli --harness codex launches the Codex CLI but routes its API traffic to Anthropic or Google instead of OpenAI.⁹ Useful for keeping the CLI you like but using whichever model is cheapest/best for the task.

Recommendation matrix

Mac↔VPS mirror — what syncs, what doesn't

Your VPS at /home/dev/ mirrors your Mac home. Same shape, different absolute paths. The relative-to-home structure is what matters for muscle memory and scripts.

Heads up — this section is being reworked. P-3's "exact mirror at ~/" assumed each machine's home stays clean enough that "skip OS clutter" is a workable sync rule. The VPS dotfolder reality (24+ folders, mostly machine-specific) disproves that assumption. P-9 proposes a wrapper folder (working name workspace/) as the sync boundary. Tree below shows the P-9 shape; the P-3-flat shape was simpler but doesn't survive contact with real machine state. See D2 above for the full discussion.

Shape parity vs path parity

Two different ways to be "the same":

• Path parity = literal same path. Hard to achieve cross-OS because /Users/coach ≠ /home/dev.
• Shape parity = same folder structure relative to home. ~/workspace/projects/n8n/ on Mac matches ~/workspace/projects/n8n/ on VPS — different absolute paths, same shape.

We chose shape parity. Scripts using ~/workspace/... work on both machines. Scripts using /home/dev/workspace/... only work on VPS.

(Originally locked under P-3 as "exact mirror at ~/" with no wrapper. P-9 reopens this — see D2. The shape-parity principle is unchanged regardless of which option lands.)

What's machine-specific

• .claude/settings.local.json — different per machine by design
• .claude.json — local-scope MCP servers track project paths and per-machine state; do not sync
• ~/.claude/projects/<key>/<session>.jsonl — session transcripts; per-machine (but see below — they CAN be mirrored read-only)
• OS-specific paths inside any setting (e.g., a hook that calls osascript on Mac) — needs a Linux equivalent on VPS

Cross-machine session awareness (new requirement, 2026-05-01)

Goal: each machine should be aware of the other's CC sessions. VPS Claude should be able to comb through Mac sessions, and vice versa. Plus a session-browser web app indexes BOTH + claude.ai web sessions, with filterable tags.

The safe pattern — one-way mirror Mac → VPS, indexer reads from VPS

The session-browser web app indexer scans all three sources and tags each session by:

• Project / CWD — derived from JSONL cwd field, normalized so /Users/coach/X and /home/dev/X map to the same project
• Machine — DEV (VPS), COACH (Mac), or WEB
• App / use context — Cowork, Code, Chat, etc. (manual tag at session-launch, or pattern-derived)

Cheapest first step — a CLAUDE.md hint

Even before sync runs, you can drop a line in each machine's ~/.claude/CLAUDE.md:

# Cross-machine session awareness
The other machine's Claude Code sessions are mirrored read-only at:
  Mac sessions on VPS:  /home/dev/imported-sessions/mac/
  VPS sessions on Mac:  ~/.claude-vps-mirror/  (TBD)

Session-browser web app: https://<your-app>/sessions

Now Claude can find remote sessions on demand (via SSH or local read), even before the indexer is built.

Three decisions to land

D1 — VPS user: keep dev, switch to root, or rename?

Why not root

The "[DEV] Claude Code on VPS" notebook is unambiguous: run Claude Code as a non-root named user with sudo. Running as root gives the AI "master keys" — catastrophic if it hallucinates a destructive command or interacts with malicious code.⁸

This isn't just advice. Claude Code actively refuses to run with --dangerously-skip-permissions if it detects the root user.⁸ That flag is core to autonomous remote operation, so root literally breaks the use case.

Why not rename to coach

• Migration cost is huge — ssh keys, keychain entries, systemd services, tmux sessions, every script that hardcodes /home/dev/.
• Path-string parity isn't the goal — shape parity is. ~/projects/n8n/ works on both machines regardless of the absolute path. Renaming gives you path parity but at high cost — and ~/ already does the same thing more cleanly.
• Username doesn't matter for muscle memory. You almost never type the absolute path. Scripts use ~/ or $HOME.

Pending revision impact

None. Current setup already keeps dev. No new candidate revision needed.

D2 — Wrapper folder: none, dev/, work/, or code/?

Four shapes were on the table:

What changed since v1 of this tutorial

v1 said "P-3 Option A holds: no extra wrapper above ~/projects/." That was based on an assumption that has since broken: you can sync everything in home and just skip OS clutter. New evidence — Jonah's actual VPS state — shows that's not realistic.

The new evidence (VPS dotfolder population)

Jonah's /home/dev/ right now has 24+ dotfolders, almost all machine-specific:

• VPS-only — should NEVER sync to Mac: .pm2/, .dispatch/, .ccgram/, .notebooklm/ (running on VPS), .n8n-mcp/, .copilot/, .gnupg/, .bun/, .dotnet/, .cache/, .local/, .config/, etc.
• SHOULD sync (CLI configs): .claude/, .gemini/, .codex/, .opencode/, .agents/.
• Mac-only visible folders: Documents/, Library/, Music/, Pictures/ — never sync.

P-3 Option A's sync rule becomes: "sync these visible folders + these dotfolders; skip these other dotfolders + Mac clutter." Two maintenance lists, both growing every time you install a tool.

The P-9 alternative — wrapper folder as sync boundary

Move all sync targets into one wrapper. Sync rule collapses to: "sync the wrapper + this small CLI dotfolder allowlist." One growing list, one stable list.

Wrapper name — Jonah's current ranking

Creator-convention evidence

Every successful creator surveyed uses some wrapper — only the name varies:¹⁰

Pending revision impact

P-9 candidate written in pending-revisions.md. architecture-decisions.md NOT edited per the no-silent-rewrites rule. Reviewers asked to weigh in on the wrapper name; everything else in P-9 has solid evidence behind it.

D3 — What's normally at user-home on stock Linux?

Three things to take away

1. A fresh Linux user-home starts much cleaner than a Mac home. Linux doesn't dump Documents/, Library/, Music/, Pictures/ by default — it's just dotfiles. But it doesn't stay clean: every CLI you install drops a dotfolder (.claude/, .gemini/, .codex/, .pm2/, .notebooklm/, .bun/, etc.) plus visible folders for tool data. After a few months it's just as cluttered as a Mac home — see Jonah's actual VPS at 24+ dotfolders. Both machines need a sync strategy that doesn't rely on home staying clean.
2. The filesystem root / is NOT your home. /etc/, /opt/, /var/ are system folders managed by the OS and package manager. Don't put your work there. Don't fight them.
3. The wrapper-folder argument applies on BOTH machines, not just Mac. v1 of this tutorial said the clutter argument was Mac-only. That was wrong — the VPS dotfolder reality disproves it. The cleanest sync rule is "sync the wrapper + an explicit small dotfolder allowlist; everything else stays machine-specific." That's what P-9 proposes (see D2 above).

Files I do not need

Common things that look mandatory but aren't:

• plans/ — only if you use Plan Mode. Plan Mode itself is opt-in (Shift+Tab cycles to it).
• Custom skills — built-in skills (/simplify, /loop, /debug, etc.) ship with Claude Code. You don't need any of your own to start.
• Custom agents — built-in agents (Explore, Plan, general-purpose) cover the common cases.
• Hooks — pure quality-of-life. The Notification hook is nice; everything else is for power users.
• Custom commands — legacy. Skip them; use skills if you need something custom.
• .claude/rules/ — only if your CLAUDE.md is getting too big or you have file-type-specific rules.
• ~/.agents/skills/ — only if you're running multiple CLIs. Gemini, Codex, and OpenCode load skills natively from here; Claude Code doesn't (needs a symlink). If you're CC-only, skip it.
• Auto-memory — Claude writes this itself. You never create or edit it manually. (Toggle with /memory.)

Citations

1. Anthropic — Memory. https://code.claude.com/docs/en/memory (retrieved 2026-04-30). Walk-up rule, @import syntax, CLAUDE.md scopes, AGENTS.md note, .claude/rules/, auto-memory storage location, plan-mode plans/ folder reference.
2. Anthropic — Settings. https://code.claude.com/docs/en/settings. 5-layer precedence (Managed → CLI → Local → Project → User), arrays-merge / scalars-replace / objects-deep-merge, settings.local.json auto-gitignore.
3. Anthropic — Skills. https://code.claude.com/docs/en/skills. Skill folder layout, Enterprise > Personal > Project > Plugin precedence, frontmatter reference, custom-commands-merged-into-skills.
4. Anthropic — Sub-agents. https://code.claude.com/docs/en/sub-agents. Agent precedence (Project priority 3 > User priority 4 > Plugin priority 5), .claude/agents/ walk-up.
5. Anthropic — MCP. https://code.claude.com/docs/en/mcp. Three scopes (Local / Project / User), ~/.claude.json as the home for Local + User scope, .mcp.json as project-only file-based config, approval flow.
6. Anthropic — Hooks. https://code.claude.com/docs/en/hooks. Hooks live in settings.json (any scope), event types, plugin hooks/hooks.json.
7. Anthropic — Common workflows. https://code.claude.com/docs/en/common-workflows. Plan mode, --worktree flag, .claude/worktrees/ directory.
8. NLM — [DEV] Claude Code on VPS (notebook 7db6ea97, retrieved 2026-04-30). Non-root recommendation, --dangerously-skip-permissions root refusal, ~/projects/ structure, worktree project--feature naming convention.
9. NLM — [DEV] Multi-CLI Orchestration (notebook c4acbd14, retrieved 2026-04-30). Side-by-side parity table, .env handling per CLI, AGENTS.md as cross-CLI convention.
10. NLM — [DEV] Claude Code Setup (notebook 42f55c2a, retrieved 2026-04-30). Wrapper-folder recommendation (repositories/, projects/, business/), settings precedence walk-through.
11. Internal research — community patterns. _dev0/migration/review/research/conventions/03-community-patterns.md. Pattern A "Simple Hierarchical" universal across 50+ public repos, Boris Cherny "vanilla setup" quote.
12. Internal research — prior-chat JSONL mined. _dev0/migration/review/research/conventions/00b-prior-chat-jsonl-mined.md L146-177. ~/.agents/skills/ as community/orchestrator universal registry (later confirmed officially recognized by Gemini, Codex, OpenCode — see citations 14-16).
13. NLM — [DEV] Claude Code Advanced (notebook e5664a62, retrieved 2026-04-30). settings.json does NOT walk up (fixed scopes only); skills/agents have intentionally opposite precedence; hooks fire in parallel with dedup; plans is officially documented via plansDirectory setting (default ~/.claude/plans/); custom commands still supported, skill wins on name collision.
14. NLM — [DEV] Gemini CLI (notebook fa8eb9c4, retrieved 2026-04-30). GEMINI.md walks up AND down (subdirs to depth 200); reads .env (CWD up + ~/.env + ~/.gemini/.env); MCP in settings.json at all hierarchy levels merged; skills at ~/.gemini/skills/, .gemini/skills/, AND ~/.agents/skills/, .agents/skills/; agents at ~/.gemini/agents/, .gemini/agents/.
15. NLM — [DEV] Codex CLI (notebook 81d2e6cb, retrieved 2026-04-30). AGENTS.md walks TOP-DOWN (project root → CWD); reads .env; MCP in ~/.codex/config.toml + .codex/config.toml (trusted projects); skills at ~/.codex/skills/ + ~/.agents/skills/ + project .agents/skills/ walked up.
16. NLM — [DEV] OpenCode (notebook cbd59533, retrieved 2026-04-30). AGENTS.md at project root or global; OpenCode walks up to nearest .git; reads .env; MCP in opencode.json "mcp" block; skills at ~/.config/opencode/skills/, .opencode/skills/, plus flexible scanning that picks up .agents/skills/.
17. Web-search corroboration (2026-05-01). DEV.to community thread "What do you call your folder where you keep your code?" + GitHub Folder-Structure-Conventions guide + World Bank style guide. Real-world dev convention clusters on plain functional names: ~/dev/, ~/workspace/, ~/src/, ~/repo/, ~/Developer/.

Verification log with full claim → source mapping: _dev0/migration/review/research/conventions/07-verification-log.md. Contradictions resolved: 06-contradictions.md.