sift-cc 0.2.1__tar.gz

sift_cc-0.2.1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

sift_cc-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Ruff check
+        run: ruff check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        run: python -m unittest discover -s tests -v

sift_cc-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sift_cc-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv*/
+venv/
+.env
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+sift-exports/
+.claude/settings.local.json

sift_cc-0.2.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] — 2026-05-30
+
+### Packaging
+- Added GitHub Actions CI workflow: ruff lint plus unittest suite across Python 3.10–3.13 on Ubuntu and macOS.
+- Added trusted-publishing release workflow that builds the wheel/sdist and publishes to PyPI on `v*` tags.
+- Added minimal `[tool.ruff]` config (pyflakes + syntax errors only).
+- Added Dependabot config to keep GitHub Actions versions current.
+
+## [0.2.0] — 2026-05-30
+
+### Added
+- **Interactive TUI** — `sift` with no arguments launches a curses-based terminal UI: scrollable session list on the left, live preview pane on the right with stats, first prompt, and per-session tool/file activity bars. Live filter (`/`), full-archive content search (`s`), in-place actions for show / export / resume / copy-id / copy-path, help overlay (`?`), with a non-interactive `--help` fallback when not attached to a TTY. Uses `pbcopy` / `wl-copy` / `xclip` for clipboard, gracefully degrades when none are available.
+- `sift last` — render the most recent session.
+- `sift resume <id>` — print (or `--exec`) the `claude --resume` command for a session, in its original cwd.
+- `sift files <id>` — list files touched by Read / Edit / Write / NotebookEdit / MultiEdit, with per-op breakdown.
+- `sift tools <id>` — horizontal bar chart of tool usage in a session.
+- `sift bash <id>` — extract every shell command run, with timestamps.
+- `sift links <id>` — extract URLs, ranked by mention count and colored by source role.
+- `sift export <id>` — clean markdown export with frontmatter, headings per turn, optional `<details>` thinking blocks, and tool-call summaries.
+- `sift related <id>` — find similar sessions across the archive using TF-IDF cosine similarity.
+- `sift pick` — interactive session picker using `fzf` when available, with numbered-menu fallback. Chained `--action show|path|resume|files|tools|id`.
+- `sift prompts` — list first user prompts across recent sessions for quick "what was I working on?" recall.
+- `sift completion bash|zsh|fish` — generate shell completion scripts with session-ID completion for relevant subcommands.
+- `--version` flag.
+- `--since` / `--until` accept relative spans (`7d`, `2w`, `12h`) or ISO dates on `list`, `search`, `stats`.
+- `list --sort recent|tokens|messages|duration|input|output`.
+- `search -l/--files-only` to print only matching session IDs.
+- `stats` now includes per-session averages, standout sessions, an hour-of-day histogram, and an optional `--year` 52-week heatmap.
+- `stats --json` for piping into other tools.
+- `projects --json`.
+
+### Changed
+- Numbers ≥ 1 G now formatted with a "G" suffix.
+- Code-block extraction supports more language extensions (swift, kotlin, java, c/cpp, ruby, php, toml, scss, dockerfile, diff/patch, …).
+
+### Packaging
+- Renamed `sift` → `sift.py` to enable `pip install`.
+- Added `pyproject.toml` (hatchling) with `sift` console-script entry point.
+- Added MIT `LICENSE`.
+
+## [0.1.0] — 2026-05-30
+
+Initial release.
+
+- `projects`, `list`, `search`, `show`, `code`, `stats`, `path`, `open`.
+- Plain Python, stdlib only.

sift_cc-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Mavec
+
+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.

