ClaudeTimeline

Stop losing your conversation to terminal scrollback. A thin wrapper for claude --resume that dumps the session's chat history to less -R before Claude Code starts, so you can scroll back through long conversations that would otherwise be gone.

The Problem

When you run claude --resume <session-id>, the terminal scrollback gets overwritten as Claude Code starts. If you scroll up to find context from earlier in the conversation, it's gone. For long sessions — multi-hour debugging marathons, complex refactors, design explorations — losing that history is painful.

The Solution

ClaudeTimeline installs a tiny claude shim on your PATH that intercepts --resume, dumps the session transcript to your terminal's pager (less -R with ANSI colors), and only then hands off to the real claude:

$ claude --resume 4779032a-...
    ┌──────────────────────────────────────────────┐
    │  ─── User ───                               │
    │  Please analyze this codebase...            │
    │                                              │
    │  ─── Assistant ───                           │
    │  [previous Claude response, in color]        │
    │                                              │
    │  ─── User ───                               │
    │  Now add OAuth support...                   │
    │  ...                                        │
    └──────────────────────────────────────────────┘
    (press q to exit less)
[Claude Code starts with full history visible]

Bare claude (no --resume) is passed through with zero overhead.

Install

pipx install claude-resume-dump   # recommended: isolated env, adds to PATH
# or
pip install --user claude-resume-dump

Then install the shim:

claude-resume-dump install
# → Shim written to ~/.local/bin/claude
# → Add ~/.local/bin to your PATH if not already (the command prints the export line)

Verify:

which claude                   # should print ~/.local/bin/claude
claude-resume-dump --version

Quickstart

# 1. Find a session to resume
claude-resume-dump list
# SESSION_ID                          MTIME               MSGS  PATH
# 4779032a-2cf3-4564-b24d-...        2026-06-08 11:53    110   ...

# 2. Resume it — history is dumped to less first
claude --resume 4779032a-2cf3-4564-b24d-15438c83b3c5

# 3. Or inspect without launching
claude-resume-dump show 4779032a-2cf3-4564-b24d-15438c83b3c5 | less -R

# 4. Search across all your sessions
claude-resume-dump grep "OAuth"

# 5. Export a session as markdown
claude-resume-dump export 4779032a-2cf3-4564-b24d-15438c83b3c5 --output session.md

Subcommand reference

The --cwd flag uses the Claude Code project encoding (slashes and spaces become dashes). For most users the auto-detection from pwd is correct.

How it works

The shim is a 50-line bash (or Windows .cmd / .ps1) script that:

1. Checks if $@ contains --resume.
2. If not: execs the real claude "$@" — zero overhead, transparent.
3. If yes: extracts the resume ID, computes the encoded cwd (same scheme Claude Code uses for ~/.claude/projects/), calls claude-resume-dump dump <encoded-cwd> <resume-id> | less -FRX, then execs the real claude --resume <id> "$@".

The dump subcommand reads ~/.claude/projects/<encoded-cwd>/<resume-id>.jsonl, parses out user/assistant messages, and prints them with ANSI colors. tool_use and thinking blocks are filtered out — only the actual conversation renders.

Platform notes

PowerShell flavor is shipped (claude.ps1) but not auto-installed on Windows. To use it manually, point your PowerShell profile's $env:PATH at the PowerShell shim location.

Troubleshooting

claude-resume-dump: command not found — your pipx/pip install dir isn't on PATH. Re-run claude-resume-dump install and follow the printed export PATH=... line.

Permission denied when running claude after install — the shim isn't executable. Fix: chmod +x ~/.local/bin/claude.

History dump is empty — your session ID is wrong, or the .jsonl file was rotated. Run claude-resume-dump list to find valid IDs.

claude is the wrong binary (still the real one, not the shim) — your shell is hashing claude from a different PATH entry. Verify with which -a claude; the shim should come first.

Want to uninstall — claude-resume-dump uninstall removes the shim and the persisted config. The real claude binary is untouched.

Development

git clone https://github.com/yourname/claude-timeline
cd claude-timeline
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest                  # 54 tests, ~1s
ruff check src/ tests/
ruff format src/ tests/
mypy src

Project layout follows the standard src/ layout for hatchling:

src/claude_timeline/
  __init__.py        # version
  cli.py             # Click commands (7 subcommands)
  jsonl_parser.py    # .jsonl → list[Message]
  render.py          # list[Message] → ANSI string
  shim.py            # shim template + install/uninstall
  config.py          # XDG/Roaming TOML config

tests/
  test_jsonl_parser.py   # uses tests/fixtures/real-session.jsonl
  test_render.py
  test_config.py
  test_shim.py
  test_cli.py            # Click CliRunner integration
  fixtures/real-session.jsonl

See docs/001-claude-timeline-prd.md for the full design rationale and docs/progress.md for current phase status.

License

MIT — see LICENSE.