Metadata-Version: 2.4
Name: chat-timeline
Version: 0.1.1
Summary: Export Cursor / Claude Code / Codex chats and build a git-tracked, LLM-friendly project timeline.
Project-URL: Homepage, https://github.com/fredfts/chat-timeline
Project-URL: Issues, https://github.com/fredfts/chat-timeline/issues
Project-URL: Source, https://github.com/fredfts/chat-timeline
Author: Fred
License: MIT License
        
        Copyright (c) 2026 Fred
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,chat-export,claude-code,codex,cursor,developer-tools,timeline
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# chat-timeline

Export chat history from **Cursor**, **Claude Code**, and **Codex** and build a
git-tracked, LLM-friendly project timeline.

The result is three artifacts that live inside your repo:

- `timeline/timeline.md` — chronological, compact, ready for an LLM to read.
- `timeline/contents/timeline.json` — referenced content keyed by entry ID.
- `timeline/sessions/session.md` — full chat exports + git index context.

A built-in git pre-commit hook keeps the timeline in sync with your commits
automatically.

Works on Windows, macOS, and Linux. Pure stdlib — no runtime dependencies.

---

## Install + configure (one command)

```bash
pipx install chat-timeline && timeline init
```

`pipx` not available? The equivalent is:

```bash
python -m pip install --user chat-timeline && timeline init
```

`timeline init` is idempotent and does everything for you:

1. Resolves the project root (`git rev-parse --show-toplevel`).
2. Creates `timeline/` with `chats/`, `sessions/`, `contents/`, and the
   archive folder.
3. Writes `timeline/.gitignore` and a managed block in the project's
   `.gitignore`.
4. Installs `LLM_INSTRUCTIONS.md` for downstream prompts.
5. Installs the git pre-commit hook (calls `timeline -p` on each commit).

To reverse: `timeline deinit` removes the hook and the managed `.gitignore`
block. Your exported data is left untouched.

---

## Daily use

```bash
timeline                  # interactive selector → exports + session + timeline
timeline claude           # claude only
timeline cursor 1-5       # cursor chats #1..#5
timeline -t               # rebuild timeline only (incremental)
timeline -t -rt           # rebuild timeline from scratch
timeline -p               # pre-commit standalone (auto-detects modified chats)
```

Equivalent: `python -m chat_timeline …`.

Full flag reference: `timeline --help`.

### Interactive selector keys

| Key | Action |
|---|---|
| `↑ ↓` | move pointer |
| `PgUp PgDn` | page |
| `Home End` | jump to first/last |
| `Space` | toggle chat (or entry, when expanded) |
| `→` | expand chat to entries |
| `←` | collapse / jump back to parent |
| `a` | toggle select-all |
| `t` | cycle tracking mode (chat) or toggle exclude/force-add (entry). Hold 3s to clear tracking. |
| `p` | toggle pre-commit auto mode |
| `o` | toggle timeline archive rotation for this run |
| `h` | toggle "hot entries only" filter |
| `Tab` | switch list ↔ numeric input |
| `Enter` | confirm · `Esc` cancel |

---

## What it reads (per source)

| Source | Storage location | Notes |
|---|---|---|
| Cursor | `%APPDATA%/Cursor/User/workspaceStorage/` (Win), `~/Library/Application Support/Cursor/User/workspaceStorage/` (mac), `~/.config/Cursor/User/workspaceStorage/` (linux) | SQLite |
| Claude Code | `~/.claude/projects/<slug>/*.jsonl` | Cross-runtime: Windows reads WSL data, WSL reads Windows data |
| Codex | `~/.codex/sessions/**/*.jsonl` | Same cross-runtime discovery |

Nothing is transmitted anywhere. Everything runs locally on your machine.

---

## Configuration

| Env var | Effect |
|---|---|
| `TIMELINE_PROJECT_ROOT` | Override the auto-detected git toplevel. |
| `TIMELINE_HOME` | Override the default `<project>/timeline` location. |
| `TIMELINE_AMEND` | Set by the pre-commit hook on `git commit --amend`. |

---

## Pre-commit hook details

The hook is a POSIX shell script that:

1. Detects `git commit --amend` from the parent process's `cmdline`.
2. Calls the installed `timeline` entry point, with fallbacks to
   `python -m chat_timeline` and `wsl.exe timeline`.
3. Stages any updated timeline files into the commit.

On Windows it runs under Git Bash (which ships with Git for Windows).

---

## Status

v0.1.0 ships a working CLI based on a vendored monolithic implementation
(`chat_timeline._legacy`). v0.2.0 will split it into clean modules
(`sources/`, `tui/`, `session.py`, `timeline.py`) without breaking the CLI or
the on-disk format.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports welcome — please include
the output of `timeline --version` and your OS + Python version.

## License

MIT. See [LICENSE](LICENSE).
