Browse, search and export your Claude Code chat histories from the terminal.
The repo ships two tools that share the same data layer:
| Tool | What it is | Best for |
|---|---|---|
claude-history-tui.py (ch-tui) |
Full-screen interactive browser (textual) | Finding and reading a conversation, deleting sessions, exporting markdown |
claude-history-browser.py (ch) |
One-shot CLI (rich) | Scripting, piping, grepping across every session |
Both read ~/.claude/ read-only (except the TUI's explicit delete and markdown
export), and both honour CLAUDE_CONFIG_DIR if you point Claude Code elsewhere.
Interactive TUI (ch-tui)
- 🖥️ Session list with vim-like navigation and a live detail preview pane
- 🔍 Filter as you type by summary, first prompt, branch or project
- 📁 Project filter by regex
- 👁️ Full conversation viewer with markdown rendering and collapsed "working..." chatter
- 🔎 In-document search —
/,?,n,Nwith highlighted hits and match counts - 🗑️ Delete sessions (transcript, index entry and file history) behind a confirmation
- 📝 Markdown export with smart caching, plus open-in-editor / open-in-viewer
- 📐 Columns stretch to the terminal width
CLI (ch)
- 📋 List all conversations with date, index status, summary, message count, branch and project
- 🔍 Search summaries, first prompts and branch names
- 🔎 Deep grep through every message body
- 📖 View a conversation in three layouts (
border,box,simple) - 📊 Statistics across your whole history
- 🎨 Rich output with a plain-text fallback when
richisn't installed
Both
- 🏷️ Session titles — a session's own title (one you set yourself, or Claude's AI-generated one) is used in place of the first-prompt summary
- ✅ Index status shows which sessions have an AI-generated summary yet
- 🗓️ Filters by branch, project path and date
# rich for the CLI output, textual for the TUI
pip install -r requirements.txtclaude-history-browser.py works without rich (it falls back to plain text).
textual is required for claude-history-tui.py — without it the TUI fails at
startup with ModuleNotFoundError: No module named 'textual'.
chmod +x claude-history-browser.py claude-history-tui.pysource /path/to/claude-code-history/claude-history-aliases.sh| Alias | Runs |
|---|---|
ch-tui |
The interactive TUI |
ch |
The CLI (any subcommand) |
ch-list |
ch list |
ch-search |
ch search |
ch-grep |
ch grep |
ch-view |
ch view |
ch-stats |
ch stats |
ch-recent |
10 most recent sessions |
ch-today |
Sessions modified today |
ch-proj <project> <cmd> |
Any command scoped to a project, e.g. ch-proj liquidity list |
Sourcing the file also exports COLUMNS=200 so the CLI tables get room to breathe.
Or add a single alias by hand:
alias claude-history='/path/to/claude-code-history/claude-history-browser.py'The CLI uses wide tables. For best results use a terminal at least 150 columns wide; below that some columns get squeezed. You can force a width:
COLUMNS=200 ./claude-history-browser.py listThe TUI adapts to whatever size the window is and re-flows on resize.
Both tools read $CLAUDE_CONFIG_DIR when it is set, falling back to ~/.claude:
CLAUDE_CONFIG_DIR=/data/me/.claude ch-tui./claude-history-tui.py
# or
ch-tui
# Start with a filter already applied
ch-tui --project liquidity-bot
ch-tui --branch main
ch-tui --since 2026-01-20 ⭘ Claude Code History Browser — 25 sessions
┌──────────────────────────────────────────────────────────┐┌────────────────────────┐
│ # MD Date Summary Msgs ││ Summary: Add in-doc │
│ 1 2026-01-30 19:44 Add in-doc search 101 ││ search │
│ 2 ✓ 2026-01-30 18:54 Auto-switching system 71 ││ │
│ 3 ✓ 2026-01-28 05:31 Regime improvements 27 ││ Messages: 101 │
│ ││ Branch: main │
└──────────────────────────────────────────────────────────┘└────────────────────────┘
q Quit d Delete m Edit MD v View MD / Search p Project r Refresh
(Branch and Project columns are cut off above; they sit to the right of Msgs.)
- MD —
✓when the cached markdown export is up to date with the transcript - Summary — the session's title if it has one, otherwise the first prompt
- The Summary / Branch / Project columns share the leftover width, so the table fills the window instead of leaving dead space on wide terminals
- The pane on the right previews the highlighted session: summary, message count, branch, project, created/modified timestamps, index status and the first prompt
| Key | Action |
|---|---|
j/k |
Navigate up/down |
Enter |
Open the session conversation |
d |
Delete session (with confirmation) |
m |
Edit markdown in your editor |
v |
View markdown in your viewer |
M |
Force regenerate markdown |
/ |
Filter sessions as you type |
p |
Project filter (regex) |
r |
Refresh the session list |
Esc |
Close the active filter |
q |
Quit |
The / filter matches against summary, first prompt, branch and project path.
Vim-style search inside the open conversation:
| Key | Action |
|---|---|
/ |
Search forwards - type to jump to hits as you type |
? |
Search backwards |
Enter |
Accept the search, hand focus back to the document |
n |
Jump to the next hit (same direction as the search) |
N |
Jump to the previous hit |
Esc |
Cancel the search / clear highlights, then leave the view |
j/k, PgUp/PgDn |
Scroll |
g/G or Ctrl-A/Ctrl-E |
Jump to top/bottom |
q |
Back to the session list |
Every hit is highlighted in yellow, the current one in cyan, and the bar at the
bottom shows 3/17 style match counts (plus (wrapped) when the search rolls
past the end). Searches are regex (an invalid pattern falls back to a literal
match) and case-insensitive unless the term contains an uppercase character,
like vim's smartcase.
Messages are rendered as markdown with a coloured left border per role. Empty and system-noise messages are dropped, and runs of short "working on it" assistant messages are collapsed into a single block, with a count of what was hidden at the end of the transcript.
d opens a confirmation modal listing exactly what will be removed (y to
confirm, n/Esc to back out):
- the session's
.jsonltranscript in~/.claude/projects/<project>/ - its entry in that project's
sessions-index.json - its file-history directory
~/.claude/file-history/<sessionId>/
Deletion is permanent — there is no undo.
The TUI generates and caches markdown files from your sessions:
- Location:
~/.claude/markdown/{project-hash}/{sessionId}.md - Caching: mtime comparison against the transcript for fast invalidation
- Background generation: stale files regenerate on startup
- MD column: shows
✓when the export is current
# [Summary or first prompt]
**Session ID:** `uuid`
**Project:** `/path/to/project`
**Branch:** `main`
**Created:** 2026-01-30 18:34
**Modified:** 2026-01-30 19:44
**Messages:** 42
---
## User (2026-01-30 18:34)
User message content...
---
## Assistant (2026-01-30 18:35)
Assistant response...
---Editor (m key):
CLAUDE_HISTORY_EDITORenvironment variableEDITORenvironment variablecursor(if available)open(macOS) /xdg-open(Linux)
Viewer (v key):
CLAUDE_HISTORY_MD_VIEWERenvironment variableopen(macOS - uses system default app)glow(Linux, if available)xdg-open(Linux fallback)
To use a specific app as your markdown viewer on macOS, set it as the default app for .md files in Finder (Get Info → Open with → Change All).
# List all conversations (sorted by date, newest first)
./claude-history-browser.py list
# Show only 10 most recent
./claude-history-browser.py list --limit 10
# Filter by branch
./claude-history-browser.py list --branch feature/my-branch
# Filter by project path (substring match)
./claude-history-browser.py list --project liquidity-bot
# Filter by date range
./claude-history-browser.py list --since 2026-01-20
./claude-history-browser.py list --until 2026-01-21
# A single day (--until covers all of it)
./claude-history-browser.py list --since 2026-01-20 --until 2026-01-20Transcript timestamps are UTC and the list shows them as written, so a bare
YYYY-MM-DD is read as a UTC calendar date: --since starts at 00:00 that
day and --until runs to the end of it. Both also accept a full ISO
timestamp (--since 2026-01-20T14:30), which is used exactly as given.
# Search for conversations about CompilerConfig
./claude-history-browser.py search "CompilerConfig"
# Limit results
./claude-history-browser.py search "BFP8" --limit 5# Search through all message content
./claude-history-browser.py grep "pytest"
# Case-sensitive search
./claude-history-browser.py grep "CompilerConfig" --case-sensitive
# Limit results
./claude-history-browser.py grep "YAML" --limit 3# View by session number (from list, search or grep -- they all agree)
./claude-history-browser.py view 1
# View by session ID, or any unambiguous prefix of it
./claude-history-browser.py view 81b9f767-88c1-4e70-9d90-4cc77c92b4f7
./claude-history-browser.py view 81b9f767
# View with no message truncation (default cap is 4000 chars per message)
./claude-history-browser.py view 1 --max-message-length 0
# Include thinking blocks (hidden by default)
./claude-history-browser.py view 1 --include-thinking
# Include empty messages like tool calls (hidden by default)
./claude-history-browser.py view 1 --include-empty
# Message layout: border (default), box (panels), simple (header+rule)
./claude-history-browser.py view 1 --format simple
# Border style for markdown tables inside messages
./claude-history-browser.py view 1 --table-box rounded
./claude-history-browser.py view 1 --table-box simple # rich's own borderless look
./claude-history-browser.py view 1 --no-table-row-lines # no rule between body rows
# Keep colours when piping
./claude-history-browser.py view 1 --color always | less -rThe # column is a global ID: every session gets its position in one
newest-first ordering of your whole history, and list, search, grep and
the TUI all print that same number. Whatever # you see, view N takes it —
filters never renumber anything.
The visible consequence is that a filtered listing has gaps:
$ ./claude-history-browser.py list --project claude-code-history
# Date Summary
1 2026-09-17 19:56 ch-grep table IDs mismatch with ch-view
4 2026-09-17 19:44 Claude Code History Speedup
27 2026-09-03 16:31 Claude Code History Search and Port Changes
44 2026-08-25 20:11 Claude Code History improvements
view 27 opens that third row with or without --project.
The numbers are positions, though, so they slide as sessions are created or touched — #4 today may be #6 tomorrow. For a handle that keeps working (a note, a script, a bookmark), use the session ID or a short prefix of it.
./claude-history-browser.py statsReports total sessions, total messages, average messages per session, and the number of unique branches and projects.
# 1. List recent conversations
./claude-history-browser.py list --limit 10
# 2. Search for something specific
./claude-history-browser.py search "CompilerConfig"
# 3. View the details of conversation #3
./claude-history-browser.py view 3
# 4. Deep search through all content
./claude-history-browser.py grep "test_models.py" Claude Code Sessions
╭────┬──────────────────┬─────┬────────────────────────────────────────────┬──────┬────────┬─────────────────────╮
│ # │ Date │ IDX │ Summary │ Msgs │ Branch │ Project │
├────┼──────────────────┼─────┼────────────────────────────────────────────┼──────┼────────┼─────────────────────┤
│ 1 │ 2026-01-30 19:44 │ │ Current active session... │ 101 │ main │ ~/project/myapp │
│ 2 │ 2026-01-30 18:54 │ ✓ │ Implementing Robust Auto-Switching System │ 71 │ main │ ~/project/bot │
│ 3 │ 2026-01-28 05:31 │ ✓ │ Auto-switch regime system improvements │ 27 │ main │ ~/project/bot │
╰────┴──────────────────┴─────┴────────────────────────────────────────────┴──────┴────────┴─────────────────────╯
Total sessions: 26
IDX column: ✓ = indexed, blank = not yet indexed (3 unindexed)
Column notes:
- IDX: ✓ if the session has an AI-generated summary, blank if not yet indexed
- Project: project path with
~for home directory - Columns resize to fit their content, and the text columns give space back
when the terminal is too narrow for the whole table — the
#column is kept intact so the number stays usable inview
Shows session metadata (summary, dates, branch, message count) followed by every
message with its role, timestamp and content, formatted per --format.
Markdown tables inside a message are drawn with full borders by default
(--table-box square):
┌──────────────────┬─────────────────────┬─────────────────────┐
│ │ chunk 2048 │ chunk 4096 │
├──────────────────┼─────────────────────┼─────────────────────┤
│ prior KV = 0 │ floor_c2048 (idx 0) │ floor_c4096 (idx 0) │
├──────────────────┼─────────────────────┼─────────────────────┤
│ prior KV = 49152 │ deep_c2048_i24 │ deep_c4096_i12 │
└──────────────────┴─────────────────────┴─────────────────────┘
--table-box takes square, rounded, heavy, minimal or simple;
simple is the borderless style rich renders by default, and
--no-table-row-lines drops the rule between body rows.
rich offers no setting for this — box.SIMPLE is hardcoded inside its
TableElement, with no argument and no theme key. The tool supplies its own
table element through Markdown.elements (the tag-to-class map rich exposes),
which leaves rich's globals alone; if those internals ever change shape, the
table falls back to rich's own rendering rather than disappearing.
Shows which sessions contain the term, the number of matches per session, and a
preview of the matching content. The # is the same global session ID list
prints, so it feeds straight into view.
Both tools read from ~/.claude/ (or $CLAUDE_CONFIG_DIR), where Claude Code
stores its history:
~/.claude/projects/<project-hash>/— one.jsonltranscript per session~/.claude/projects/<project-hash>/sessions-index.json— metadata and AI-generated summaries~/.claude/file-history/<sessionId>/— file snapshots for a session~/.claude/markdown/<project-hash>/<sessionId>.md— markdown exports written by the TUI
Both tools cache the per-session facts they need for the list (title, first
prompt, message count, timestamps, branch, project) in
~/.cache/claude-history-browser/session-metadata.json (or
$XDG_CACHE_HOME), and share the one file. Entries are keyed on each
transcript's size and mtime, so an appended or renamed session is rescanned
automatically and deleted ones are dropped. A cached entry holds only facts
about the file, never either tool's formatting of them, so it doesn't matter
which tool wrote it. Nothing is written inside ~/.claude; delete the cache
file any time and the next run rebuilds it.
The same file also caches each directory's listing, keyed on the directory's mtime. Reading a directory is a round trip that no attribute cache absorbs — about 7ms each against an NFS-mounted Claude dir, however few entries it holds — and a listing does one per project plus one for the root. A directory's mtime changes whenever an entry is added or removed, which is exactly when its listing would differ, so a single stat stands in for re-reading it. Appending to a transcript doesn't touch its directory and doesn't need to: the per-file stamp already covers that.
Because both tools read the same file, its version marker has to be bumped in both at once — otherwise each run would discard the other's work and both would get slower.
A session's display name is picked in this order:
- Custom title — a title you set yourself, stored as a
custom-titleentry in the transcript - AI title — Claude's own generated title, stored as an
ai-titleentry - Indexed summary — the AI summary in
sessions-index.json - First prompt — the first line of your opening message, truncated
Claude Code uses lazy indexing — sessions are indexed when you close the next session, not the current one:
- Indexed (✓): has an AI-generated summary in
sessions-index.json - Unindexed (blank): the transcript exists but isn't in the index yet
(active session, or never revisited). These are read straight from the
.jsonl, so they still show up in both tools.
To index old sessions, start and /exit a new session in that project directory.
- Reading a conversation? Use the TUI.
ch-tui,Enter, then/to find the bit you want - Use grep for code/function searches: if you remember a specific function or file, use
greprather thansearch - Use search for topic searches: if you remember the topic but not exact terms, use
search - Pipe to less for long outputs:
./claude-history-browser.py view 1 --color always | less -r - Combine with shell tools:
./claude-history-browser.py list | grep qwen - Filter by project:
--project(orch-proj) quickly narrows to one codebase - Clean view output: tool calls and thinking blocks are hidden by default — add
--include-thinking/--include-emptyto see them
Install with pip install rich. The CLI still works without it, just with basic
text output.
The TUI (ch-tui) requires textual, unlike claude-history-browser.py which
only needs rich. Install with pip install textual (or
pip install -r requirements.txt for both).
Make sure Claude Code has been run at least once in your project directory, and
that CLAUDE_CONFIG_DIR points at the right place if you have moved it.
Make the scripts executable: chmod +x claude-history-browser.py claude-history-tui.py
- JSON output mode -
list --jsonfor scripting/piping tojq - Show files mentioned - Extract file paths discussed in a session (useful for "what did I work on?")
- Better stats - Activity by day/week, most active projects, average session length
- Regex search -
grep --regex "def \w+\("for pattern matching - Message count filter -
list --min-messages 50to find substantial conversations - Diff sessions - Compare two related sessions to see what changed
- Copy session ID to clipboard - Quick
view 3 --copy-id - Continuation chain - Show which sessions were continued from others (detect "This session is being continued")
- Timeline/calendar view - Visual activity heatmap
Feel free to extend this tool. Both scripts carry their own copy of the
ClaudeHistoryBrowser data layer (session discovery, metadata, titles), so a
change to how sessions are read usually needs applying to both.
claude-history-browser.py:
ClaudeHistoryBrowser— core data accessRichDisplay/BasicDisplay— rich UI and plain-text fallback
claude-history-tui.py:
ClaudeHistoryTUI— the app: session list, filters, previewSessionViewerScreen— conversation view and in-document searchInstantScrollRichLog— the log widget: instant scrolling and hit highlightingMarkdownGenerator— markdown export, caching, editor/viewer launchingSessionDeletionService— works out and removes a session's files
Enjoy browsing your Claude Code history! 🚀