A code graph draws one layer of a project: the code. Functions, calls, imports, what depends on what. It is a good picture and people read it fine.
Under that layer there is another one, and it has no picture. The sessions you ran. What you typed into each of them. The moments the agent chose one way over another, and its reason. The work a later session picked up from an earlier one. All of it exists, in transcripts and in someone's memory, and no one has seen it drawn.
session-trail is a Claude Code plugin that draws that layer. It sits next to a code graph, not in place of it.
What is on the picture
One lane per session. A node per decision or finished piece of work. A curve between lanes when a later session continues a line an earlier one started. Small ticks on each lane for every prompt you typed. Read left to right, it is the story of the project.
Click a node and you get its title, what, why and how, the files touched around it, the session id and the path of the local transcript. Click a tick and you get the prompt, as typed.
The why, and your own words
Two things I most wanted on this picture.
The why, in the agent's words, at the moment it chose. When the agent makes a choice with lasting consequences, or finishes a unit of work, it passes a short brief to a Sonnet subagent, which writes the node. The why has to name the options that were passed over. That is the sentence you cannot get back from a diff.
Your own words, as typed. Every prompt is stored word for word by a hook. No model in that path, no summary in between. Weeks later, "what did I ask for back then" has an answer in the original wording, and the transcript path on the node takes you to the conversation.
Side by side on one axis, the request and the reason it produced are the part of the history that used to vanish first.
Many sessions, one picture
The hardest thing to see in agent work is how it spreads across sessions. A session starts, does something, ends; the next one picks up part of it, or does not. Here each session is a lane, and when a later one continues an earlier line, a curve joins the two. The time axis is linear inside a session and compressed across idle gaps, so a month with three active days fits on one screen.
The same picture for the person and the agent
The viewer is the product. It is drawn for people to read, and the agent's read side sits on top of it: three commands (show, why <path>, search) that it uses in one situation, right before reversing a choice that looks intentional. No history is pushed into the context on edits.
The point is that you and the agent look at the same history. You in the viewer, weeks later, or a teammate joining the project; the agent at the start of a session, or when it is about to undo something. Working with an agent, what you lose first is context: the reasons, the sequence, the story. This puts them back where a person can see them.
How it is built
- One append-only file,
.session-trail/events.jsonl, in the project folder. The graph is a pure reduction over it. Commit it to share the history with your team, or gitignore it. - Node 18+, no npm dependencies. The viewer is vanilla JS and SVG, no build step.
- Hooks do the mechanical part (sessions, file touches, prompts) and run async, so the conversation is not slowed. The Sonnet subagent writes nodes in the background; the main agent does not wait for it.
Try it
/plugin marketplace add jsk4581/session-trail
/plugin install session-trail@session-trail
Work as usual, then /session-trail:view opens the timeline.
Repo: https://github.com/jsk4581/session-trail (MIT)
I would like to hear what else you would want on a timeline like this, and how you keep track of work that spans many agent sessions today.
Top comments (0)