codestrain 0.1.0__tar.gz

codestrain-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install pytest
+        run: python -m pip install --upgrade pip pytest
+
+      - name: Run unit tests
+        run: python -m pytest tests/ -v
+
+      - name: Run smoke tests
+        run: tests/smoke.sh

codestrain-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        working-directory: .
+        run: python -m build
+
+      - name: Upload distributions
+        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 distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via Trusted Publisher
+        uses: pypa/gh-action-pypi-publish@release/v1

codestrain-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python build / packaging
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+
+# uv / venv
+.venv/
+.uv-cache/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+
+# Credentials — never commit
+.pypirc
+.pypi_api_key
+.env

codestrain-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to CodeStrain CLI
+
+Thanks for stopping by. CodeStrain CLI is small, stdlib-only, and built to stay that way.
+
+## Local setup
+
+```bash
+git clone https://github.com/codestrain/codestrain-cli.git
+cd codestrain-cli
+
+# Optional but recommended — keeps the test deps isolated.
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python -e . pytest ruff
+```
+
+## Run the tests before sending a PR
+
+```bash
+.venv/bin/python -m pytest tests/ -v        # 44 unit + integration tests
+tests/smoke.sh                              # 16 CLI surface checks
+```
+
+CI runs the same suite on macOS and Linux × Python 3.9 / 3.10 / 3.11 / 3.12 / 3.13. If your PR doesn't pass locally, it won't pass there.
+
+For the full test plan (manual UX checklist, fixture format, CI matrix), see [`TESTING.md`](TESTING.md).
+
+## What's in scope
+
+- bug fixes for the existing flag surface (`--all`, `--project`, `--detect`, `--anonymize`, `--no-breakdown`, `--no-color`, `--logo`, `--path`)
+- DRS-formula tuning backed by data
+- additional Claude Code JSONL schema fields we currently miss
+- terminal-compatibility patches (see open issues on Windows / Git Bash)
+- documentation, examples, install-script fixes
+
+## What's out of scope
+
+- new runtime dependencies — this project is stdlib-only and stays that way
+- emoji in code or docs (project tone is direct)
+- features that require the CodeStrain server / ML backend (those live in the closed-source side)
+
+## Sign your commits (DCO)
+
+We use the [Developer Certificate of Origin](https://developercertificate.org/) — no CLA, no paperwork. Just sign off each commit:
+
+```bash
+git commit -s -m "fix: handle empty alpha bbox without crashing"
+```
+
+The `-s` adds a `Signed-off-by:` line and certifies you wrote the change (or have permission to contribute it) under the project's license.
+
+## Licensing posture
+
+CodeStrain CLI is MIT-licensed today and will stay that way for v0.1.x. If at some point we introduce a commercial license for a future major version, we will (a) announce it at least 90 days in advance, (b) keep individuals and small organizations free, and (c) never apply new terms retroactively — every release tagged before the change keeps its MIT license forever.
+
+By signing off your commit you certify the DCO 1.1. The project maintainer reserves the right to release new versions of the project under additional licenses.
+
+## Reporting issues
+
+Open a [GitHub issue](https://github.com/codestrain/codestrain-cli/issues) with:
+
+- what you ran (`codestrain --all` etc.)
+- what you expected
+- what happened instead
+- `codestrain --version` + `python3 --version` + OS
+
+For privacy: never paste raw JSONL or session content — share the redacted output (`codestrain --all --anonymize --no-color`) instead.
+
+## Maintainer
+
+Built and maintained by Ivan Kononov / LLP HubLab — codestrain.dev.

codestrain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLP HubLab (codestrain.dev)
+
+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.

codestrain-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: codestrain
+Version: 0.1.0
+Summary: Your AI coding recovery score, from the terminal.
+Project-URL: Homepage, https://codestrain.dev
+Project-URL: Repository, https://github.com/codestrain/codestrain-cli
+Author: Ivan Kononov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: burnout,claude-code,developer-tools,drs,wellness
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/codestrain/codestrain-cli/main/.assets/logo.png" alt="CodeStrain" width="200"/></p>
+
+# CodeStrain CLI
+
+*Your AI coding recovery score, from the terminal.*
+
+<p align="center">
+  <a href="https://pypi.org/project/codestrain/"><img src="https://img.shields.io/pypi/v/codestrain.svg" alt="PyPI version"/></a>
+  <a href="https://pypi.org/project/codestrain/"><img src="https://img.shields.io/pypi/pyversions/codestrain.svg" alt="Python versions"/></a>
+  <a href="https://github.com/codestrain/codestrain-cli/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/codestrain.svg" alt="License: MIT"/></a>
+  <a href="https://github.com/codestrain/codestrain-cli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/codestrain/codestrain-cli/ci.yml?branch=main" alt="CI status"/></a>
+</p>
+
+## What is this
+
+CodeStrain parses the Claude Code JSONL session logs already on your disk (`~/.claude/projects/`) and prints cost, token usage, a Developer Recovery Score (DRS) estimate, and a per-project breakdown. Zero dependencies — Python stdlib only. Read-only — your JSONL never leaves the machine.
+
+## Install
+
+```bash
+# one-liner (recommended)
+curl -fsSL codestrain.dev/install | sh
+```
+
+```bash
+# pipx
+pipx install codestrain
+```
+
+```bash
+# uv
+uv tool install codestrain
+```
+
+## Quick start
+
+```bash
+# today's stats (default)
+codestrain
+```
+
+```bash
+# all-time, every session ever logged
+codestrain --all
+```
+
+```bash
+# all-time, with project names hashed
+codestrain --all --anonymize
+```
+
+## Example output
+
+```
+   ______          __     _____ __             
+  / ____/___  ____/ /__  / ___// /__________ _( )___
+ / /   / __ \/ __  / _ \ \__ \/ __/ ___/ __ `/ / __ \
+/ /___/ /_/ / /_/ /  __/___/ / /_/ /  / /_/ / / / / /
+\____/\____/\__._/\___//____/\__/_/   \__._/_/_/ /_/
+
+  Your AI coding recovery score.
+
+--- All Time ------------------------------------------
+
+  Sessions:  1454
+  Duration:  137h 21m  (span 15352h 27m)
+  Turns:     61007
+  Tokens:    2.0M in / 25.4M out
+  Cost:      $21948.61
+  Models:    claude-haiku-4-5, claude-opus-4-5, claude-opus-4-7 +5 more
+
+  DRS Estimate  (avg per active day · 52 days · 2.6h/day)
+  Strain:    9.0/21
+  Recovery:  82%
+  Readiness: GREEN — Recovered. Good to go.
+
+--- Per-Project Breakdown -----------------------------
+
+  project-1   31h  2m  13638 turns  $7193.92
+  project-2   21h 40m   8684 turns  $3652.80
+  project-3   15h 32m   4789 turns  $1212.63
+  ...
+```
+
+## Flags reference
+
+| Flag | Purpose |
+|------|---------|
+| `--all` | Aggregate every session ever logged instead of just today. |
+| `--project NAME` | Only include sessions whose project basename matches `NAME`. |
+| `--path DIR` | Read JSONL from `DIR` instead of `~/.claude/projects/`. |
+| `--detect` | Scan common locations and print where Claude Code data lives. |
+| `--anonymize` | Hash project names before printing the breakdown. |
+| `--no-breakdown` | Suppress the per-project breakdown table. |
+| `--no-color` | Disable ANSI colors (also honors `NO_COLOR`). |
+| `--logo {auto,big,small,none}` | Control the ASCII logo: `big` always, `small` one-liner, `none` off, `auto` picks based on terminal width. |
+
+## DRS — what it actually measures
+
+**Strain (0-21, per active day).** The CLI sums the gaps between consecutive turns that are ≤ 5 minutes — that's the "active coding" duration. Each hour contributes `2.1` strain points, capped at 21. The 5-minute threshold matches the ccusage / Claude Code Usage Monitor convention and is configurable via `CODESTRAIN_GAP_MIN`. Debug-heavy sessions (high error ratio), late-night work (after 22:00), and weekend coding add small penalties.
+
+**Recovery (0-100%).** Recovery moves inversely to strain and is modulated by hours since the last session (sleep proxy). Eight hours off lifts the baseline; high recent strain pulls it down. The local heuristic doesn't have biometric input — it's purely behavioral.
+
+**Readiness.** A traffic-light derived from recovery: **GREEN** at ≥ 67%, **YELLOW** between 34% and 66%, **RED** below 34%. The thresholds match the macOS app and the WHOOP-inspired DRS spec.
+
+This is a heuristic estimate from JSONL logs, not medical advice. The full CodeStrain app refines DRS with ML models, wearable data (HealthKit / WHOOP / Oura), and per-user calibration.
+
+## Why this is privacy-first
+
+- All parsing runs locally. No data ever leaves your machine.
+- No telemetry, no opt-in pings, no usage analytics — not even crash reports.
+- Your JSONL files are read-only. They are never uploaded, copied, or modified.
+- Respects `NO_COLOR` and `FORCE_COLOR` / `CLICOLOR_FORCE` conventions for piping and CI.
+
+## Related projects
+
+- [ccusage](https://github.com/ryoppippi/ccusage) — the npm reference for parsing Claude Code JSONL. Friend, not foe. We follow its session model so numbers line up.
+- [Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) — Python alternative with ML burn-rate prediction and a live dashboard.
+
+## Roadmap (v0.1)
+
+- CreatureView — a tiny macOS menu-bar companion that surfaces DRS without opening a terminal (private beta).
+- Souls Studio — paid persona pack and custom-character marketplace (Drill Sergeant, Gentle Princess, Sarcastic AI...).
+- Magenta-key sprite pipeline v1.2 — clean alpha extraction for community-created creatures.
+- Wearable integration — Apple HealthKit, WHOOP, Oura → unified `HealthSnapshot`.
+
+More at [codestrain.dev](https://codestrain.dev).
+
+## Contributing
+
+PRs welcome. Sign your commits with `git commit -s` (DCO) and run the suite before opening one:
+
+```bash
+python -m pytest tests/
+tests/smoke.sh
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contribution workflow and [`TESTING.md`](TESTING.md) for the full test matrix.
+
+## License
+
+CodeStrain CLI is MIT-licensed and free for everyone — individuals, teams, companies, and forks — forever for this and every prior release. The CodeStrain hosted service (DRS predictions, ML models, encrypted sync) is a separate paid product; the CLI works fully offline without it.
+
+If we ever introduce a commercial license for a future major version, we will give at least 90 days' notice, keep individuals and small organizations free, and never apply new terms retroactively. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the maintainer's relicensing posture and the DCO sign-off contributors use.
+
+Copyright (c) 2026 LLP HubLab (codestrain.dev).
+
+---
+
+Star this repo if codestrain told you something you didn't know about your last week of AI coding. → [codestrain.dev](https://codestrain.dev)

codestrain-0.1.0/README.md

@@ -0,0 +1,150 @@
+<p align="center"><img src="https://raw.githubusercontent.com/codestrain/codestrain-cli/main/.assets/logo.png" alt="CodeStrain" width="200"/></p>
+
+# CodeStrain CLI
+
+*Your AI coding recovery score, from the terminal.*
+
+<p align="center">
+  <a href="https://pypi.org/project/codestrain/"><img src="https://img.shields.io/pypi/v/codestrain.svg" alt="PyPI version"/></a>
+  <a href="https://pypi.org/project/codestrain/"><img src="https://img.shields.io/pypi/pyversions/codestrain.svg" alt="Python versions"/></a>
+  <a href="https://github.com/codestrain/codestrain-cli/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/codestrain.svg" alt="License: MIT"/></a>
+  <a href="https://github.com/codestrain/codestrain-cli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/codestrain/codestrain-cli/ci.yml?branch=main" alt="CI status"/></a>
+</p>
+
+## What is this
+
+CodeStrain parses the Claude Code JSONL session logs already on your disk (`~/.claude/projects/`) and prints cost, token usage, a Developer Recovery Score (DRS) estimate, and a per-project breakdown. Zero dependencies — Python stdlib only. Read-only — your JSONL never leaves the machine.
+
+## Install
+
+```bash
+# one-liner (recommended)
+curl -fsSL codestrain.dev/install | sh
+```
+
+```bash
+# pipx
+pipx install codestrain
+```
+
+```bash
+# uv
+uv tool install codestrain
+```
+
+## Quick start
+
+```bash
+# today's stats (default)
+codestrain
+```
+
+```bash
+# all-time, every session ever logged
+codestrain --all
+```
+
+```bash
+# all-time, with project names hashed
+codestrain --all --anonymize
+```
+
+## Example output
+
+```
+   ______          __     _____ __             
+  / ____/___  ____/ /__  / ___// /__________ _( )___
+ / /   / __ \/ __  / _ \ \__ \/ __/ ___/ __ `/ / __ \
+/ /___/ /_/ / /_/ /  __/___/ / /_/ /  / /_/ / / / / /
+\____/\____/\__._/\___//____/\__/_/   \__._/_/_/ /_/
+
+  Your AI coding recovery score.
+
+--- All Time ------------------------------------------
+
+  Sessions:  1454
+  Duration:  137h 21m  (span 15352h 27m)
+  Turns:     61007
+  Tokens:    2.0M in / 25.4M out
+  Cost:      $21948.61
+  Models:    claude-haiku-4-5, claude-opus-4-5, claude-opus-4-7 +5 more
+
+  DRS Estimate  (avg per active day · 52 days · 2.6h/day)
+  Strain:    9.0/21
+  Recovery:  82%
+  Readiness: GREEN — Recovered. Good to go.
+
+--- Per-Project Breakdown -----------------------------
+
+  project-1   31h  2m  13638 turns  $7193.92
+  project-2   21h 40m   8684 turns  $3652.80
+  project-3   15h 32m   4789 turns  $1212.63
+  ...
+```
+
+## Flags reference
+
+| Flag | Purpose |
+|------|---------|
+| `--all` | Aggregate every session ever logged instead of just today. |
+| `--project NAME` | Only include sessions whose project basename matches `NAME`. |
+| `--path DIR` | Read JSONL from `DIR` instead of `~/.claude/projects/`. |
+| `--detect` | Scan common locations and print where Claude Code data lives. |
+| `--anonymize` | Hash project names before printing the breakdown. |
+| `--no-breakdown` | Suppress the per-project breakdown table. |
+| `--no-color` | Disable ANSI colors (also honors `NO_COLOR`). |
+| `--logo {auto,big,small,none}` | Control the ASCII logo: `big` always, `small` one-liner, `none` off, `auto` picks based on terminal width. |
+
+## DRS — what it actually measures
+
+**Strain (0-21, per active day).** The CLI sums the gaps between consecutive turns that are ≤ 5 minutes — that's the "active coding" duration. Each hour contributes `2.1` strain points, capped at 21. The 5-minute threshold matches the ccusage / Claude Code Usage Monitor convention and is configurable via `CODESTRAIN_GAP_MIN`. Debug-heavy sessions (high error ratio), late-night work (after 22:00), and weekend coding add small penalties.
+
+**Recovery (0-100%).** Recovery moves inversely to strain and is modulated by hours since the last session (sleep proxy). Eight hours off lifts the baseline; high recent strain pulls it down. The local heuristic doesn't have biometric input — it's purely behavioral.
+
+**Readiness.** A traffic-light derived from recovery: **GREEN** at ≥ 67%, **YELLOW** between 34% and 66%, **RED** below 34%. The thresholds match the macOS app and the WHOOP-inspired DRS spec.
+
+This is a heuristic estimate from JSONL logs, not medical advice. The full CodeStrain app refines DRS with ML models, wearable data (HealthKit / WHOOP / Oura), and per-user calibration.
+
+## Why this is privacy-first
+
+- All parsing runs locally. No data ever leaves your machine.
+- No telemetry, no opt-in pings, no usage analytics — not even crash reports.
+- Your JSONL files are read-only. They are never uploaded, copied, or modified.
+- Respects `NO_COLOR` and `FORCE_COLOR` / `CLICOLOR_FORCE` conventions for piping and CI.
+
+## Related projects
+
+- [ccusage](https://github.com/ryoppippi/ccusage) — the npm reference for parsing Claude Code JSONL. Friend, not foe. We follow its session model so numbers line up.
+- [Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) — Python alternative with ML burn-rate prediction and a live dashboard.
+
+## Roadmap (v0.1)
+
+- CreatureView — a tiny macOS menu-bar companion that surfaces DRS without opening a terminal (private beta).
+- Souls Studio — paid persona pack and custom-character marketplace (Drill Sergeant, Gentle Princess, Sarcastic AI...).
+- Magenta-key sprite pipeline v1.2 — clean alpha extraction for community-created creatures.
+- Wearable integration — Apple HealthKit, WHOOP, Oura → unified `HealthSnapshot`.
+
+More at [codestrain.dev](https://codestrain.dev).
+
+## Contributing
+
+PRs welcome. Sign your commits with `git commit -s` (DCO) and run the suite before opening one:
+
+```bash
+python -m pytest tests/
+tests/smoke.sh
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contribution workflow and [`TESTING.md`](TESTING.md) for the full test matrix.
+
+## License
+
+CodeStrain CLI is MIT-licensed and free for everyone — individuals, teams, companies, and forks — forever for this and every prior release. The CodeStrain hosted service (DRS predictions, ML models, encrypted sync) is a separate paid product; the CLI works fully offline without it.
+
+If we ever introduce a commercial license for a future major version, we will give at least 90 days' notice, keep individuals and small organizations free, and never apply new terms retroactively. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the maintainer's relicensing posture and the DCO sign-off contributors use.
+
+Copyright (c) 2026 LLP HubLab (codestrain.dev).
+
+---
+
+Star this repo if codestrain told you something you didn't know about your last week of AI coding. → [codestrain.dev](https://codestrain.dev)

codestrain-0.1.0/TESTING.md

@@ -0,0 +1,150 @@
+# CodeStrain CLI — test plan
+
+`codestrain_cli.py` ships zero-deps (stdlib only) and parses Claude Code JSONL. Before public release we want **automated unit tests** for pure logic + **scripted smoke tests** for the CLI surface + **a manual UX checklist** for visual output.
+
+Tests live in `cli/tests/`. Run them from the repo root:
+
+```bash
+cd cli && python -m pytest tests/         # unit + integration
+cd cli && ./tests/smoke.sh                # CLI surface
+```
+
+---
+
+## 1. Unit tests (`cli/tests/test_unit.py`)
+
+Pure functions, no I/O, no JSONL parsing. Fast (< 1 s total).
+
+| Function | Cases |
+|---|---|
+| `Colors.enabled()` | tty + isatty=True → True · NO_COLOR set → False · TERM=dumb → False · pipe/non-tty → False |
+| `c(color, text)` | colors on → wrapped · colors off → bare text |
+| `drs_color(r)` | r=80 → GREEN · r=50 → YELLOW · r=20 → RED · boundaries at 34 & 67 |
+| `readiness_label(r)` | each tier returns the correct label |
+| `estimate_strain(hrs, debug, late, weekend)` | base 4 h → ~? · +late-night penalty (2×) · +weekend penalty (1.5×) · debug-ratio amplifies · clamped 0-21 |
+| `estimate_recovery(strain, since_last)` | strain 0 → 100% · high strain → low recovery · short sleep penalty |
+| `format_duration(sec)` | < 60 → `Ns` · < 3600 → `Xm Ys` · ≥ 3600 → `Xh Ym` |
+| `format_cost(c)` | `$0.00` for 0 · `$0.12` for 0.123 · `$12.34` for 12.34 |
+| `format_tokens(n)` | `1000` → `1.0K` · `1_500_000` → `1.5M` · 0 → `0` |
+
+## 2. Integration tests (`cli/tests/test_jsonl.py`)
+
+Drive `find_jsonl_files`, `parse_jsonl`, `extract_session_stats` with **synthetic fixture JSONL** under `cli/tests/fixtures/`. No dependency on the user's `~/.claude/projects/` (so tests are deterministic on any machine).
+
+Fixtures:
+
+```
+cli/tests/fixtures/
+├── projects/
+│   ├── -Users-test-projectA/
+│   │   ├── session-001.jsonl    # 3 turns, 5 min, has tokens
+│   │   └── session-002.jsonl    # malformed line in the middle (parser must skip)
+│   ├── -Users-test-projectB/
+│   │   └── session-003.jsonl    # 8 turns, 1 h, debug-heavy
+│   └── empty-project/
+│       └── empty.jsonl          # 0 lines
+└── single_event.jsonl           # one-line valid event for sanity
+```
+
+Test cases:
+- `find_jsonl_files(fixtures/projects/)` → discovers all 4 .jsonl files
+- `find_jsonl_files(..., project_filter="A")` → returns only projectA's files
+- `parse_jsonl(session-002.jsonl)` → skips bad line, returns the rest
+- `parse_jsonl(empty.jsonl)` → returns `[]` (no exception)
+- `extract_session_stats(parsed)` → turn count + token sums + cost match precomputed expected values
+- `extract_session_stats([])` → zero stats, no division-by-zero crash
+
+## 3. CLI surface tests (`cli/tests/smoke.sh`)
+
+Bash script that exercises every flag, asserts exit code 0, and greps stdout for expected strings. No pytest needed — just `bash`.
+
+```bash
+#!/usr/bin/env bash
+# Each command must exit 0 and produce expected key strings.
+
+cli=cli/codestrain_cli.py
+fixtures=cli/tests/fixtures
+
+assert_contains() { grep -qF "$2" <<<"$1" || { echo "FAIL: $3"; exit 1; }; }
+
+# 1. --help exits 0, mentions every flag.
+out=$(python3 $cli --help)
+assert_contains "$out" "--all"     "--help missing --all"
+assert_contains "$out" "--project" "--help missing --project"
+assert_contains "$out" "--path"    "--help missing --path"
+assert_contains "$out" "--no-color""--help missing --no-color"
+
+# 2. Default run against fixture dir — should print today's section.
+out=$(python3 $cli --path $fixtures/projects --no-color)
+assert_contains "$out" "CodeStrain" "header missing"
+assert_contains "$out" "Today"      "today section missing"
+
+# 3. --all aggregates everything (turn count must reflect projectA + projectB).
+out=$(python3 $cli --path $fixtures/projects --all --no-color)
+assert_contains "$out" "All-Time"   "--all label missing"
+
+# 4. --project filter.
+out=$(python3 $cli --path $fixtures/projects --project A --no-color --all)
+assert_contains "$out" "projectA"   "--project filter dropped projectA"
+# projectB must NOT show up
+grep -qF "projectB" <<<"$out" && { echo "FAIL: project filter leaked"; exit 1; }
+
+# 5. NO_COLOR env should strip ANSI sequences.
+out=$(NO_COLOR=1 python3 $cli --path $fixtures/projects)
+grep -qE $'\033\[' <<<"$out" && { echo "FAIL: NO_COLOR ignored"; exit 1; }
+
+# 6. Custom non-existent path → graceful exit (currently warns + exits non-zero,
+#    or exits 0 with empty sections — pin the expected behavior here).
+python3 $cli --path /tmp/does-not-exist --no-color >/dev/null
+# accept any exit code 0 or 1; if it crashes with traceback, fail.
+[ $? -le 1 ] || { echo "FAIL: missing path crashed"; exit 1; }
+
+echo "smoke.sh OK"
+```
+
+## 4. Manual UX checklist
+
+Run these from a terminal **with** colors and **without** (`NO_COLOR=1`). What you check:
+
+| # | Step | Pass criteria |
+|---|------|---------------|
+| 1 | `codestrain` (no flags) | ASCII logo prints. "Today" section shows correct sessions/duration/turns. DRS line colored green/yellow/red matching recovery. |
+| 2 | `codestrain --all` | "All-Time" label visible. Numbers > today's by a reasonable factor. |
+| 3 | `codestrain --project codestrain` | Output limited to that project's sessions only. No spillover. |
+| 4 | `codestrain --no-color` | Zero ANSI escapes (verify with `\| cat`). Layout still readable. |
+| 5 | `codestrain \| cat` | Same as #4 — auto-detected non-tty. |
+| 6 | `codestrain --help` | All 4 flags shown. Examples block shown. Exit code 0. |
+| 7 | `codestrain --path /tmp/empty-dir` (`mkdir /tmp/empty-dir`) | "0 sessions" gracefully. No crash. |
+| 8 | Terminal width ≤ 80 cols | Header doesn't wrap weirdly. Divider lines aligned. |
+| 9 | Dark terminal (Solarized Dark) | Yellow + Red still readable on dark BG. |
+| 10 | Light terminal (default macOS Terminal.app) | Same — pick AMBER over pure yellow if needed. |
+| 11 | `time codestrain --all` on 1000+ sessions | Completes in < 2 s on M1. CPU < 200%. |
+| 12 | `codestrain` with cycled JSONL (live Claude Code session running) | No file-lock errors; latest turn shows up after re-run. |
+| 13 | `codestrain --help \| less` | Pager-safe; no broken escapes. |
+
+## 5. Regression assets to bundle in the public repo
+
+For the public `codestrain-cli` repo, include `tests/fixtures/` so contributors can run the suite without needing their own `~/.claude/projects/`. Keep fixtures **small + synthetic** (no real prompts, no PII). Goal: < 50 KB total.
+
+## 6. CI matrix
+
+When the public repo is up, run on every PR:
+
+| Job | Python | OS | What |
+|---|---|---|---|
+| `lint` | 3.12 | ubuntu-latest | `ruff check`, `ruff format --check` |
+| `unit` | 3.9 / 3.10 / 3.11 / 3.12 / 3.13 | ubuntu-latest | `pytest cli/tests/` |
+| `smoke` | 3.11 | macos-latest + ubuntu-latest | `cli/tests/smoke.sh` |
+
+GitHub Actions matrix block lives in `.github/workflows/cli.yml`.
+
+---
+
+## TL;DR — what to run before opening the public-repo PR
+
+```bash
+# from repo root
+python -m pytest cli/tests/ -v && cli/tests/smoke.sh
+```
+
+If both green and the manual checklist passed on M-series macOS + an Intel Mac (or Linux VM), ship it.