carn

README

carn

A terminal UI for browsing, searching, and managing your local Claude and Codex session archives.

What it does

You accumulate hundreds of AI coding sessions across different projects. They live as raw JSONL files scattered under ~/.claude/projects/ and ~/.codex/sessions/. carn indexes them into a local SQLite store and gives you a fast, searchable TUI to browse conversations, read transcripts, and resume sessions — without leaving the terminal.

Features

Browsing

• Conversation list with model, token count, duration, tool usage, and git branch
• filter by provider, project, model, git branch, plan status, or multi-part conversations — with regex support
• Automatic grouping of related sessions into multi-part conversations
• Subagent detection and display
• Split and fullscreen layout modes with tab to switch focus

Search

• Search (/) — debounced full-text search across all message content via the SQLite FTS index; an empty query returns to the full conversation list
• Structured filters (f) handle provider, project, model, git branch, plan, and multi-part narrowing
• Search preview snippets in results

Transcript viewer

• Markdown rendering with syntax highlighting
• Toggleable sections: thinking blocks, Tool calls, tool Results, sidechain messages, system messages, plans
• Diff display with colored additions and removals
• Search within transcript (/) with next / N previous match navigation

Actions

• resume a session in the original provider with correct working directory — works for both Claude and Codex sessions
• Copy to clipboard — pick a target: conversation, plan, or raw source files
• export conversation as Markdown
• open conversation, plan, or raw files in $EDITOR
• Resync from source directories without restarting

First launch

On first run, carn shows an import overview with source and archive paths, configuration status, and file counts. Press enter to import, or configure settings before proceeding.

Installation

Homebrew (macOS and Linux)

brew install rkuska/carn/carn

Binary download

Download a pre-built binary from Releases and place it in your $PATH.

From source

Requires Go 1.25.2 or later. SQLite is bundled — no external dependencies.

go install github.com/rkuska/carn@latest

Or build manually:

git clone https://github.com/rkuska/carn
cd carn
go build -o carn .

On first launch, carn scans source directories and builds its canonical store at ~/.local/share/carn/. Subsequent launches detect changes and rebuild incrementally.

Configuration

Configuration is optional. All settings have sensible defaults.

Create a config file at ~/.config/carn/config.toml (or $XDG_CONFIG_HOME/carn/config.toml):

# Source and archive directory paths.
[paths]
# archive_dir = "~/.local/share/carn"
# claude_source_dir = "~/.claude/projects"
# codex_source_dir = "~/.codex/sessions"
# log_file = "~/.local/state/carn/carn.log"

# Display preferences.
[display]
# Go time format for timestamps shown in headers and metadata.
# timestamp_format = "2006-01-02 15:04"

# Number of loaded transcripts to keep in the browser cache.
# browser_cache_size = 20

# Search behavior.
[search]
# Milliseconds to wait before triggering a deep search query.
# deep_search_debounce_ms = 200

# Logging behavior.
[logging]
# Log verbosity: debug, info, warn, error.
# level = "info"
# Maximum log file size in megabytes before rotation.
# max_size_mb = 10
# Number of rotated log files to keep.
# max_backups = 3

Set DEBUG=1 to force debug-level logging.

Keybindings

Press ? at any time to open the help overlay.

Browser

Key	Action
j / k	Move up / down
gg / G	Jump to top / bottom
ctrl+f / ctrl+b	Page down / up
enter	Open conversation
/	Search conversations
ctrl+l	Clear active search
f	filter dialog
O	Toggle fullscreen / split layout
tab	Toggle focus between list and transcript
r	resume session in provider
R	Resync conversations from source
o	open session in editor
?	Help
q / ctrl+c	Quit

Transcript viewer

Key	Action
j / k	Scroll up / down
gg / G	Jump to top / bottom
ctrl+f / ctrl+b	Page down / up
/	Search transcript
n / N	next / previous match
t	Toggle thinking blocks
T	Toggle Tool calls
R	Toggle tool Results
p	Toggle plans
s	Toggle sidechain messages
m	Toggle system messages
y	Copy — choose target: conversation, plan, or raw
o	open — choose target: conversation, plan, or raw
e	export as Markdown
r	resume session
q / esc	Back to browser

Import overview

Key	Action
enter	Import / continue
c	configure settings in $EDITOR
?	Help
q / ctrl+c	Quit

How it works

Raw sessions (~/.claude/projects/, ~/.codex/sessions/)
  -> Scan and group by project + slug
  -> Parse metadata and messages
  -> Canonical SQLite store (~/.local/share/carn/)
     |- Conversation catalog
     |- Transcript blobs
     |- Full-text search index
  -> TUI browser, viewer, deep search

Source directories are never modified. All processed data lives in the archive directory and can be rebuilt from source at any time.

License

GPL-3.0. See LICENSE.