Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/claude-directory
Section/Topic
Application data → “Cleaned up automatically” and “Kept until you delete them”, plus the cleanupPeriodDays setting description
Current Documentation
The docs currently say:
Files in the paths below are deleted on startup once they're older than cleanupPeriodDays. The default is 30 days.
projects/<project>/<session>.jsonl
projects/<project>/<session>/tool-results/
file-history/<session>/
plans/
debug/
paste-cache/, image-cache/
session-env/
They also say:
The following paths are not covered by automatic cleanup and persist indefinitely.
backups/ | Timestamped copies of ~/.claude.json taken before config migrations
And on the same page:
shell-snapshots/ holds runtime files removed when the session exits cleanly.
Other docs identify the task-list directory but do not mention retention cleanup:
To share a task list across sessions, set CLAUDE_CODE_TASK_LIST_ID to use a named directory in ~/.claude/tasks/
Task list: ~/.claude/tasks/{team-name}/
The cleanupPeriodDays row in settings currently says only:
Session files older than this period are deleted at startup (default: 30 days, minimum 1). Setting to 0 is rejected with a validation error. Also controls the age cutoff for automatic removal of orphaned subagent worktrees at startup.
What's Wrong or Missing?
Changelog v2.1.117 says: “The cleanupPeriodDays retention sweep now also covers ~/.claude/tasks/, ~/.claude/shell-snapshots/, and ~/.claude/backups/”.
The current docs do not reflect that expanded sweep:
A. backups/ is described as persisting indefinitely
That now contradicts the changelog behavior because ~/.claude/backups/ is part of the cleanupPeriodDays retention sweep.
B. shell-snapshots/ is described only as clean-exit cleanup
The docs imply shell-snapshots/ is removed only when a session exits cleanly, but v2.1.117 adds age-based startup cleanup through cleanupPeriodDays.
C. tasks/ is documented as a storage location, but not as retained data subject to cleanup
Users who rely on shared task lists can discover the on-disk path, but the docs do not warn that old task-list data is now swept by cleanupPeriodDays.
This is a data-retention behavior change, so users need accurate expectations about which ~/.claude directories persist and which are automatically deleted.
Suggested Improvement
Update the retention documentation to match v2.1.117:
- In
claude-directory, add tasks/, shell-snapshots/, and backups/ to the age-based cleanup coverage described under cleanupPeriodDays.
- Remove or revise the statement that
backups/ is “not covered by automatic cleanup and persist[s] indefinitely.”
- Revise the
shell-snapshots/ note so it explains both cleanup paths: clean session exit and age-based startup cleanup.
- Expand the
cleanupPeriodDays row in settings so it explicitly lists the additional directories now covered.
- Consider adding a short note in task-list docs that shared task-list directories under
~/.claude/tasks/ are also subject to cleanupPeriodDays retention.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 4 pages affected
Source: Changelog v2.1.117
Exact changelog entry: The cleanupPeriodDays retention sweep now also covers ~/.claude/tasks/, ~/.claude/shell-snapshots/, and ~/.claude/backups/
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/claude-directory
Section/Topic
Application data → “Cleaned up automatically” and “Kept until you delete them”, plus the
cleanupPeriodDayssetting descriptionCurrent Documentation
The docs currently say:
They also say:
And on the same page:
Other docs identify the task-list directory but do not mention retention cleanup:
The
cleanupPeriodDaysrow in settings currently says only:What's Wrong or Missing?
Changelog v2.1.117 says: “The
cleanupPeriodDaysretention sweep now also covers~/.claude/tasks/,~/.claude/shell-snapshots/, and~/.claude/backups/”.The current docs do not reflect that expanded sweep:
A.
backups/is described as persisting indefinitelyThat now contradicts the changelog behavior because
~/.claude/backups/is part of thecleanupPeriodDaysretention sweep.B.
shell-snapshots/is described only as clean-exit cleanupThe docs imply
shell-snapshots/is removed only when a session exits cleanly, but v2.1.117 adds age-based startup cleanup throughcleanupPeriodDays.C.
tasks/is documented as a storage location, but not as retained data subject to cleanupUsers who rely on shared task lists can discover the on-disk path, but the docs do not warn that old task-list data is now swept by
cleanupPeriodDays.This is a data-retention behavior change, so users need accurate expectations about which
~/.claudedirectories persist and which are automatically deleted.Suggested Improvement
Update the retention documentation to match v2.1.117:
claude-directory, addtasks/,shell-snapshots/, andbackups/to the age-based cleanup coverage described undercleanupPeriodDays.backups/is “not covered by automatic cleanup and persist[s] indefinitely.”shell-snapshots/note so it explains both cleanup paths: clean session exit and age-based startup cleanup.cleanupPeriodDaysrow insettingsso it explicitly lists the additional directories now covered.~/.claude/tasks/are also subject tocleanupPeriodDaysretention.Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
backups/persists indefinitely and only gives a clean-exit note forshell-snapshots/cleanupPeriodDayssetting description should mention the newly covered directories~/.claude/tasks/but does not mention retention cleanup~/.claude/tasks/{team-name}/but does not mention retention cleanupTotal scope: 4 pages affected
Source: Changelog v2.1.117
Exact changelog entry: The
cleanupPeriodDaysretention sweep now also covers~/.claude/tasks/,~/.claude/shell-snapshots/, and~/.claude/backups/