Default Claude Code transcript retention to 1 year (cleanupPeriodDays) — 30-day default wipes sessions from the persisted ~/.claude volume #173

Summary

Claude Code deletes session transcripts older than cleanupPeriodDays (default 30) every time it starts. The template persists ~/.claude in a named volume, so transcripts survive rebuilds. The 30-day sweep still deletes them, and after a month /resume no longer finds those sessions. The images and templates should default to keeping transcripts for at least a year.

Why it has to be user scope

The cleanup runs at startup and sweeps every project under ~/.claude/projects, not just the current one. Setting cleanupPeriodDays in a project's .claude/settings.json isn't enough: any session started from another directory (a worktree, /tmp, a second repo on the same volume) falls back to 30 days and deletes the old transcripts from every project. The setting has to be in ~/.claude/settings.json (or managed settings).

Verification

claude --version          # 2.1.280
jq .cleanupPeriodDays ~/.claude/settings.json   # null -> 30-day default applies

The CLI's own schema text: "Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention."

Suggested fix

Set it only when it's missing (//=), so a value a user chose on purpose is kept:

SETTINGS="$HOME/.claude/settings.json"
[ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"
jq '.cleanupPeriodDays //= 365' "$SETTINGS" > /tmp/claude-settings.json \
    && mv /tmp/claude-settings.json "$SETTINGS"

Where to put it:

• Preferred: a small baked script, e.g. /usr/local/bin/ensure-claude-defaults, chained into postStartCommand next to /usr/local/bin/patch-playwright-mcp. It only runs jq, with no claude CLI calls, so it doesn't hit the OAuth sign-in race from fix(devcontainer): theme, login, node_modules isolation, self-contained claude-code config #58. It also runs on every start, so existing containers and volumes pick it up. init-plugins.sh has the same "never reaches existing containers" problem as claude-code template: plugins added to init-plugins.sh never reach existing containers unless the script is run by hand #171.
• Simpler, but can't be overridden: add "cleanupPeriodDays": 365 to claude-code/.devcontainer/managed-settings.json. Managed settings take precedence over user settings, so users could no longer pick a different value.
• init-plugins.sh on its own isn't enough for the default variant, because it's run by hand there.

Affected files in this repo

• claude-code/.devcontainer/devcontainer.json (postStartCommand)
• claude-code/.devcontainer/claude-sandbox/devcontainer.json (postStartCommand)
• claude-code/.devcontainer/Dockerfile (bake the script)
• or claude-code/.devcontainer/managed-settings.json, ralphex-fe/managed-settings.json

Related

• fix(devcontainer): theme, login, node_modules isolation, self-contained claude-code config #58: claude CLI calls from postCreate race the OAuth sign-in
• claude-code template: plugins added to init-plugins.sh never reach existing containers unless the script is run by hand #171: init-plugins.sh changes don't reach existing containers