The Claude Code Config Ecosystem — What’s Out There and What I Built

Here’s something you figure out about 3 hours into serious Claude Code usage: it has no memory.

Not “bad memory.” Not “spotty memory.” No memory. Every new session starts with a blank context window. If you were halfway through refactoring an authentication middleware, and the context compacted, or you closed the terminal, or you went to lunch — it’s gone. Your AI collaborator has the continuity of a goldfish with amnesia.

The natural reaction is “well, I’ll just tell it what we were doing.” But that’s like saying you’ll just re-explain the last 3 hours of context from memory. Your memory is also terrible. You just don’t like admitting it.

So you build infrastructure. And that infrastructure turns out to be the single highest-leverage investment in the entire workflow.

I’ve spent an unreasonable amount of time on this. 69 tracked files. 13,869 lines. One initial commit. Turns out I’m not the only one — there’s a whole ecosystem of people doing the same thing, and the approaches are wildly different. Some people built 100-agent marketplaces. Some built auto-learning reflection loops. I built something more like an operating system.

Here’s what the landscape looks like, where my setup fits in it, and what it actually looks like when the whole thing fires in production.

The ~/.claude/ directory — what lives there

The ~/.claude/ directory is where Claude Code stores its brain. Every session starts by reading CLAUDE.md from this directory (or from the repo root, or both). But CLAUDE.md is just the entry point.

The official stuff — things Claude Code creates or expects:

• CLAUDE.md — your instructions file. Claude reads this every session.
• commands/ — slash commands. Each .md file becomes /user:name.
• settings.json — permissions, MCP servers, model preferences.
• projects/ — per-project session state (auto-managed, don’t touch).
• plugins/ — MCP server plugins (also auto-managed).
• skills/ — marketplace skills.

The community stuff — directories that have become conventions without being official:

• agents/ — subagent persona definitions. “You are an architect who thinks about…”
• hooks/ — event hooks triggered on tool calls, commits, etc.
• rules/ — glob-scoped rules files like python-style.md.

My custom addition:

• memory/ — modular config. More on this in a second.

Here’s what my actual ~/.claude/ looks like:

~/.claude/
├── CLAUDE.md              # 26 lines — just @imports
├── agents/                # 8 subagent personas
│   ├── architect.md
│   ├── engineer.md
│   ├── pm.md
│   ├── researcher.md
│   ├── blogger.md
│   ├── ghostwriter.md
│   ├── advisor.md
│   └── codebase-researcher.md
├── commands/              # 30+ slash commands
│   ├── commit.md
│   ├── recover.md
│   ├── handoff.md
│   ├── plan-work.md
│   ├── review-pr.md
│   ├── learn-repo.md
│   └── ...
├── memory/                # 10 modular config files
│   ├── identity.md
│   ├── communication.md
│   ├── subagents.md
│   ├── quality-assurance.md
│   ├── security.md
│   ├── git-conventions.md
│   ├── project-conventions.md
│   ├── session-protocol.md
│   ├── web-search.md
│   └── paths.md
├── scripts/               # Helper scripts
├── skills/                # 5 skills
├── settings.json
└── settings.local.json    # Machine-specific overrides

The modular memory system

Most people have one big CLAUDE.md. It starts small, grows to 500 lines, becomes unmaintainable, and you can’t tell which instructions are about git conventions vs. security vs. how you like your Slack messages drafted.

My CLAUDE.md is 26 lines:

# Claude Code User Configuration

Modular config in `memory/` subdirectory.

---

@./memory/identity.md
@./memory/paths.md
@./memory/communication.md
@./memory/git-conventions.md
@./memory/web-search.md
@./memory/subagents.md
@./memory/quality-assurance.md
@./memory/project-conventions.md
@./memory/session-protocol.md
@./memory/security.md

The @ syntax is Claude Code’s file import — each reference pulls in a separate file. Each file owns one concern:

• identity.md — who I am, my co-author line, path variables
• communication.md — tone rules (Sapolsky mode — dry wit, no corporate fluff), bilingual triggers for when English is ambiguous, Slack assistance preferences
• subagents.md — the whole delegation framework: scope checks, cognitive trap detection, context economics, the virtual feature crew model
• quality-assurance.md — review protocols, verification hierarchy, planning workflows
• security.md — confirmation gates, secret hygiene, dangerous command detection
• git-conventions.md — commit format, PR conventions, cross-repo work
• session-protocol.md — what to do at session start, during, end, and after compaction

