Author's): Vikas Tiwari
Originally published in Towards Artificial Intelligence.
A few weeks ago I was working on a legacy project that had over 100 microservices. I encountered a bug in this particular backend service that looked really familiar, but I couldn't remember where or how I fixed it. Then it hit me that Claude Code would remember, but then I wouldn't remember which session to open.
I started wondering where all these conversations were stored, and after some reading, I found out that CC kept everything inside ~/.claude/projects/(folder-names)/(uuid).jsonl How JSONL files.
For example, for one of my applications at ~/ws/nq/news-bulletin/app call history will be stored in ~/.claude/projects/-Users-vikas-t-ws-nq-news-bulletin-app/bf8ecb66-fc60-4187-9c92-cded3ea68f58.jsonl. The UUID here is made up.
What exactly is there?
Every file is JSONL (JSON lines). One JSON object per line. Each line represents one turn in the conversation.
{
"type": "assistant",
"uuid": "abc-123-def",
"timestamp": "2026-01-14T04:51:53.996Z",
"sessionId": "fe82a754-0606-4bcf-b79a-f7b6f2a72bc8",
"message": {
"id": "msg_01ABC123",
"type": "message",
"role": "assistant",
"model": "claude-opus-4-5-20251101",
"content": (
{
"type": "tool_use",
"id": "toolu_xyz",
"name": "Read",
"input": {"file_path": "/path/to/file.py"}
}
),
"stop_reason": "tool_use",
"usage": {
"input_tokens": 1234,
"output_tokens": 567,
"cache_creation_input_tokens": 5000,
"cache_read_input_tokens": 0
}
}
}
Your prompts are there along with Claude's answers, all the tool calls (Read, Write, Edit, Bash), what matters is the token for each round, which model responded to each message (Opus 4.5, Sonnet 4.5) and basically everything that happened during that session.
What can you actually do about it
Debugging time travel
You shipped this feature 2 weeks ago and now there's a bug. You remember Claude mentioning a workaround for the Edge case, but you don't remember what it was.
grep -A5 -B5 "edge case" ~/.claude/projects/my-feature/*.jsonl
And here it is.
Get your lost job back
The terminal crashed mid-session. You didn't commit. You're basically screwed. Not with JSONL. Extract all Write/Edit calls and copy the code back:
cat crashed-session.jsonl | jq -r '.message.content()? | select(.name == "Write" or .name == "Edit") | .input'
Find that one command
Three months ago you ran a complex bash pipeline through Claude. It worked perfectly. What was that?
cat old-session.jsonl | jq -r '.message.content()? | select(.name == "Bash") | .input.command' | grep "docker"
Token cost forensics
You've reached your weekly speed limit and want to know which session caused it. Find out which session was greedy.
for f in ~/.claude/projects/*/*.jsonl; do
echo "$f: $(cat $f | jq '.message.usage.input_tokens' | paste -s -d+ - | bc) tokens"
done | sort -t: -k2 -n
50k refactoring session line appears at the very bottom.
Find out what actually worked
Tried 3 different approaches to solving the performance issue. Two failed. Which one worked and why? Read the session. See exactly when Claude changed his strategy, what didn't work and why it didn't work. Better than Stack Overflow because it is your problem.
Code review audit trail
When someone asks why you implemented something a certain way, stop the session and show your team an actual conversation where Claude explained the trade-offs, the alternatives considered, and the rationale for the decision. You get the whole thought process, not just the “because Claude said so” answer.
Extract documentation
Claude explained something complex really well during the session. Write down this explanation:
cat session.jsonl | jq -r '.message.content()? | select(.type == "text") | .text' > explanation.md
Now it's documentation.
By default, files expire after one month
CC has a default setting to automatically clear your local call history after 30 days. It's like losing all your coding memory. You can change this behavior by configuring the file cleanupPeriodDays setting in the settings.json file. To apply this setting globally to your user, create or edit the file at ~/.claude/settings.json.
If you ask me, I will keep it forever, it doesn't take up much disk space. On my computer it is several hundred MB.
To effectively disable automatic deletion, you can set the cleaning period to a very large number of days. For example, add the following to the file ~/.claude/settings.json file:
{
"cleanupPeriodDays": 99999
}
Another solution would be to simply make a backup.
Things to pay attention to
These files become large during long debugging sessions because there is a lot of back and forth, a lot of context being cached and re-read, which is completely normal for complex work.
They contain everything you showed Claude during the session, including code, any secrets you may have pasted in for debugging, file contents, command results, and more. Don't push them to GitHub unless you've thoroughly researched what's there.
How I actually use it
I have a bash function in my .zshrc:
ccsearch() {
grep -r "$1" ~/.claude/projects/*/
}
So ccsearch "authentication fix" searches all my sessions. I found solutions that I had completely forgotten about.
Most people never look at them. But if you're debugging something difficult or trying to understand what actually happened in a session, they're useful.
So back to my original story. I looked for the problem in JSONL files and it returned thousands of lines of text. It took me a while to narrow it down to what I wanted. It turned out that I had tried the correct set of commands, except that one of them had a typo. 😀
Follow for more!
Published via Towards AI
