Claude Code Session History: Reading Back What Happened in a Session

Claude Code keeps a transcript of the session. If you want to reread the conversation, that is the right artifact and this page is not for you.

It stops being the right artifact the moment you want to ask a question of it. “How many times did it touch that file.” “What ran between 14:00 and 14:30.” “Show me every Bash command in the session that broke the build.” Those are queries, and a prose transcript does not answer queries.

Two different things called history

The transcript is the conversation: prompts, responses, and the tool calls inline. It is designed for a human to read in order.

A tool-call record is one structured line per action: which tool, what arguments, what came back, which session, when. It is designed to be filtered and counted.

You want both, and they are not substitutes. The transcript tells you why something happened. The record tells you what happened, and can tell you at a scale reading cannot.

Keeping a structured session history

pip install homestead-memory     # needs Python 3.10+
hsm hook --install               # prints the snippet; you paste it

From then on every tool call appends one line to a JSONL file on your disk, carrying its session id.

hsm watch                        # everything, most recent last
hsm watch --session <id>         # one session
hsm watch --tool Edit            # one tool, across sessions
hsm watch -n 50                  # the last 50 records
hsm watch --json                 # structured output for your own tooling

Because it is JSONL, the boring tools work. grep finds a filename. jq counts calls per tool. wc -l tells you how long a session really was, which is usually longer than it felt.

If you want to see the shape before installing anything, hsm watch --demo runs the whole loop in a temporary directory and removes it afterwards.

The property a transcript does not have

A session history answers “what happened”. A useful follow-up is “can I be sure this is what happened”, and that is a different question with a different answer.

Nothing about a transcript, or a plain log, resists editing. Both are files. If the history matters after the fact, in a review, a postmortem, or a dispute, then the record needs to make alteration detectable rather than merely unlikely.

Each record here carries the hash of the record before it, so an edit, a deletion or a reorder breaks every hash after it and is reported at the exact index. Signing the head with hsm checkpoint covers the remaining case, where the whole chain is rebuilt and every hash recomputed.

That is tamper-evident, not tamper-proof. It does not prevent a change. It makes one visible, which is the only claim the mechanism supports.

The honest limits

• Claude Code only. Cursor and Codex need different mechanisms and are not built.
• About 124ms per tool call, measured, median across both hook phases.
• It records what the harness reported, not independent observation of what the tool did.
• Sessions that ran before you installed the hook are not in it. There is no backfill, because the events were never captured.

github.com/fuckbigtech-ai/homestead-memory

For the wider picture, including how this compares to hosted observability platforms, see how to monitor Claude Code.