The biggest file is subagents.md at ~415 lines. It defines a weighted scope-check system where Claude evaluates every task before starting — if the weighted steps add up to 3 or more, it delegates to a subagent instead of doing the work itself. There’s cognitive trap detection, context economics reasoning, and an iterative orchestration pattern with fresh agents per revision cycle.

I haven’t seen anyone else structure their config this way. The @ import syntax is underused — most people either dump everything into one file or use the rules/ glob pattern. Modular memory sits in between: organized by concern, individually maintainable, but loaded as one coherent instruction set.

Session recovery — the layered system

The no-memory problem isn’t just annoying. It’s the reason you need all the infrastructure above. And the solution turns out to be surprisingly simple: session recovery is a file system problem, not a memory problem. If the right files exist in the right places, a brand-new context window can reconstruct working state in seconds.

The system has five layers, but most of the time you only touch one.

Layer 1: /user:recover — the command you actually use. It detects whether you’re in a git repo or a ClaudeProject and reads the appropriate state. For repo work (90% of the time), it reads git status, recent commits, and local config. For project work, it reads the bootstrap file and project structure. One command. Full context.

Layer 2: SESSION-BOOTSTRAP.md — only for multi-session project work (design documents, long-running investigations). ~20 lines of current state: what you’re building, where the specs live, what task you’re on, what to do next. Generated by /user:handoff, not maintained by hand.

Layer 3: The project structure — specs/, plans/, DECISIONS.md, LESSONS.md, research/. Each directory has a lifecycle. Specs go from draft → review → approved → executing → complete. Plans track tasks with checkboxes that persist across sessions. Research captures dead ends so you don’t re-explore them. This is session-resilient state management — every piece of context that matters lives in a file a fresh context window can read.

Layer 4: The handoff protocol — /user:handoff at end of session updates the bootstrap, records next actions, gets reviewed by subagents (PM for framing, Researcher for context sufficiency), and archives previous state to HISTORY.md. The review step catches “obvious” context that a loaded window thinks is redundant to record but will be completely missing next time.

Layer 5: Mid-session compaction — the most brutal scenario. Context compacts while you’re working. Protocol: run /user:recover. Trust the bootstrap file or git state. No re-exploring, no “what were we doing?”

The whole system exists because of a deeper insight: human working memory and AI context windows fail in remarkably similar ways. Both lose context after interruptions. Both are overconfident about what they’ll remember. Both resist building external memory systems because “I’ll remember.” The entire field of personal knowledge management — from GTD to Zettelkasten — exists because human working memory is unreliable. AI context windows are unreliable in the exact same way. We just haven’t internalized it yet.

A real example: understanding a CI thread at speed

All of this sounds like infrastructure for its own sake until you watch it work. So here’s what happened today.

A Slack thread dropped in one of our CI channels — seven messages, multiple teammates, about why CI didn’t catch a Rocket config error before it hit production. The kind of thread where you need to understand the conversation fast, extract the actual technical issue, and figure out what to do about it. In English. Under time pressure.

I pointed Claude at the thread. It fetched all seven messages and presented them verbatim — each one in English with Chinese translation side by side. This is communication.md in action: it knows I’m an ESL speaker with ADHD, and that when time pressure hits, bilingual output cuts the cognitive load of parsing a fast-moving English discussion. I didn’t ask for bilingual mode. The config triggers it automatically when it detects urgency.

From those seven messages, Claude extracted the core issue: CI’s dependency checker only looks at Python imports, but the Rocket config test loads configs by glob/name, not by import. So when someone changes a config file, the dependency checker doesn’t see a connection to the config test, and the test doesn’t get triggered. The fix: explicit yolo.ci dependency annotations.

Two config files interact there — identity.md (knows my role, my team, which CI system I care about) and communication.md (knows the bilingual triggers, the Slack thread summarization format, the “lead with the decision or action item” rule). Neither file is long. They just encode the right defaults so I don’t have to specify them every time.

