Claude Code Sessions

Definition

A session is a saved conversation tied to a project directory. Sessions are saved continuously to local transcript files, so a developer can exit, run /clear, or switch tasks and later resume.

Key Points

• Entry points: claude --continue (resumes most recent session in current dir), claude --resume (picker), claude --resume <name> (direct), claude --from-pr <number> (picker filtered to a PR), /resume (switch mid-session).
• What a resumed session restores: conversation history (incl. tool calls/results), model (unless retired/restricted/overridden), agent (system prompt, tool restrictions), permission mode (plan/bypassPermissions never restored; auto only if still eligible), active goal, unexpired scheduled tasks. Flags like --mcp-config, --settings, --plugin-dir, --fallback-model must be re-passed.
• Resume from summary: on Pro/Max, a session inactive ~1h and >100k tokens offers (a) resume from summary (runs /compact), (b) full session as-is, (c) “don’t ask me again.”
• Naming & branching: claude -n auth-refactor, /rename, Ctrl+R in picker; /branch <name> or claude --continue --fork-session copies conversation; history and permission grants carry over, background subagents keep running.
• Context control: /clear (fresh context, prior saved), /compact [instructions], /context.
• Transcripts: JSONL at ~/.claude/projects/<project>/<session-id>.jsonl (project = workdir path with non-alphanumerics → -); /export for readable copy; scripts via claude -p --output-format json|stream-json and claude -p --resume <session-id>; config CLAUDE_CONFIG_DIR, cleanupPeriodDays (30-day default).

Implications

Sessions are the cost-management primitive behind “clear between tasks” in token-usage-reduction: /clear frees context cheaply while persistence keeps work recoverable. Resume-from-summary is the canonical compaction-at-scale trigger (>100k tokens), and branching gives cheap experiment isolation without losing the original thread. Script access (claude -p --resume <session-id>) turns past sessions into data for tooling like token-optimizer-mcp.

Open Questions

• Whether resumed sessions’ restored context interacts cleanly with prompt caching (cache misses on long breaks).
• Interaction between cleanupPeriodDays and long-running projects.

Related

token-usage-reduction — why session hygiene (clear/rename/resume) is a cost lever claude-code-memory — companion persistence layer for project instructions claude-code-system-prompt — the agent sessions are snapshots of token-optimizer-mcp — consumes transcript data via scripts codeburn — reads on-disk session files to track token/cost per session

Sources

• raw/external/code-claude-com-sessions-0ab9c7fd.md