Skip to main content
← All posts
A 30s East Asian software engineer at a dark walnut desk reviewing structured JSON session files on an open laptop, warm coral desk lamp casting focused light, Monocle editorial style
·7 min read

Opencode Chat History: Where Files Live and How to Read Them (2026)

Where Opencode stores its session JSON on macOS, Linux, and Windows, what the files contain, and how to resume, grep, or export them to clean markdown.

Opencode has quietly become the open-source answer to Claude Code for engineers who want a terminal coding agent without being locked to a single vendor. If you have been using it for a few weeks, you already have a sprawl of session files on disk. The question most people hit next is simple. Where does Opencode keep its chat history, and how do you read those files without squinting at raw JSON in a terminal pager.

This guide walks through the file paths on macOS, Linux, and Windows. It shows you what the session JSON contains at the field level, from role markers to tool call payloads. Then it covers the two reading paths worth your time: the built-in resume flow for jumping back into a session, and an external markdown reader for studying what the agent did. By the end you should know exactly where to point ls, grep, and your preferred reader.

Where Opencode Stores Session Files

Opencode writes session data to your platform's standard user data directory, scoped per project. On macOS, that resolves to ~/Library/Application Support/opencode/project/<project-hash>/storage/session/. On Linux following the XDG spec, you will find it at ~/.local/share/opencode/project/<project-hash>/storage/session/. On Windows, check %APPDATA%\opencode\project\<project-hash>\storage\session\.

The <project-hash> is a slug derived from the absolute path of the directory you ran opencode in. Each project you have used Opencode in gets its own folder, which keeps session files from one repo cleanly separated from another. Inside each session directory, you will see a info/ folder with session metadata, a message/ folder with the full turn-by-turn transcript, and sometimes a part/ folder for streamed message parts. Everything is plain JSON, one file per session or per message, with no proprietary database format to decode.

If you want to find the project-hash for your current directory without digging through folders, run opencode in the project root and open any session with /sessions. The path shown in the status bar maps directly to the storage folder on disk. For a broader look at how terminal agents handle this, our writeup on Codex CLI chat history covers a similar layout pattern used by the OpenAI tool. Keeping this mapping clear in your head pays off the first time you need to grep across months of sessions.

What Lives Inside a Session File

A single session is split across two or three files, which trips people up on first contact. The info/<session-id>.json file holds metadata: when the session started, which model was used, token totals, and the parent session if you forked. The message/<session-id>/<message-id>.json files hold the turns themselves, one file per message, with the role, the text content, any tool calls, and the tool results that came back. The split makes incremental writes cheap, since Opencode only has to append one new file per turn.

The schema is stable enough that you can grep across sessions for a specific prompt or tool invocation. Say you want to find every session where Opencode ran a database migration. A one-liner like grep -r "prisma migrate" ~/.local/share/opencode/project/*/storage/session/message/ returns the exact session IDs and message files to open. This beats scrolling back through a shell buffer that was wiped two restarts ago. It also makes session content amenable to any tool that reads markdown or JSON, which is the whole point of the plain-file approach.

The one wrinkle is streamed assistant responses. If a message was still generating when the session was closed abruptly, you may see a part/ folder with chunk files that never got coalesced into the final message JSON. Opencode usually recovers these on next launch, but if you are reading files directly, be aware the full text may be split across several part files for an incomplete turn. Writing a tiny coalesce script is a sensible one-time fix if you want clean reads.

Resuming vs. Reading: Two Different Jobs

The quickest way back into a conversation is opencode --continue from the project directory, which drops you into the most recent session with full context restored. For older sessions, opencode followed by the /sessions command inside the TUI gives you a picker. This is the right path when you want to keep working. The agent reloads the full history and you pick up from where you left off. Treat the TUI as a live cockpit, not an archive viewer.

Reading is a different job entirely. When you want to review what the agent did, extract a code block, share a snippet with a teammate, or build a knowledge base from your sessions, dropping back into the TUI is the wrong tool. The TUI is optimized for live interaction, not for scanning three hundred messages across a long session with code blocks, tool outputs, and diffs mixed together. The ergonomics of scrolling in a terminal collapse once a session gets past a few dozen turns.

For that, point a markdown reader at the session content. We built Prism MD specifically for this. Paste a session export, or load a converted markdown file, and you get proper code block syntax highlighting, collapsible tool outputs, inline math rendering if the agent wrote any equations, and typography that does not fatigue your eyes after two minutes. The same pattern applies to reading Claude Code chat history, which stores sessions in a similar per-project layout. Pick the right tool for the job and the friction drops to zero.

Exporting Sessions to Markdown

Opencode does not ship a native export command yet, but the JSON structure is simple enough to convert with a short script. The core idea is to read the info file for the session metadata, iterate the message/<session-id>/ directory in chronological order, and emit a markdown document with role headings and fenced code blocks for tool outputs. Fifty lines of Python or a dozen lines of jq plus a shell loop will get you there. The output is a single file you can open in any reader, commit to a notes repo, or paste into a longer document.

A minimal conversion flow looks like this. Read the session info JSON and emit a title line with the session summary and timestamp. For each message file sorted by creation time, emit an H2 with the role, either ## User or ## Assistant. Pass the message parts array through, rendering text parts as paragraphs and tool parts as fenced code blocks tagged with the tool name. Save the result as <session-id>.md and open it in your markdown reader of choice. The checklist below sticks the same flow in one scannable list for later reference:

  • Read the session info JSON and emit a title line with the session summary and timestamp
  • For each message file sorted by creation time, emit an H2 with the role (## User or ## Assistant)
  • Pass the message parts array through, rendering text parts as paragraphs and tool parts as fenced code blocks tagged with the tool name
  • Save the result as <session-id>.md and open it in your markdown reader

Once you have a markdown version, you can pipe sessions into any workflow you already use. Archive them in a notes system, diff two sessions to compare approaches, or search across a quarter of agent work with ripgrep. The export becomes the canonical form, and the raw JSON stays as a backup. Teams that review agent work in retros benefit most, since the markdown form reads cleanly in pull request descriptions and shared docs.

FAQ

Can I move Opencode's session folder to a different location?

Yes. Set the XDG_DATA_HOME environment variable on Linux or symlink the macOS Application Support folder to wherever you want sessions stored. This is useful if you want to put sessions on an encrypted volume or a synced drive like iCloud or Dropbox. Do it before starting a new session, not mid-conversation, to avoid confusing the file watcher.

How do I share a single Opencode session with someone else?

Grab the full message/<session-id>/ directory plus the matching info/<session-id>.json file and zip them. The recipient drops the files into their own Opencode storage directory under a project folder, and the session shows up in their /sessions list. For a cleaner share, convert to markdown first and send the single file. Markdown travels better across Slack, email, and docs.

Do old sessions ever get deleted automatically?

No. Opencode retains sessions indefinitely by default. Over time this folder grows, so periodically archiving older sessions to compressed markdown is a reasonable hygiene step. You can see a similar long-term approach in our guide on archiving AI conversations. A quarterly cleanup script is usually enough.

Why are some sessions missing their final assistant response?

Usually because the session was ended before the stream finished. Check the part/ folder for that session. If chunk files are present, you can concatenate them manually to recover the partial response. Future Opencode versions may finalize these on exit, but today the recovery step is a manual one.

Read your Opencode sessions like real docs

Free to start — no credit card.

Try Prism MD 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