Skip to main content
← All posts
An East Asian developer in their 30s scrolling through a Plandex AI coding conversation on a tablet at a dark walnut desk, warm coral accents glowing against a near-black UI, brass desk lamp lighting the scene from the left.
·7 min read

How to Find and Read Plandex Chat History: Step-by-Step Guide

Where Plandex stores conversation history, how to export plans to markdown with jq, and how to read long planning sessions on any device.

Plandex is a terminal-based AI coding agent that keeps every plan, every rollback, and every conversation turn in a local project directory. That is great for reproducibility and audit trails. It is less great when you want to review a long Plandex session on a phone, a tablet, or any surface that is not a cramped terminal pane. The transcripts live in plain files on your disk, but they are split across directories, mixed with metadata, and formatted for the CLI rather than for human reading. If you have ever tried to understand what happened in a four-hour planning session by scrolling the Plandex REPL, you know the frustration. This guide shows where Plandex stores its chat history, how to pull a clean copy out, and how to read it in a reader built for AI output. Everything below works on macOS, Linux, and Windows WSL without extra tooling beyond jq.

Where Plandex keeps your chat history

Plandex writes everything to a .plandex-v2 directory inside the project you ran it against. If you started Plandex in ~/code/my-app, the history lives under ~/code/my-app/.plandex-v2, and it survives shell restarts, laptop reboots, and most editor crashes. The directory is safe to back up with the rest of your project, though many teams gitignore it to avoid committing conversation noise alongside code. Inside that folder you will find one subdirectory per plan, each containing a few predictable pieces:

  • A convo folder with numbered JSON message files, one per conversation turn.
  • A context folder with the files Plandex loaded into working memory.
  • A logs folder with the per-step diffs it proposed, applied, or rolled back.
  • A plan.json with metadata like the plan name, model, and branch.

The messages themselves are plain JSON on disk, with the markdown body sitting inside a message field, the role in a role field, and timestamps on every turn. That is the field you want when exporting, because it holds the formatted output the CLI printed. The Plandex CLI shows these messages one at a time in a pager, so you never see the full arc of a session in a single scrollable view. For a broader primer on this problem across tools, the LLM CLI chat history guide covers the general pattern across coding agents. Plandex happens to be one of the cleanest implementations because every turn is a discrete file with a stable schema, which makes scripting against the history trivial.

How to export a Plandex conversation to markdown

The fastest way to get a readable file is to concatenate the JSON messages in order and extract the markdown field. A one-liner with jq handles it in under a second, even for sessions with hundreds of turns. The sorted glob ensures the messages come out in chronological order rather than alphabetical by filename, which matters once you cross ten messages. From the project root, change into the convo folder for the plan you care about and run the pipeline below.

cd .plandex-v2/plans/<plan-id>/convo
ls *.json | sort -n | xargs -I {} jq -r '.message' {} > ~/plandex-session.md

That produces a single markdown file with the full back-and-forth, in order, with code blocks intact and roles preserved. Plandex sometimes writes extra metadata around each turn, like model IDs and token counts, which you can strip with a quick sed pass if the noise bothers you. Keep the assistant turns verbose: those are where the planning logic lives, and trimming them defeats the point of the export. The official Plandex docs also cover the plandex convo command, which prints the current branch to stdout, and you can redirect that into a file for a quicker shareable transcript. The GitHub repo at plandex-ai/plandex has the current flag list, the release notes, and the schema reference if you want to script something more involved than a flat concat.

Why reading Plandex sessions matters

Plandex is unusual among coding agents because it stages changes before applying them. Every proposed diff gets its own entry in the convo log, along with the model's reasoning for the choice, the files it touched, and the rollback point. If you only ever accept or reject at the prompt, you miss the explanation and lose the chance to spot shaky reasoning before it ships. Pulling the full session into a reader lets you see the thinking next to the diff, which is how you catch the subtle mistakes before they land in your main branch. It is also how you learn what the model is good at and where it tends to overreach, which pays off every time you plan the next feature.

