Skip to content

claude-global-vs-project-settings.md

Latest commit

 

History

History
248 lines (186 loc) · 10.3 KB

claude-global-vs-project-settings.md

File metadata and controls

248 lines (186 loc) · 10.3 KB

Claude Code: Global vs Project-Level Features

A comprehensive comparison of which Claude Code features are global-only (~/.claude/) versus which have both global and project-level (.claude/) equivalents.

← Back to Claude Code Best Practice Claude

Table of Contents

  1. Overview
  2. Global-Only Features
  3. Dual-Scope Features
  4. Settings Precedence
  5. Directory Structure Comparison
  6. Tasks System
  7. Agent Teams
  8. Design Principles
  9. Sources

Overview

Claude Code uses a scope hierarchy where some features exist at both the global (~/.claude/) and project (.claude/) levels, while others are exclusively global. The design principle: things that are personal state or cross-project coordination live globally; things that are team-shareable project config can live at the project level.

  • ~/.claude/ is your user-level home (global, all projects)
  • .claude/ inside a repo is your project-level home (scoped to that project)

Global-Only Features

These live only under ~/.claude/ and cannot be scoped to a project:

Feature Location Purpose
Tasks ~/.claude/tasks/ Persistent task lists across sessions and agents
Agent Teams ~/.claude/teams/ Multi-agent coordination configs (experimental, Feb 2026)
Auto Memory ~/.claude/projects/<hash>/memory/ Claude's self-written learnings per project (personal, never shared)
Credentials & OAuth System keychain + ~/.claude.json API keys, OAuth tokens (never in project files)
Keybindings ~/.claude/keybindings.json Custom keyboard shortcuts
MCP User Servers ~/.claude.json (mcpServers key) Personal MCP servers across all projects
Preferences/Cache ~/.claude.json Theme, model, output style, session state

Dual-Scope Features

These exist at both levels, with project-level taking precedence over global:

Feature Global (~/.claude/) Project (.claude/) Precedence
CLAUDE.md ~/.claude/CLAUDE.md ./CLAUDE.md or .claude/CLAUDE.md Project overrides global
Settings ~/.claude/settings.json .claude/settings.json + .claude/settings.local.json Project > Global
Rules ~/.claude/rules/*.md .claude/rules/*.md Project overrides
Agents/Subagents ~/.claude/agents/*.md .claude/agents/*.md Project overrides
Commands ~/.claude/commands/*.md .claude/commands/*.md Both available
Skills ~/.claude/skills/ .claude/skills/ Both available
Hooks ~/.claude/hooks/ .claude/hooks/ Both execute
MCP Servers ~/.claude.json (user scope) .mcp.json (project scope) Three scopes: local > project > user

Settings Precedence

User-writable settings apply in this override order (highest to lowest):

Priority Location Scope Version Control Purpose
1 Command line flags Session N/A Single-session overrides
2 .claude/settings.local.json Project No (git-ignored) Personal project-specific
3 .claude/settings.json Project Yes (committed) Team-shared settings
4 ~/.claude/settings.local.json User N/A Personal global overrides
5 ~/.claude/settings.json User N/A Global personal settings

Policy layer: managed-settings.json is organization-enforced and cannot be overridden by local files.

Important: deny rules have the highest safety precedence and cannot be overridden by lower-priority allow/ask rules.

Directory Structure Comparison

Global Scope (~/.claude/)

~/.claude/
├── settings.json              # User-level settings (all projects)
├── settings.local.json        # Personal overrides
├── CLAUDE.md                  # User memory (all projects)
├── agents/                    # User subagents (available to all projects)
│   └── *.md
├── rules/                     # User-level modular rules
│   └── *.md
├── commands/                  # User-level commands
│   └── *.md
├── skills/                    # User-level skills
│   └── */SKILL.md
├── tasks/                     # GLOBAL-ONLY: Task lists
│   └── {task-list-id}/
├── teams/                     # GLOBAL-ONLY: Agent team configs
│   └── {team-name}/
│       └── config.json
├── projects/                  # GLOBAL-ONLY: Per-project auto-memory
│   └── {project-hash}/
│       └── memory/
│           ├── MEMORY.md
│           └── *.md
├── keybindings.json           # GLOBAL-ONLY: Keyboard shortcuts
└── hooks/                     # User-level hooks
    ├── scripts/
    └── config/

~/.claude.json                 # GLOBAL-ONLY: MCP servers, OAuth, preferences, caches

Project Scope (.claude/)

.claude/
├── settings.json              # Team-shared settings
├── settings.local.json        # Personal project overrides (git-ignored)
├── CLAUDE.md                  # Project memory (alternative to ./CLAUDE.md)
├── agents/                    # Project subagents
│   └── *.md
├── rules/                     # Project-level modular rules
│   └── *.md
├── commands/                  # Custom slash commands
│   └── *.md
├── skills/                    # Custom skills
│   └── {skill-name}/
│       ├── SKILL.md
│       └── supporting-files/
├── hooks/                     # Project-level hooks
│   ├── scripts/
│   └── config/
└── plugins/                   # Installed plugins

.mcp.json                      # Project-scoped MCP servers (repo root)

Tasks System

Introduced in Claude Code v2.1.16 (January 22, 2026), replacing the deprecated TodoWrite system.

Storage

Tasks are stored at ~/.claude/tasks/ on the local filesystem (not in a cloud database). This makes task state auditable, version-controllable, and crash-recoverable.

Tools

Tool Purpose
TaskCreate Create a new task with subject, description, and activeForm
TaskGet Retrieve full details of a specific task by ID
TaskUpdate Change status, set owner, add dependencies, or delete
TaskList List all tasks with their current status

Task Lifecycle

pending  →  in_progress  →  completed

Dependency Management

Tasks can block other tasks via addBlockedBy/addBlocks, creating dependency graphs that prevent premature execution.

Multi-Session Collaboration

CLAUDE_CODE_TASK_LIST_ID=my-project-tasks claude

All sessions sharing the same ID see task updates in real-time, enabling parallel workstreams and session resumption.

Key Differences from Old Todos

Feature Old Todos New Tasks
Scope Single session Cross-session, cross-agent
Dependencies None Full dependency graph
Storage In-memory only File system (~/.claude/tasks/)
Persistence Lost on session end Survives restarts and crashes
Multi-session Not possible Via CLAUDE_CODE_TASK_LIST_ID

Agent Teams

Announced February 5, 2026 as an experimental feature. Agent Teams allow multiple Claude Code sessions to coordinate on shared work.

Enabling

// In ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Configuration

Team configs live at ~/.claude/teams/{team-name}/ and support modes:

Mode Description Requirements
In-process (default) All teammates run inside your terminal None
Split panes Each teammate gets its own pane tmux or iTerm2 (not VS Code terminal)

Design Principles

The global-only vs dual-scope split follows a clear pattern:

Category Scope Rationale
Coordination state (tasks, teams) Global-only Needs to persist beyond any single project
Security state (credentials, OAuth) Global-only Prevents accidental commits to version control
Personal learning (auto-memory) Global-only User-specific, not team-shareable
Input preferences (keybindings) Global-only User muscle memory, not project-specific
Configuration (settings, rules, agents) Both levels Teams need to share project-specific behavior
Workflow definitions (commands, skills) Both levels Can be personal or team-shared

Auto-memory (~/.claude/projects/<hash>/memory/) is a notable hybrid: it's about a specific project but stored globally because it represents personal learning rather than team-shareable configuration.

Sources