How to Read Aider Chat History Files Like Real Documents

Aider drops a file called .aider.chat.history.md into every project it touches. That file is where every prompt, every diff, every reasoning trace, and every command output lives. It is real markdown, which is the good news. It is also thousands of lines of interleaved prose and fenced code with no navigation, which is the bad news. If you have been scrolling through it in your editor and losing your place every time you close the tab, there is a better way to read it. Most Aider users I know treat the file as write-only, which is a waste of the best paper trail their AI tools produce.

This guide walks through the shape of the file, why terminals and IDEs make poor readers for it, and how to turn it into something you can study on a couch or a train. The tools involved are cheap or free, the workflow takes about ten minutes to set up, and the payoff shows up the next time you want to remember why you asked the model to refactor a function two weeks ago. None of the steps require a plugin, a subscription, or a change to how you already run Aider. If you can copy a file and open it in a browser, you can do this.

What Aider Writes to Disk

Aider is a terminal-based AI pair programmer that edits files in your git repo. Every session appends to .aider.chat.history.md at the repo root, plus a JSON companion at .aider.input.history for your raw prompts. The markdown file is the interesting one. It contains your requests, the model's replies, the exact search/replace blocks it proposed, the diffs it applied, and any linter or test output it reacted to. That combination makes it the closest thing to a working transcript of a coding session that any current AI tool produces.

Because the file grows forever by default, a two-week project can easily push it past ten thousand lines. The Aider docs on chat history note you can clear it with /clear or split it with /reset, but most people never do. That is fine for grep. It is miserable for reading, and it means the file drifts further from anything a normal markdown viewer can handle in one screen.

The other quirk is that Aider wraps model output in HTML comments and fenced blocks that some renderers choke on. Any reader you pick has to handle nested fences and long code cells without collapsing them into a mess. Diff blocks with plus and minus prefixes need to survive as code, not as a mangled bullet list. If the reader reformats those, you lose the ability to see exactly what the model proposed to change.

Why the Terminal and Your IDE Are Bad Readers

VS Code will open the file, but the built-in markdown preview treats it as one giant document with no outline. There are no per-turn anchors. Search jumps you around but you lose context. If you close the split, you lose your scroll position. If the file passes about five megabytes, the preview stops updating live, and you end up staring at a spinner instead of the content you came for.

Terminals are worse in a different way. less gives you search but no formatting, so code blocks and prose blur together on the screen. bat colors things nicely but has no navigation for a file this size, and it forces you to work through a pager rather than skim by section. Neither tool lets you skim by heading or bookmark a spot you want to return to, which is the exact behavior you want when reviewing a long session.

The core issue is that .aider.chat.history.md is not one document. It is a stream of conversation turns concatenated into one file. You want to read it the way you read a chat log with real turn boundaries, not the way you read a README. Treating it as prose fails, and treating it as pure code fails too. It sits in a middle category that most editors were never designed to handle.

Turning the History Into a Readable Document

The move is to open the file in a reader that understands markdown as a first-class format and treats each session or turn as its own navigable chunk. That is exactly what Prism MD was built for. You point it at the file, it renders the code blocks with proper syntax highlighting, and it gives you a table of contents built from the headings Aider already writes. The reading experience becomes closer to a technical article than a raw log.

A few things make Aider history specifically nicer to read this way. Long fenced code blocks stay scrollable inside their own container instead of blowing out the page width. Diff blocks get color, so you can see at a glance what Aider proposed to change. Your scroll position and highlights persist per file, so closing the tab does not cost you your place. The table of contents makes it possible to jump straight to the session where you fixed a specific bug, which is the query you will run most often.

If you want the file on your phone or tablet for offline reading, the workflow is the same as any other AI transcript. Sync the file through iCloud, Dropbox, or a git remote, then open it in a reader that handles offline files. The guide on reading Claude conversations offline on Android covers the sync side of that in more depth, and the same pattern applies here. Once the file is on the device, the reader does the rest of the work.

Splitting a Long History Into Sessions

If your .aider.chat.history.md has crossed the point where even a good reader feels slow, split it. Aider itself does not do this automatically, but the file uses a consistent header pattern for each session start, which makes a shell one-liner enough. A simple awk or csplit command keyed on the session header will produce one file per session, which you can then read in order or in isolation. This turns a single log into a small library.

Two habits pay off once you start doing this. First, rename each split file with a date and a short description of what you worked on, so future you can find the session where you refactored the auth module. Second, keep the split files in a history/ folder next to the repo, out of git if the content is sensitive, and treat them like a lab notebook. If you want a strict checklist:

1. Split by session header with csplit or awk.
2. Rename each file with the date and a short topic tag.

This is the same instinct behind organizing AI conversations by project and behind building a personal knowledge base from your AI chats. The history file is a record of your thinking with a tool. It is worth treating like one, especially once you notice how often you want to look up a past decision. A little structure at the storage layer makes the reading layer trivial.

FAQ

Does Aider have a built-in viewer for chat history?

No. Aider is a command-line tool focused on editing code, not reading old sessions. The /history slash command inside a running session shows recent turns, but there is no standalone viewer for the on-disk file. External readers are the only path to a comfortable reading experience.

Can I safely delete .aider.chat.history.md?

Yes. Aider will start a fresh file on the next run. Before you delete, consider archiving it, because the file often contains the reasoning behind decisions that are not obvious from the diff alone. A monthly archive folder is a low-effort way to keep the signal without letting the working file grow forever.

Should the history file be in git?

Usually no. It contains prompts, model responses, and sometimes secrets that appeared in your terminal output. The Aider project ships a default .gitignore entry for it, and keeping it that way is the safe default. Version it only if you have a specific reason and you have first scrubbed it for anything sensitive.

Will a large history slow Aider down?

The history file itself does not slow the tool at runtime. What slows things down is the context Aider sends to the model on each turn, which is controlled separately by the /tokens and /clear commands. Long history files are a reading problem, not a runtime one, and splitting the file will not change how the tool performs. Keep the two concerns separate in your head and you will make better choices about when to prune and when to open a better reader.