[FEATURE] Add per-project cleanup: forget/remove a single project entry (instead of editing ~/.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
Claude Code persists per-project state keyed by absolute project path. Over time I accumulate many short-lived projects (e.g. test folders, cloned repos, throwaway PoCs). This leaves a growing set of stale project entries that I no longer need, but Claude Code continues to keep them indefinitely.
Today there is no safe, supported way to remove a single project from the per-project store. The only practical options are either:
1) manually editing ~/.claude.json (or the current equivalent store), which is error-prone and risks corrupting the entire file/state, or
2) clearing everything globally (e.g. history clear), which is unacceptable because it deletes state for all projects.
This becomes a real workflow problem when:
- I want to “forget” one project (tool trust / MCP server enablement, cached stats, etc.) without affecting other projects.
- I want to remove sensitive/temporary paths from the persisted project list.
- The per-project store grows unbounded and impacts usability/performance (related to ongoing reports about ~/.claude.json growth).
Proposed Solution
Add a first-class, per-project removal command and/or API.
CLI proposal (one of these, exact naming not important):
- claude project forget "<absolute-path>"
- claude project rm "<absolute-path>"
- claude history clear --project "<absolute-path>"
- claude project prune --older-than 30d
Expected behavior:
- Remove exactly one project entry identified by absolute path (the top-level key).
- Optionally support “clear history only” vs “delete entire project state”:
- --history-only (keeps allowedTools/MCP enablement, clears history/cost/usage stats)
- --all (removes the entire project block)
- Safe writes:
- atomic write (write to temp + rename)
- automatic backup before changes
- validate JSON/schema before committing changes
- Discoverability:
- claude project list (shows stored projects + lastUsed and size/entry count)
- claude project info "<path>" (shows what will be removed)
Rationale:
This avoids manual JSON editing, prevents accidental corruption, and avoids “nuke all projects” behavior for a single-project cleanup.
Alternative Solutions
- Manual edit of ~/.claude.json:
- Risky and error-prone; easy to break JSON (especially with large files).
- Not automatable in a safe way for most users.
- Global clear (history clear / delete config):
- Removes all projects, losing trust settings and other state that I want to keep.
- Creating fresh user profiles / moving config:
- Heavy-handed, still loses state across all projects.
Priority
High - Significant impact on productivity
Feature Category
CLI commands and flags
Use Case Example
1) I open a temporary folder for testing (e.g. /home/user/Downloads/Test) and Claude Code creates a project entry for it, including trust/MCP server enablement and cached usage stats.
2) Later I delete the folder or no longer want it tracked. The entry remains in the per-project store forever.
3) I want to remove only that one stale entry, without losing my state for other active repos.
With the proposed feature:
- I run: claude project forget "/home/user/Downloads/Test"
- Claude Code removes exactly that project entry and leaves all other projects untouched.
- The config/store remains valid (atomic write + backup), and the project list is clean.
Additional Context
Project entries are currently stored keyed by absolute path, for example:
"/home/user/Downloads/Test": {
"allowedTools": [],
"mcpServers": {},
"hasTrustDialogAccepted": true,
...
}
This makes a per-path delete operation deterministic (delete the top-level key for that path).
Related context:
- There are existing reports about unbounded growth and performance impact when the per-project store accumulates history/state.
- There are also reports/discussions that .claude.json has been considered deprecated in favor of a newer settings hierarchy, so the feature should target the current storage mechanism and not depend on deprecated files.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