Metadata-Version: 2.4
Name: claude-resume-dump
Version: 0.1.4
Summary: Thin wrapper for `claude --resume` that dumps session history to less before launch.
Project-URL: Homepage, https://github.com/Ricardo-Ray/claude-timeline
Project-URL: Repository, https://github.com/Ricardo-Ray/claude-timeline
Project-URL: Issues, https://github.com/Ricardo-Ray/claude-timeline/issues
Project-URL: Changelog, https://github.com/Ricardo-Ray/claude-timeline/blob/main/CHANGELOG.md
Author: ClaudeTimeline contributors
License: MIT
Keywords: claude,claude-code,less,resume,session-history,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/claude-resume-dump.svg)](https://pypi.org/project/claude-resume-dump/)

## 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

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

Then install the shim:

```bash
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:

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

## Quickstart

```bash
# 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

| Command | Purpose |
|---|---|
| `install [--target-dir PATH]` | Install the `claude` shim. |
| `uninstall [--target-dir PATH]` | Remove the shim. |
| `dump <encoded-cwd> <resume-id> [--no-color]` | Render a session to stdout (used by the shim). |
| `list` | List recent sessions in the current project. |
| `show <session-id> [--cwd PATH] [--no-color]` | Render one session. |
| `grep <pattern> [--cwd PATH]` | Substring search across all sessions. |
| `export <session-id> --output PATH [--cwd PATH]` | Markdown export. |

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: `exec`s 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
   `exec`s 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

| OS | Shim flavor | Install dir (default) |
|---|---|---|
| Linux / macOS | POSIX bash | `~/.local/bin/claude` |
| Windows | cmd.exe batch | `%LOCALAPPDATA%\Programs\claude-timeline\claude.cmd` |

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

```bash
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](LICENSE).
