Session State & Resumption
CoreManage session state, resumption, and forking · Difficulty 3/5
Explanation
Long-running agent work often spans multiple sessions. Managing session state correctly prevents wasted work and stale context issues.
Named Session Resumption
Use --resume <session-name> to continue a specific prior conversation. This preserves the full conversation history including tool results from the previous session.
When to Resume vs Start Fresh
| Scenario | Strategy |
|---|---|
| Prior context is mostly valid | Resume with --resume |
| Files have been modified since last session | Resume but inform agent of specific changes |
| Prior tool results are stale (data changed) | Start fresh with structured summary |
| Exploring a different approach | Fork the session |
Starting a new session with a structured summary is more reliable than resuming with stale tool results, because the agent may reason incorrectly based on outdated information.
Targeted Re-Analysis
When resuming after code modifications, inform the agent about specific file changes rather than requiring full re-exploration. This enables targeted re-analysis of only what changed.
fork_session
Create independent branches from a shared analysis baseline to explore divergent approaches:
- Compare two testing strategies from a shared codebase analysis
- Try different refactoring approaches without losing the original analysis
- Each fork operates independently with its own conversation history
Key Takeaways
- Use --resume <session-name> to continue named investigation sessions
- Start fresh with structured summaries when prior tool results are stale
- Use fork_session to explore divergent approaches from a shared baseline
- Inform resumed sessions about specific file changes for targeted re-analysis
Related Concepts