How Claude Manages Its Own State

What You'll Learn

You've been writing files that tell Claude what to do (CLAUDE.md, info.md, preferences.md, rules). But Claude Code also maintains its own files behind the scenes. In this lesson, we look at the full configuration picture: what you write, what Claude manages and how it all fits together.

The Three-File Model

Claude Code's configuration comes from three types of files, each with a different purpose:

File	Purpose	Who writes it
CLAUDE.md	Knowledge and instructions (what Claude should know)	You
settings.json	Permissions and behaviour (what Claude can do)	You / your team
claude.json	Machine state (authentication, preferences, caches)	Claude Code (automatic)

CLAUDE.md

You've been building this since Section 3. It holds project context, conventions and instructions. This is where your standards live.

settings.json

This controls what Claude is allowed to do. Permission rules, environment variables, hooks and model selection. It lives at multiple scopes:

• ~/.claude/settings.json for your personal global settings
• .claude/settings.json for project-level settings (shared with team via git)
• .claude/settings.local.json for your personal overrides on a specific project (gitignored)

We'll configure permissions properly in the security section later in the course. For now, just know this is where they live.

claude.json

This file lives at ~/.claude.json. Claude Code manages most of it automatically, but you can also edit it directly, for example to add MCP server configurations that apply across all your projects. It stores:

• OAuth session data
• MCP server configurations
• Per-project tool approvals (what you've said "yes" to)
• Theme and notification preferences
• Various caches

Authentication credentials themselves are stored securely in your system's keychain (macOS Keychain, etc.), not in this file. But if you've ever wondered where Claude remembers that you approved a specific tool in a specific project, claude.json is where.

The Full Picture

Here's everything in one view:

~/.claude.json, Claude Code's auto-managed state

What you write: CLAUDE.md, AGENTS.md, info.md, preferences.md, settings.json, rules What Claude manages: claude.json

Key Takeaways

• CLAUDE.md is for instructions, settings.json is for permissions, claude.json is for state
• You write the first two. Claude manages the third
• settings.json exists at user, project and project-local scopes
• We'll configure permissions in the security section later