
How to Read Cursor Background Agent Chat History (2026)
Where Cursor Background Agent transcripts live on disk, how to export a full session, and how to read 20,000 word runs without a cramped side panel.
Cursor Background Agents run while you work on something else. They open their own branch, iterate on a task, and come back with a diff and a transcript. The transcript is the part most people never read, and it is where the real reasoning lives. If you want to understand why the agent chose one approach over another, or why it quietly skipped a file, you have to open the full log. A quick glance at the diff rarely tells the full story.
This guide shows where Background Agent chat history is stored, how to export it, and how to read it without losing your mind in a cramped side panel. The side panel is fine for a status check during the run. For a full session with code blocks, tool calls, and reasoning, you want a proper reader. Treat the transcript as a document rather than a sidebar notification.
Where Cursor Stores Background Agent Transcripts
Cursor keeps Background Agent sessions in two places. The live session view is inside the Cursor app under the Background Agents tab, which lists every active and completed run with a status chip. The persistent store is in Cursor's user data folder, where each session is written as a JSON record alongside its linked git branch metadata. If you want to grep across many runs, the on-disk copy is the one to target.
On macOS the path is ~/Library/Application Support/Cursor/User/globalStorage/cursor.background-agents/. On Windows it is %APPDATA%\Cursor\User\globalStorage\cursor.background-agents\. On Linux you will find it at ~/.config/Cursor/User/globalStorage/cursor.background-agents/. Inside, each session has its own folder with session.json, a messages/ directory of turn-by-turn records, and a tool-calls/ directory for file edits and shell runs.
The JSON is structured but not pretty. Opening one in a text editor gives you a wall of escaped markdown with inline tool payloads. This is why reading it in-place is painful and why most teammates give up after the first scroll. The format mirrors what Cursor's local chat history uses, which we covered in our Cursor chat history guide, so if you have read that one the shape will feel familiar.
Exporting a Session for Reading Elsewhere
Cursor added a copy-to-clipboard button for Background Agent transcripts in the 0.47 release. Open the session in the Background Agents panel, click the three-dot menu on the session header, and choose Copy Full Transcript. You get a markdown blob with every user message, every assistant turn, every tool call, and the final diff summary. Paste that into any markdown reader and you have a clean copy within seconds.
For a cleaner export, grab the raw files directly. The steps are short and the result is a portable artifact you can archive, diff, or share with a teammate. Working from the raw folder also preserves tool-call payloads that the clipboard export sometimes truncates for long shell outputs. The checklist below covers the common case:
- Navigate to the session folder in your file manager
- Zip the folder for safekeeping or send it to a markdown reader
- Open
session.jsonwithjqif you want to grep for a specific tool call - Keep the
tool-calls/folder intact if you want to replay what the agent ran
The copy button is faster for a quick read while the context is still fresh in your head. The raw folder is better when you want to diff two sessions or share a session with a teammate who does not use Cursor. Pick the path that matches how often you plan to revisit the run. Both outputs render identically in a proper markdown reader, so there is no quality loss in choosing one over the other.
Reading the Transcript Without a Headache
A Background Agent transcript is long. A single feature-sized task can produce 20,000 words of agent reasoning, tool output, and diff context. Scrolling that in Cursor's side panel at 320 pixels wide is a punishment. The panel also strips code block borders and inlines tool payloads in a way that breaks visual rhythm.
Prism MD was built for this. Paste the exported markdown and you get full-width typography, proper code blocks with language detection, collapsible tool calls, and a persistent reading position. KaTeX renders inline math if the agent wrote any. Mermaid blocks render as diagrams rather than fenced source, and our writeup on handling long code blocks in AI answers covers the specific layout decisions that make a 2,000-line transcript readable instead of punishing.
For offline work, Prism MD caches your imported transcripts locally. On a flight or in a coffee shop with flaky wifi you can still open the full history and keep reading. The read-side is a progressive web app, so it installs to your home screen and opens like a native reader. If you are also reading Claude Code sessions, our Claude Code chat history guide covers the same offline flow for Anthropic's agent.
When to Save vs When to Delete
Not every Background Agent session is worth keeping. If the agent ran a trivial lint fix or renamed a variable, delete the transcript when you merge the PR. The signal to noise is low and the storage is wasted. A graveyard of trivial runs makes it harder to find the sessions that matter when you search months later.
If the agent wrestled with a tricky migration, picked between two architectural options, or wrote a non-obvious piece of logic, keep the transcript indefinitely. A kept transcript is a design document you did not have to write. Six weeks from now when you ask why a particular adapter looks the way it does, the agent's reasoning is sitting right there. The extract action items from AI conversations workflow pairs well here: skim the transcript, pull the three or four decisions worth remembering, and let the rest sit as evidence.
FAQ
Does Cursor sync Background Agent sessions across devices? No, the sessions live in local user storage and never leave the machine on their own. If you switch machines, you lose access unless you manually copy the folder or export the transcript before switching. Exporting to a markdown reader before you swap laptops is the safe move. A cloud-synced reader like Prism MD then keeps the content available across devices even though Cursor itself does not.
Can I read a Background Agent transcript without opening Cursor? Yes, and the workflow is simple. Copy the session folder off to any device and open it with a markdown reader. The structure is JSON wrapping markdown, so any tool that can render markdown and expand JSON works. Prism MD does this natively and keeps the tool-call blocks collapsible so the signal stays visible.
Why is my transcript missing the last few turns?
If Cursor crashes mid-session or you force-quit the app, the final turns may still be in memory and not yet written to disk. Let the agent finish and the status chip turn green before closing the window. A clean exit flushes the pending writes and preserves the full run. If you suspect a truncated session, check the modification time on session.json against the last turn you saw in the panel.
Are Background Agent transcripts private? The session content is sent to Cursor's servers for the model to run on. The local copy stays on your machine for as long as you keep it. If you need a fully local workflow, the Background Agent product is not the right fit for that constraint. Local chat history from other tools can still live on your device and feed into the same reader.
Keep Your Agent Reasoning Readable
Background Agents are only as useful as the record they leave behind. A transcript buried in a 320-pixel side panel is a transcript nobody reads. A transcript opened in a proper reader is a design document, a debugging log, and a teaching artifact at once. Treat the export step as part of finishing the task, not an afterthought once the branch is merged.
Read your Cursor Background Agent runs the way they deserve.
Free to start — no credit card.
Related reading

Opencode Chat History: Where Files Live and How to Read Them (2026)
7 min read · opencode · chat history

How to Read Microsoft Copilot (365) Chat History in 2026
7 min read · microsoft copilot · copilot 365

Factory AI Droid Chat History: Where Sessions Live and How to Export Them (2026)
7 min read · factory ai · droid
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