NativeAIHub
📁

Project Structure

How to organize your Claude Code ecosystem files across global settings, project CLAUDE.md files, and shared resources. The directory layout that makes everything discoverable.

Configuration·2 sections·1 min read
codingworkflowproductivity
Install Prompt

Paste this into Claude Code to set it up:

The Claude Code ecosystem has a clear file hierarchy: ~/.claude/ for global config (agents/, skills/, settings.json), ~/.claude.json for MCP servers, and CLAUDE.md at each project root for project specific instructions. Keep agents and skills in their respective directories, MCP configs in ~/.claude.json, and project context in CLAUDE.md.

01What It Does

Everything has a home

The Claude Code ecosystem spreads across three locations on your machine, each with a distinct purpose. Global configuration lives in ~/.claude/ and ~/.claude.json, covering agents, skills, settings, and MCP servers that apply everywhere. Project specific context lives in the CLAUDE.md file at each project root, giving Claude the knowledge it needs for that particular codebase. Understanding this hierarchy is essential because putting files in the wrong place means they either load everywhere (wasting context) or do not load at all.

02Directory Map

1

~/.claude/ (global directory)

This directory holds everything that applies across all projects. The agents/ subfolder contains your custom agent .md files. The skills/ subfolder contains skill definitions (each in its own subfolder with a SKILL.md). The settings.json file holds permissions, hooks, environment variables, and MCP servers. A continue-prompts/ folder stores session continuation files. This is your personal Claude Code operating system.

2

~/.claude.json (global MCP registry)

A separate JSON file at your home directory root. It stores global MCP server configurations (the tools Claude can connect to in every session) and project specific MCP overrides under the "projects" key. Claude Code also writes session metrics and internal state here. Because of this continuous writing, always edit it with jq commands rather than a text editor.

3

CLAUDE.md (project context)

A Markdown file at the root of each project. This is where you put project specific instructions: coding conventions, architecture decisions, important file paths, build commands, and anything Claude needs to know about this particular codebase. Claude reads this file at the start of every session in that directory. Keep it focused and concise; everything here consumes context tokens.

4

How they interact

On session start, Claude Code loads ~/.claude/settings.json for global defaults, ~/.claude.json for MCP servers, and the project's CLAUDE.md for local context. Settings cascade: global permissions apply everywhere, project settings.json can override them, and CLAUDE.md adds project specific instructions on top. Agents and skills from ~/.claude/ are available in every project. This layered approach means you configure once globally and customize per project only where needed.