This pairs well with how you would review AI coding agent transcripts in general across any tool. The pattern is the same across the ecosystem: get the file out of the agent, read it somewhere the typography does not fight you, highlight what matters, and archive the rest for later reference. Teams that review Plandex sessions as a group tend to catch regressions earlier because the full reasoning sits in one place rather than scattered across terminal scrollback that nobody wants to replay. Shared reading also surfaces team-level patterns, like which prompts consistently produce clean diffs and which ones send the agent on long detours. Over months, that archive becomes a kind of institutional memory for how your team works with a given model.

Reading the exported session in Prism MD

Once you have the markdown file, upload it to Prism MD and the reader handles the rest without configuration. Code blocks get proper syntax highlighting with a monospace font picked for long sessions, and language detection runs on the fence hint so your Go, Rust, and TypeScript blocks all look distinct. Headings get real hierarchy with generous spacing between sections, so a plan with a dozen H2s stays scannable. If Plandex produced a Mermaid diagram inside a plan, Prism MD renders it inline rather than showing the raw code fence. If the model wrote math expressions in LaTeX, KaTeX rendering kicks in automatically with no extra setup or client-side flags.

The reader also keeps your position across devices through a sync layer tied to your account. Start a review on your laptop, continue on your phone during a commute, finish on a tablet in bed, and the scroll state follows the document rather than the device. For long planning sessions that run several thousand words, this is the difference between reviewing the whole plan and giving up halfway through. Dark mode uses warm coral accents against near-black backgrounds, which is easier on the eyes than the pure white of most code editors during a late-night review. Line length stays around sixty-five characters, which research on reading comprehension has repeatedly flagged as the comfortable range for sustained reading. The outline rail on the side shows every H2 and H3 in the session, so jumping to the step where Plandex proposed the database migration takes one tap instead of a page of scrolling.

FAQ

Does Plandex store chat history in the cloud

Plandex does not store conversation history in the cloud by default. The agent runs locally on your machine and the convo files sit under the .plandex-v2 directory in your project root. The hosted Plandex Cloud service does store sessions server-side for teams that opt in to the paid tier, but you can still export those sessions with the CLI and read them anywhere you want. If you need to move a conversation between machines, copying the plan folder is enough to preserve the full history.

Can I read Plandex sessions on my phone

Yes, and that is the whole point of exporting. Export the convo to markdown with the jq command above, upload the file to Prism MD, and open the resulting URL on your phone. The reader is mobile-first, so long planning sessions stay readable without pinch-zoom or horizontal scroll on narrow screens. Code blocks wrap gracefully and the outline rail collapses into a drawer so the main reading surface stays the full width of the viewport.

How do I find the plan ID I want to export

Run plandex plans from the project directory to list every plan Plandex knows about. The output includes the ID, the name you gave it, the model it used, and the last-updated timestamp. Match the ID to the folder under .plandex-v2/plans/ and export from there with the jq pipeline shown above. If you have dozens of plans, piping the output through grep on the name is the fastest way to find the right one.

What if my Plandex session is thousands of messages long

That is where a dedicated reader pays off most. Prism MD renders the full file but keeps navigation fast, so you can skim the outline, jump to a specific step, and read only the sections that matter without the browser stuttering on the file size. The sync layer also means you can leave the session open on a tablet and return to it days later without losing your place. For sessions that cross ten thousand messages, split the export by date range using the timestamps in the JSON before uploading.

Read your Plandex sessions anywhere

Free to start — no credit card.

Get started free →

Related reading

Ready to read your own AI documents?

Open ChatGPT, Claude, Gemini, or any markdown file in the reader built for the way models write.

  • ✓Renders code, math & Mermaid out of the box
  • ✓Works offline once you've opened a doc
  • ✓Free forever for personal reading