Then I asked something that sounds trivial but reveals the whole point of the session recovery system: “How do I refer to this conversation from another session?” Because tomorrow, or next week, when someone asks about the Rocket config CI gap, I need to pick up where I left off. The answer isn’t a session ID — Claude Code doesn’t have persistent session references. The answer is the handoff file. Deposit the context into SESSION-BOOTSTRAP.md, and any future session can reconstruct it. The files are the memory. The AI is just the CPU.

That’s the infrastructure doing its job invisibly. No ceremony, no extra steps. Just config files that know who I am, how I process information, and where to put things so I can find them later.

The scope myth

Now here’s the trap that stops people from building any of this.

“It’s just a small task. I don’t need a plan file.”

“I’ll remember what I was doing. I don’t need to update the bootstrap.”

“This is a quick fix. I’ll skip the handoff.”

This is the scope myth — the persistent delusion that the current task is smaller than it actually is, and therefore doesn’t need the infrastructure you built for “real” work.

Every cognitive trap has linguistic fingerprints:

Here’s the heuristic that catches them all:

“Am I about to explain why this task is small?”

If yes, that explanation IS the cognitive trap.

Genuine small tasks don’t need justification. If you’re mentally arguing for why something is trivial, your subconscious already knows it isn’t.

Consider this scope assessment:

Task: Clean up old config file
Steps: 1 read (1.0) + 2 edits (1.0) = 2.0
Trap check: "Cleanup" framing detected — add 1.0 correction
Corrected total: 3.0
Decision: DELEGATE (crosses complexity threshold)

The word “cleanup” itself triggered a weight correction. Not because cleanup tasks are always complex, but because the framing is doing persuasive work — packaging the task as smaller than its actual content warrants.

And there’s a useful economic framing for this: think of context as a budget. Direct work = paying cash from your wallet. Every file you read, every exploration — that’s context spent from a finite window. Delegation (to subagents, to files, to future sessions) = paying with someone else’s budget. A 10-step task done in the current context costs 10 steps. Delegated, it costs ~2 (spawn + receive). That’s 80% savings.

The session recovery system is essentially a context bank. You deposit state into files during the session and withdraw it cheaply in the next one. The scope myth is what makes you think you don’t need to make deposits.

What the community is building

The ecosystem has exploded. Here’s what matters if you’re configuring Claude Code seriously.

Tier 1: Bookmark these

Tier 2: Interesting patterns

Tier 3: Reference material

Community hubs: r/ClaudeAI (very active config sharing), HN threads on “CLAUDE.md” (high-signal), VoltAgent Discord (the subagent community), Smithery.ai (plugin marketplace).

Two philosophies of memory

There are two competing approaches to how Claude should remember things.

1. Memory bank files (the centminmod pattern). Explicit files like CLAUDE-activeContext.md at your project root, updated via commands. Manual, deliberate, version-controlled. You decide what’s worth remembering.

2. Self-learning / reflection (the claude-reflect pattern). Hooks auto-capture when Claude corrects itself or when you correct Claude. The config evolves without you touching it.

I’m in the first camp, but more extreme. My memory files aren’t just “things to remember” — they’re an operating system. The subagent framework has weighted scope checks, cognitive trap detection, context economics. The quality assurance module has verification hierarchies and mandatory review workflows. It’s not “here’s what I prefer” — it’s “here’s how to think about your own reasoning.”

The second approach is interesting and I’m jealous of it. Hooks are the one major thing from the ecosystem that I don’t have yet. The idea that your config gets smarter over time, automatically, is genuinely compelling. But I worry about drift — what happens when auto-captured corrections contradict each other?

Breadth vs. depth

Most popular repos are breadth plays. “Here’s 112 agents! 146 skills! 72 plugins!” And they’re genuinely useful — you browse them, find the 3-4 things you actually need, adapt them. wshobson/agents has a three-tier model strategy that’s clever. everything-claude-code covers more languages than I’ll ever touch.

My setup is a depth play. 8 agents instead of 112 — but those 8 form a virtual feature crew with defined interaction patterns. 30 commands instead of 146 — but they’re wired into a coherent workflow (plan → review → commit → handoff). 10 memory modules instead of one big file — but each one encodes operational principles, not just preferences.

The unique stuff I haven’t seen elsewhere:

