Working With Claude Code Transcripts

2025-11-15 16:03:50 PST

Bart Massey 2025

When I am finished with a large work session with Claude Code, I want to have a complete transcript of my conversation with the agent. This is useful for my review, and even more useful for showing our work to others.

My initial approach involved adding detailed instructions to ~/.claude/AGENTS.md with the intent of having Claude Code maintain its own transcripts.

Even after much iteration, this process was pretty much fail. Claude would forget to keep a transcript, would produce "transcripts" containing summaries, and would generally struggle with the whole process. I gave up on Claude as a transcription tool.

I was about to resort to using screen somehow (which I kind of hate), but I ran a quick Gemini search (LOL) and found out that Claude Code already keeps a complete JSON transcript of every session in ~/.claude/projects (!). This is something Claude Code had failed to disclose after numerous interrogations, and was extremely heartening.

The Gemini search showed a couple of useful things. First, these transcipts are apparently auto-deleted after 30 days (thanks Simon Willison!). The suggested fix is to add "cleanupPeriodDays: 99999" to ~/.claude/settings.json. Done.

Second, there are existing Python command-line tools to work with the transcripts. Gemini suggested claude-conversation-extractor, which contains several small tools; the blog post above pointed to Simon Willison's own claude_to_markdown.

I installed claude-conversation-extractor, ran claude-search, and was told it would be good to

$ pip install --user spacy && python -m spacy download en_core_web_sm

to get better search. With or without, the search seemed to work great.

Extraction during search was annoying, since the claude-search tool's extraction put the markdown output in ~/Desktop/Claude\ logs; this was hard to find and I don't use my Desktop directory anyhow. But meh. Might fix and upstream later. At the very least, --help should be added to these tools.

Anyhow, now I can get back my Claude Code conversations and have future ones continue to be recorded automatically. There were some I really wanted back, so this is not just good but great news.