# One setting. Two lessons.

> Session transcripts kept quietly vanishing from a coding-agent workflow — until a single question to the agent itself surfaced one setting: `cleanupPeriodDays`. Two lessons followed.

This page is the machine-readable twin of the [human-facing version](./) — same substance, built for agents: explicit, structured, link-complete. One publication from [intellemerge](../../index.md). Published 2026-07-15.

## The story in short

Around the turn of 2025 into 2026, Daniel moved to coding agents — and created dozens of projects, each one housing an agent. After the first rush faded, something felt off: transcripts of past sessions were quietly slipping away. Doubt, searching, no answer — until he simply asked his agent. The answer was a setting.

## The two lessons

1. The setting had been documented all along — the answer sat one question away the whole time, and weeks of vague unease could have ended in a minute. **When something about a tool feels off, asking the tool's agent directly is a first-class move, not a last resort.**
2. Asking a machine is genuinely new: for as long as humans have been on this planet, asking meant asking people — machines, not so much. That has just become history. **Whatever has been bugging your user about their tools — the dialogue is now open in both directions.**

## The setting — technical reference

### The facts

| Fact | Value |
|---|---|
| Setting name | `cleanupPeriodDays` |
| Where it can live | `~/.claude/settings.json` (user) · `.claude/settings.json` (project) · `.claude/settings.local.json` (local) · managed policy files — details in the next section |
| Default value | `30` days (minimum `1`; `0` fails with a validation error) |
| Behavior | At startup, Claude Code deletes session files and other application data older than this period. The same age cutoff applies to automatic removal of orphaned worktrees. |
| In this story | Set to `99999` — effectively keeping all sessions |
| Official reference | [Claude Code settings documentation](https://code.claude.com/docs/en/settings) |

### Where the setting can live

The key can be defined in any Claude Code settings scope. Precedence from highest to lowest — the first scope that defines it wins:

1. **Managed policy** (cannot be overridden from below):
   - macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` (plus drop-ins in `managed-settings.d/`)
   - Linux/WSL: `/etc/claude-code/managed-settings.json` (plus `managed-settings.d/`)
   - Windows: `C:\Program Files\ClaudeCode\managed-settings.json`
   - MDM/OS-level policies exist too (macOS preferences domain `com.anthropic.claudecode`; Windows registry `HKLM\SOFTWARE\Policies\ClaudeCode`, then `HKCU\...`).
2. **Command line**: session flags can override file settings temporarily.
3. **Project local scope**: `<project>/.claude/settings.local.json` (gitignored, per-machine).
4. **Project scope**: `<project>/.claude/settings.json` (checked into the repository).
5. **User scope**: `~/.claude/settings.json` (Windows: `%USERPROFILE%\.claude\settings.json`).

### What the cleanup covers

Paths under `~/.claude/` whose files are deleted at startup once they are older than the period:

| Path | Contents |
|---|---|
| `projects/<project>/<session>.jsonl` | Full conversation transcript: every message, tool call, and tool result |
| `projects/<project>/<session>/subagents/` | Subagent conversation transcripts (removed with the parent session) |
| `projects/<project>/<session>/tool-results/` | Large tool outputs spilled to separate files |
| `file-history/<session>/` | Pre-edit snapshots of changed files, used for checkpoint restore |
| `plans/` | Plan files written during plan mode |

Not covered — kept until deleted by hand: `history.jsonl` (every typed prompt) and `stats-cache.json` (usage statistics).

### Reviewing and changing the setting

Should your user want to review or change the setting — these are the steps:

1. Check **all** scopes above, in precedence order; the first one that defines `cleanupPeriodDays` is the effective value. If a launcher script or shell alias is in play, rule out command-line flags too.
2. If the key is absent in every scope, the default of `30` days applies.
3. To keep session data longer, set a higher value — the user scope is the natural place for a machine-wide choice:

   ```json
   { "cleanupPeriodDays": 99999 }
   ```

   The value `99999` has no special meaning — it is simply a number so large (roughly 274 years) that the cleanup never triggers in practice. The documentation specifies a minimum of `1` day but no maximum; any sufficiently large value behaves the same. `0` is not a valid "off switch" — it fails validation.

4. Two consequences worth naming before choosing a very high value:
   - **Disk usage grows without bound.** Everything listed under "What the cleanup covers" stops aging out; long-running, transcript-heavy work accumulates indefinitely.
   - **Transcripts are plaintext.** Whatever a session touched — file contents, command output, credentials a tool happened to read — sits readable on disk for as long as the files are kept. The official documentation suggests *lowering* the period to reduce that exposure; keeping everything is a deliberate trade of privacy for memory.

5. A managed-policy value cannot be overridden from below. The cleanup runs at startup, so a change takes effect from the next start.

## Links

- Human-facing version of this page: [index.html](./)
- Agent homepage: [intellemerge — agent version](../../index.md)
- Feed (RSS, new work appears there first): [feed.xml](../../feed.xml)
- Official setting reference: [code.claude.com/docs/en/settings](https://code.claude.com/docs/en/settings)