[FEATURE] Better lifecycle management for project metadata in `~/.claude.json`

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

Claude CLI stores project-scoped metadata under the projects key in the global file ~/.claude.json.
Over time, entries for deleted or temporary directories accumulate, and there is currently no built-in cleanup workflow.

Current Behavior

When Claude CLI is used in a directory, it can register that directory in ~/.claude.json:

{
  "projects": {
    "/path/to/project-a": {
      "allowedTools": [],
      "mcpServers": {},
      "exampleFiles": ["main.ts", "app.ts"],
      "lastCost": 1.23,
      "lastSessionId": "xxx"
    },
    "/path/to/deleted-project": {
      "...": "stale metadata"
    }
  }
}

Problem

1. Stale project entries remain after directories are deleted.
2. No official cleanup command exists for orphaned project records.
3. Global config can grow significantly for users with high project churn (temporary workspaces, automation, CI).
4. Project-scoped metadata is mixed with user-scoped/global settings.

Expected Behavior

Users should have a supported way to keep project metadata accurate and bounded over time, either by:

• automatic pruning of non-existent project paths,
• a manual cleanup command,
• or storing project metadata closer to each project.

Proposed Solution

Proposal

Any one of the following (or a combination) would solve the issue:

Option A: Add cleanup command

claude config clean --stale

Removes entries in projects whose directories no longer exist.

Option B: Support project-local metadata storage

Store mutable project metadata in .claude/project-meta.json (alongside existing .claude/settings*.json) instead of only in ~/.claude.json.

Option C: Add configurable storage strategy

{
  "projectMetadataLocation": "system" | "project"
}

Default can remain backward-compatible ("system").

Why this matters

• Improves long-term maintainability of user config.
• Helps automation-heavy workflows avoid ~/.claude.json bloat.
• Better separation between global preferences and per-project state.

Backward Compatibility

• Keep current behavior as default.
• If new storage mode is introduced, provide migration/fallback behavior.

Environment

• Claude CLI version: 2.1.14 (Claude Code)
• OS
• ProductName: macOS
• ProductVersion: 26.3
• BuildVersion: 25D125

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_