deja-claude

A keyboard-driven TUI for browsing, previewing, and managing Claude Code conversation sessions.

Claude Code stores every conversation as JSONL files in ~/.claude/projects/. With hundreds of sessions, there's no good way to browse, search, preview, or manage them. deja-claude gives you a lazydocker-style interface to navigate your session history.

Installation

With pipx (recommended):

pipx install deja-claude

With pip:

pip install deja-claude

From source:

git clone https://github.com/alpamayo-solutions/deja-claude.git
cd deja-claude
pip install -e ".[dev]"

Usage

deja-claude                          # browse all sessions
deja-claude /path/to/project         # filter to sessions from that folder

The optional path argument filters sessions to only those whose working directory matches the given folder. Without it, the default_folder from settings is used (defaults to ~, which shows everything).

The interface has three panels:

• Left: Project tree with session counts -- navigate to filter instantly
• Center: Session list -- searchable, shows last message from each session
• Right: Conversation preview with styled text

Keyboard Shortcuts

Navigation

Actions

Display

Configuration

Settings are stored in ~/.config/deja-claude/settings.json:

{
    "default_folder": "~",
    "show_tool_messages": false,
    "show_thinking": false,
    "sort_by": "date",
    "sort_descending": true,
    "export_dir": "~/Desktop"
}

Session names (set with r) are stored in ~/.config/deja-claude/metadata.json and persist across restarts.

How It Works

Index scan (~100ms at startup):

• Walks ~/.claude/projects/*/ for JSONL files
• Reads head + tail of each file to extract metadata and last message
• Cross-references with ~/.claude/history.jsonl for fallback display text

Preview (on session select):

• Reads the last 512KB of the file (handles 40MB+ sessions without lag)
• Renders the last 40 turns as styled text in a single widget
• Debounced to stay responsive during rapid scrolling

Open in terminal:

• cds into the session's original working directory
• Runs claude -r {session_id} via Textual's app.suspend()
• When the Claude session ends, deja-claude resumes automatically

Requirements

• Python 3.10+
• Textual (installed automatically)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT