Most AI coding workflows treat the current session as the important part.
That makes sense while you are in the loop. You ask Claude Code to inspect a tricky bug, or you queue Codex to write a PR, and the useful context is right there in front of you.
The problem starts a week later.
You remember that one session found the exact migration edge case. You remember another one explained why the quick fix was wrong. You might even remember the project. But you do not remember the session ID, the terminal tab, or the exact prompt that got you there.
That is the point where AI coding sessions stop being conversations and start becoming project infrastructure.
Here is the split that has worked best for me.
1. Keep durable rules in project files
Files like AGENTS.md, CLAUDE.md, or .codex/rules are good for behavior that should apply every run:
- coding style
- test expectations
- release rules
- known architecture constraints
- commands that should or should not be used
This is not session history. It is the baseline contract for the project.
If you correct the agent twice on the same pattern, that correction probably belongs in one of these files.
2. Keep active work in a handoff document
For a feature or refactor, I like having a short implementation.md or handoff.md.
It should answer a few boring questions:
- what are we changing?
- what phase are we in?
- what did the last agent already try?
- what still needs human review?
- what tests were run?
This works especially well when Claude Code and Codex are both touching the same repo. Claude Code can help explore and make decisions locally, while Codex can take a narrower task and return a PR. The handoff document keeps those runs from drifting apart.
3. Treat old sessions as searchable project records
The raw transcripts usually exist somewhere. For Claude Code, that often means digging through local session files. For Codex, the useful context may be split across tasks, PR notes, and local terminal work.
The hard part is not that the data is gone.
The hard part is finding the right old conversation when you only remember the project and the decision.
That is why I ended up building Shelf: a small open-source desktop app for browsing Claude Code and Codex sessions by project.
Repo: https://github.com/Harukaon/shelf
The goal is simple: old AI coding sessions should be reopenable without remembering opaque session IDs or spelunking through terminal history.
It is built with Tauri v2, Rust, TypeScript, Vite, and xterm.js, and currently targets macOS Apple Silicon and Linux.
My current rule of thumb
If it affects every future run, put it in project rules.
If it affects the current feature, put it in a handoff doc.
If it explains why a past decision happened, make sure the old session is easy to find again.
That third bucket is easy to ignore until you have twenty sessions across the same project. After that, retrieval becomes part of the workflow.
AI coding sessions are not just chat logs. They are project history.
Top comments (0)