sift_cc-0.2.1/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: sift-cc
+Version: 0.2.1
+Summary: Mine your Claude Code conversation archive — search, browse, and extract from past sessions.
+Project-URL: Homepage, https://github.com/SimonMav/sift-cc
+Project-URL: Repository, https://github.com/SimonMav/sift-cc
+Project-URL: Issues, https://github.com/SimonMav/sift-cc/issues
+Author: Simon Mavec
+License-Expression: MIT
+License-File: LICENSE
+Keywords: archive,claude,claude-code,cli,conversations,search
+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 :: Only
+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
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# sift
+
+> Mine your Claude Code conversation archive.
+
+Every Claude Code session you've ever had is sitting in `~/.claude/projects/` as a JSONL file. After a few weeks that archive becomes a goldmine: code you've already worked through, decisions you've already made, explanations you've already gotten — but there's no way to actually use it.
+
+`sift` makes that archive usable. Open the interactive TUI, search across every conversation, browse sessions by project and time, extract code blocks, find related discussions, render whole sessions to markdown, and jump back into any one of them.
+
+**Single Python file. Zero runtime dependencies. Pure stdlib.**
+
+```text
+$ sift                                # interactive TUI (default when no args)
+
+  ▰ sift v0.2.1  ·  145/145 sessions                              ?  help    q  quit
+  press / to filter titles & paths   ·   s to search conversation contents
+  ─────────────────────────────────────────────────────────────────────────────────
+  ▸ a1b2c3d  webapp            173   just now  Refactor auth middl…  │  Refactor auth middleware
+    e4f5a6b  notes              29    34m ago  Add markdown table…  │  a1b2c3d4-1111-2222-3333-444455556666
+    c7d8e9f  cli-tool           58     1h ago  Investigate slow s…  │
+    1a2b3c4  infra              35     1h ago  Debug terraform pl…  │  project  ~/projects/webapp
+    5d6e7f8  api-srv            48     3h ago  Fix request timeou…  │  branch   main
+    9a0b1c2  scratch            60    14h ago  Sketch graph layou…  │  started  2026-01-15 10:31
+                                                                    │  duration 1h22m
+                                                                    │  models   claude-opus-4-7
+                                                                    │  messages 80 user, 143 assistant
+                                                                    │  tokens   in 217   out 395.2k
+                                                                    │
+                                                                    │  top tools
+                                                                    │    Bash        █████████████ 50
+                                                                    │    Write       ████ 10
+                                                                    │    Edit        ██ 7
+                                                                    │
+  ↑↓ nav   /  filter   s  search   ⏎  show   e  export   r  resume   c  copy id   ?  help   q  quit
+```
+
+…or use the underlying subcommands directly for scripting:
+
+```text
+$ sift list --days 7
+id       project              msgs       last  title
+────────────────────────────────────────────────────────────────────────────
+a1b2c3d4 webapp                127   just now  Refactor auth middleware
+e4f5a6b7 notes                  29    34m ago  Add markdown table support
+c7d8e9f0 cli-tool               58     1h ago  Investigate slow startup
+1a2b3c4d infra                  48     3h ago  Fix terraform drift
+5d6e7f89 api-srv                60    14h ago  Add request tracing
+```
+
+---
+
+## Install
+
+### pip (recommended)
+
+Until `sift` is published to PyPI, install from source:
+
+```sh
+git clone https://github.com/SimonMav/sift-cc && cd sift
+pip install .
+```
+
+This puts `sift` on your `$PATH`.
+
+### Single file, no pip
+
+```sh
+chmod +x sift.py
+ln -s "$PWD/sift.py" /opt/homebrew/bin/sift   # or anywhere on $PATH
+```
+
+Requires **Python 3.10+** (uses `X | None` type syntax).
+
+### Shell completion
+
+```sh
+sift completion bash >> ~/.bashrc
+sift completion zsh  > "${fpath[1]}/_sift"
+sift completion fish > ~/.config/fish/completions/sift.fish
+```
+
+---
+
+## The TUI
+
+Running `sift` with no arguments launches an interactive terminal UI. It opens a split view: scrollable session list on the left, live preview on the right with stats, the first prompt, and tool/file activity bars for the highlighted session.
+
+Keybindings:
+
+| Key | Action |
+| --- | --- |
+| `↑` `↓`  /  `k` `j` | Move cursor |
+| `g` / `G` | Top / bottom |
+| `PgUp` `PgDn`  /  `u` `d` | Page |
+| `/` | Filter list (live — matches title, project, first prompt) |
+| `s` | Search conversation **contents** across every session |
+| `esc` | Clear the current filter or search |
+| `⏎` | Render the selected session through your `$PAGER` |
+| `e` | Export the session to `~/sift-exports/<id>-<slug>.md` |
+| `r` | Copy `cd … && claude --resume …` to the clipboard |
+| `c` | Copy session id |
+| `p` | Copy session JSONL path |
+| `R` | Reload sessions from disk |
+| `?` | Help overlay |
+| `q` | Quit |
+
+Clipboard uses `pbcopy` on macOS, `wl-copy` or `xclip` on Linux. With no clipboard tool, the value is flashed in the footer instead.
+
+If `sift` is invoked with no args in a non-interactive context (pipe, script), it prints `--help` instead of trying to start the TUI.
+
+## Commands
+
+### Browsing
+
+| Command | What it does |
+| --- | --- |
+| `sift projects` | One-line summary per project — sessions, tokens, last activity. |
+| `sift list` | Sessions across the archive, newest first. |
+| `sift last` | Render the most recent session. |
+| `sift pick` | Interactive picker (uses `fzf` if installed). |
+| `sift prompts` | First user prompts across recent sessions — quick "what was I working on?". |
+
+### Single-session inspection
+
+| Command | What it does |
+| --- | --- |
+| `sift show <id>` | Render a session readably (paged, colored, wrapped). |
+| `sift files <id>` | Files touched (Read/Edit/Write), with per-op breakdown. |
+| `sift tools <id>` | Tool-usage bar chart for the session. |
+| `sift bash <id>` | Every shell command run, with timestamps. |
+| `sift links <id>` | URLs mentioned, ranked by count, colored by source. |
+| `sift code <id>` | Fenced code blocks. With `--out-dir`, writes each block to a file. |
+| `sift export <id>` | Clean markdown export, optional `<details>` thinking blocks. |
+| `sift path <id>` | Absolute path of the JSONL file. |
+| `sift open <id>` | Open the JSONL in `$EDITOR`. |
+
+### Search and discovery
+
+| Command | What it does |
+| --- | --- |
+| `sift search "q"` | Full-text search across every session. Regex, role filter, highlighting, context lines. |
+| `sift related <id>` | Find similar sessions using TF-IDF cosine similarity. |
+
+### Analytics
+
+| Command | What it does |
+| --- | --- |
+| `sift stats` | Token totals, model split, top projects, hour-of-day, 30-day strip. |
+| `sift stats --year` | 52-week GitHub-style activity heatmap. |
+| `sift stats --json` | Machine-readable summary for piping. |
+
+### Workflow
+
+| Command | What it does |
+| --- | --- |
+| `sift resume <id>` | Print `claude --resume` in the session's original cwd. `--exec` runs it. |
+| `sift completion {bash,zsh,fish}` | Generate a shell completion script. |
+
+---
+
+## Examples
+
+### Find that explanation from last month
+
+```sh
+sift search "MVCC isolation" --user
+sift search "rate limit" --assistant -C 2
+sift search "fn .*\(unsafe" --regex
+```
+
+### Pick up where you left off
+
+```sh
+sift last                          # render the most recent session
+sift resume $(sift list --json --limit 1 | jq -r '.[0].session_id') --exec
+```
+
+### Cross-reference sessions
+
+```sh
+sift related 003f1707              # find similar past work
+sift related 003f1707 -p webapp    # restrict to one project
+```
+
+### Export a session for sharing
+
+```sh
+sift export 003f1707 -o write-up.md
+sift export 003f1707 --thinking --tool-results -o full.md
+```
+
+### "What have I been working on?"
+
+```sh
+sift prompts --days 14
+sift stats --year
+```
+
+### Pipe into your own tools
+
+```sh
+sift list --since 30d --json | jq '.[].title'
+sift search "TODO" --files-only | xargs -I{} sift show {} --no-pager
+sift code 003f1707 --lang python --out-dir ./extracted/
+```
+
+### Interactive flow with fzf
+
+```sh
+sift pick                                 # default action: show
+sift pick --action resume                 # pick, then resume
+sift pick -p webapp --since 7d            # narrow the candidate set
+```
+
+---
+
+## Time filters
+
+Anywhere `--since` or `--until` appears (and `--days` as a shorthand):
+
+| Form | Meaning |
+| --- | --- |
+| `7d`, `2w`, `12h` | Relative offset from now. |
+| `2026-05-01` | ISO date (UTC). |
+| `2026-05-01T12:30:00` | ISO datetime. |
+
+```sh
+sift list --since 7d
+sift search "cache" --since 2026-05-01
+sift stats --since 30d --until 2026-05-25
+```
+
+---
+
+## Session IDs
+
+All commands that take a session accept either the full UUID or any **unique prefix**:
+
+```sh
+sift show 003f1707       # ✓ if it's unique
+sift show 003                  # ✗ ambiguous — sift will list candidates
+```
+
+`sift search` and `sift pick` are good ways to find an ID when you don't have one to hand.
+
+---
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SIFT_ARCHIVE` | `~/.claude/projects` | Where to look for session JSONLs. |
+| `NO_COLOR` / `SIFT_NO_COLOR` | unset | Disable ANSI colors. |
+| `EDITOR` | `vi` | Used by `sift open`. |
+| `PAGER` | `less -RFX` | Used by `sift show` and `sift last` when stdout is a TTY. |
+
+---
+
+## Development
+
+```sh
+git clone <repo> && cd sift
+python3 -m pytest tests/        # 41 tests, runs in ~0.1s
+python3 sift.py --version
+```
+
+The project is a single file (`sift.py`) plus tests. Tests build a synthetic archive in a temp directory and exercise every subcommand — no fixtures committed to the repo, no external state.
+
+---
+
+## How it works
+
+Claude Code writes one JSONL per session under `~/.claude/projects/<project>/<session-id>.jsonl`. Each line is a record: `user` and `assistant` messages, `ai-title` (Claude Code auto-titles sessions), `system`, `attachment`, etc.
+
+`sift` parses these records lazily, builds summaries on demand, and ships nothing to any server. Everything is local.
+
+The TF-IDF in `sift related` boosts the auto-title heavily (it's the highest-signal text in the corpus), reads ~30 KB of conversation per session, tokenizes on word characters minus a small English stopword set, and ranks by cosine similarity over IDF-weighted vectors. On a 145-session archive this takes under a second.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Why
+
+The conversations are right there. There just wasn't a good way to use them.