• Weighted scope checks with cognitive trap detection. Every task gets a weight estimate. Cross the threshold, Claude delegates. And a trap detector catches rationalizations like “this is just a quick fix.”

• Context economics as a first principle. The main session’s context window is scarce. Subagent windows are abundant. “Direct work = paying with cash. Delegation = paying with someone else’s budget.”

• Iterative orchestration with fresh agents. Revisions get a new agent, not the same one trying again. A loaded context creates blind spots — the agent that wrote version 1 sees what they meant, not what they wrote.

• Three-tier location separation (tool / work / reference). ~/.claude/ is how Claude thinks. $CLAUDE_PROJECTS is what Claude produces. $CLAUDE_CONFIG is what Claude knows about your repos. No single failure takes out everything.

• The modular memory pattern itself. Using @ imports to split config by concern.

What the community has that I don’t: hooks. The infrastructure-showcase repo makes a compelling case for skill auto-activation based on file type or directory. And claude-reflect’s self-learning loop is an idea I keep meaning to steal.

Version-controlling your AI’s brain

Here’s something most people don’t think to do: version-control ~/.claude/ with git.

Not all of it — there’s a lot of runtime junk. The .gitignore is surgical:

# Runtime / ephemeral
projects/
cache/
paste-cache/
file-history/
debug/
shell-snapshots/
session-env/

# Logs & telemetry
history.jsonl
statsig/
stats-cache.json

# Machine-specific
settings.local.json

# Auto-managed
plugins/

What gets tracked: memory modules, commands, agents, skills, scripts, settings. The stuff that represents decisions about how the tool should work.

Why bother?

• Rollback. When a config change makes Claude behave weirdly, git diff shows exactly what changed.
• History. The evolution of your instructions — what you added, removed, rewrote three times.
• Portability. Clone to a new machine, entire personality comes with it.
• Auditability. 13,869 lines is a lot. Git blame tells you when and why each section was added.

There’s something deeply right about version-controlling the instructions you give your AI assistant. Configuration as code, taken to its logical conclusion.

Building this for yourself

You don’t need all of this at once. The system has a natural adoption curve.

Day 1: Just use /user:recover. Build a recovery command that reads git state — branch, recent commits, local config. Run it at session start. This alone saves 10-20 minutes per session.

When git isn’t enough: At some point you’ll hit multi-session work where git state isn’t sufficient context. That’s when you create the project structure with SESSION-BOOTSTRAP.md, specs/, plans/, DECISIONS.md. Commands handle maintenance — you don’t update these files by hand.

Week 2: Handoffs and reviews. Start using /user:handoff at end of sessions. The key insight: a loaded context window doesn’t realize what “obvious” context will be missing in the next session. Fresh reviewers do.

Ongoing: Scope checking. Start noticing when you use minimizing language. Ask: “Am I explaining why this is small?” This one never fully resolves — the trap is hardwired. But awareness reduces its hit rate.

The structural advice:

1. Read “Writing a Good Claude.md” first. 748 HN points for a reason.
2. Browse awesome-claude-code for 20 minutes. Pick 2-3 things that match your workflow.
3. Start with one file, split when it hurts. When you’re scrolling past git instructions to find communication preferences, that’s when you split into modules.
4. Version-control early. git init in ~/.claude/ on day one.
5. Separate your tool from your work. Don’t put project artifacts in ~/.claude/.
6. Subagents are the multiplier. A single session with good instructions is useful. A session that knows when to delegate is dramatically more useful.

The ecosystem is moving fast — star counts from this post will be outdated in a month. But the structural patterns (modular config, separation of concerns, delegation frameworks, version control) are stable. Build on those.

The infrastructure you build before you need it is invisible when it works. You never see the session recovery that went smoothly — you just start working. You never notice the scope check that correctly flagged a “quick fix” as complex — you just avoid the 2-hour rabbit hole. The benefits are counterfactual. You’re preventing futures that never happen.

But the cost of not building it is viscerally concrete. The 20-minute context reconstruction. The “wait, where was I?” after lunch. The “quick cleanup” that ate an afternoon. The session that compacted right when you finally understood the bug.

Build the infrastructure. Your future context window will thank you for it — silently, invisibly, by simply continuing to work without interruption. Which is the whole point.