claude-code - 💡(How to fix) Fix [DOCS] cleanupPeriodDays retention docs omit tasks, backups, and shell-snapshots [1 participants]

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:

1. In claude-directory, add tasks/, shell-snapshots/, and backups/ to the age-based cleanup coverage described under cleanupPeriodDays.
2. Remove or revise the statement that backups/ is “not covered by automatic cleanup and persist[s] indefinitely.”
3. Revise the shell-snapshots/ note so it explains both cleanup paths: clean session exit and age-based startup cleanup.
4. Expand the cleanupPeriodDays row in settings so it explicitly lists the additional directories now covered.
5. 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/