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.

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

WARNING

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

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

bash

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

json

// 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

INFO

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

Claude Code: Global vs Project-Level Features ​

Overview ​

Global-Only Features ​

Dual-Scope Features ​

Settings Precedence ​

Directory Structure Comparison ​

Global Scope (~/.claude/) ​

Project Scope (.claude/) ​

Tasks System ​

Storage ​

Tools ​

Task Lifecycle ​

Dependency Management ​

Multi-Session Collaboration ​

Key Differences from Old Todos ​

Agent Teams ​

Enabling ​

Configuration ​

Design Principles ​

Sources ​