gitview 0.1.3__tar.gz → 0.7.1__tar.gz

gitview-0.7.1/PKG-INFO

@@ -0,0 +1,1355 @@
+Metadata-Version: 2.4
+Name: gitview
+Version: 0.7.1
+Summary: Git history analyzer with LLM-powered narrative generation
+Home-page: https://github.com/carstenbund/gitview
+Author: GitView Contributors
+Author-email: 
+Maintainer: GitView Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/carstenbund/gitview
+Project-URL: Documentation, https://github.com/carstenbund/gitview/blob/main/README.md
+Project-URL: Repository, https://github.com/carstenbund/gitview
+Project-URL: Issues, https://github.com/carstenbund/gitview/issues
+Keywords: git,history,analyzer,llm,narrative,ai,claude,openai,ollama
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: click>=8.1.7
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pydantic>=2.5.0
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# GitView
+
+[![Github-CI][github-ci]][github-link]
+[![Coverage Status][codecov-badge]][codecov-link]
+[![PyPI][pypi-badge]][pypi-link]
+[![PyPI - Downloads][install-badge]][install-link]
+
+
+**Git history analyzer with LLM-powered narrative generation**
+
+GitView extracts your repository's git history and uses AI to generate compelling narratives about how your codebase evolved. Instead of manually reading through thousands of commits, get a comprehensive story of your project's journey.
+
+Example run on this repository: 
+
+[[(https://github.com/carstenbund/gitview/blob/main/output/history_story.md)] 
+](https://github.com/carstenbund/gitview/blob/main/output/history_story.md)
+
+## Features
+
+- **Comprehensive History Extraction**: Extracts commit metadata, LOC changes, language breakdown, README evolution, comment analysis, and more
+- **GitHub PR/Review Enrichment**: Optionally enrich commits with Pull Request context, review comments, and collaboration data via GitHub's GraphQL API
+- **Smart Chunking**: Automatically divides history into meaningful "phases" or "epochs" based on significant changes
+- **LLM-Powered Summaries**: Uses Claude to generate narrative summaries for each phase
+- **Global Story Generation**: Combines phase summaries into executive summaries, timelines, technical retrospectives, and deletion stories
+- **Storyline Tracking**: Track narrative threads (features, refactoring efforts, bug campaigns) across phases with automatic detection and lifecycle management
+- **Agent Brief**: Compile a compact, no-LLM project history digest (`gitview brief`) meant to be committed and read once per session — a token-efficient substitute for an AI coding agent re-deriving project history from scratch
+- **Repository Graph**: Build a persistent, incremental SQLite graph of commits, files, authors, PRs and file co-change coupling (`gitview graph`) — deterministic structure that later stages interpret instead of rediscovering
+- **Structural Evidence & Motifs**: Optionally store what an external code analyser (Graphify first) sees at a commit, then detect recurring motifs — hidden coupling, emerging dependencies, centrality growth — by combining history with structure (`gitview observe`, `gitview motifs`). Fully usable with no analyser installed
+- **Evidence-First Analysis**: The graph and motifs are built before any model call, so routine phases are written from repository evidence, two report sections need no model at all, and every prompt that is sent carries established facts (`--llm-budget`)
+- **Four LLM Backends**: Anthropic, OpenAI, Ollama, and a logged-in local Claude Code CLI (`--backend claude-cli`, billed to the Claude plan, no API key)
+- **Multiple Output Formats**: Generates markdown reports, JSON data, and timelines
+- **Critical Examination Mode**: Objective assessment focused on gaps, technical debt, and alignment with project goals (perfect for project leads)
+
+## Commands
+
+| Command | What it does | LLM |
+|---|---|---|
+| `analyze` | Full pipeline: extract, chunk, summarize, narrate, write the report | yes |
+| `brief` | Compact project history digest for an AI agent to read once per session | no |
+| `graph` | Build or update the persistent repository graph (`.gitview/graph.sqlite`) | no |
+| `observe` | Store a structural observation from an external code analyser | no |
+| `motifs` | Detect recurring historical and architectural motifs | no |
+| `extract` | Extract git history to JSONL | no |
+| `chunk` | Chunk an extracted history into phases | no |
+| `storyline` | Inspect storylines tracked across phases | no |
+| `worklog` | Work log from GitHub commits across branches, for a date range | no |
+| `track-files` | Per-file change history, optionally with AI summaries | optional |
+| `file-history` | Show the change history of one file | no |
+| `inject-history` / `remove-history` | Write that history into file headers, or remove it | no |
+| `compare-branches` | Compare file histories between two branches | no |
+
+Run `gitview <command> --help` for the options of each.
+
+## Installation
+
+### Option 1: Install from PyPI (recommended)
+
+Install the published package directly from PyPI to add the `gitview` command to your PATH:
+
+```bash
+pip3 install gitview
+
+# Confirm the CLI is available
+gitview --version
+gitview --help
+```
+
+### Option 2: Install from source (editable)
+
+This installs directly from the repository in editable mode so local changes take effect immediately:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/gitview.git
+cd gitview
+
+# Install in editable mode with dependencies
+pip install -e .
+
+# The gitview command is now available system-wide
+gitview --version
+gitview --help
+```
+
+**How it works:** The `pip install -e .` command reads `pyproject.toml` and `setup.py`, which define an entry point that creates `/usr/local/bin/gitview` (or similar on Windows) that calls `gitview.cli:main`.
+
+### Option 3: Run directly from repo (no installation)
+
+Use the executable wrapper in `bin/`:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/gitview.git
+cd gitview
+
+# Install dependencies only
+pip install -r requirements.txt
+
+# Run directly from the repo
+./bin/gitview --version
+./bin/gitview analyze
+
+# Or add bin/ to your PATH
+export PATH="$PWD/bin:$PATH"
+gitview analyze
+```
+
+### Option 4: Run as Python module
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run as a module
+python -m gitview.cli --help
+python -m gitview.cli analyze
+```
+
+### Verify Installation
+
+Run the verification script to check everything is set up correctly:
+
+```bash
+python verify_installation.py
+```
+
+This will check:
+- Python version (3.8+ required)
+- All required dependencies
+- `gitview` command availability
+- LLM backend configuration (API keys, Ollama server)
+
+### Troubleshooting Installation
+
+If `gitview` command is not found after installation:
+
+```bash
+# Option 1: Use full path to module
+python -m gitview.cli analyze
+
+# Option 2: Reinstall in editable mode
+pip uninstall gitview -y
+pip install -e .
+
+# Option 3: Check if it's in your PATH
+which gitview  # Unix/Linux/Mac
+where gitview  # Windows
+```
+
+## Quick Start
+
+```bash
+# Using Anthropic Claude (default)
+export ANTHROPIC_API_KEY="your-api-key-here"
+gitview analyze
+
+# Using OpenAI GPT
+export OPENAI_API_KEY="your-api-key-here"
+gitview analyze --backend openai
+
+# Using local Ollama (no API key needed)
+gitview analyze --backend ollama --model llama3
+
+# With GitHub PR/review enrichment (richer narratives!)
+export GITHUB_TOKEN="ghp_your_token_here"
+gitview analyze --repo owner/repo --github-token $GITHUB_TOKEN
+
+# Critical examination mode (for project leads)
+gitview analyze --critical --todo GOALS.md
+
+# Skip LLM summarization (just extract and chunk)
+gitview analyze --skip-llm
+```
+
+## Usage
+
+### Full Analysis Pipeline
+
+The main command runs the complete pipeline: extract → chunk → summarize → story → output
+
+```bash
+gitview analyze [OPTIONS]
+
+Options:
+  -r, --repo PATH              Path to git repository (default: current directory)
+  -o, --output PATH            Output directory (default: "output")
+  -s, --strategy STRATEGY      Chunking strategy: fixed, time, or adaptive (default: adaptive)
+  --chunk-size INTEGER         Chunk size for fixed strategy (default: 50)
+  --max-commits INTEGER        Maximum commits to analyze
+  --branch TEXT                Branch to analyze (default: HEAD)
+  -b, --backend BACKEND        LLM backend: anthropic, openai, or ollama (auto-detected)
+  -m, --model TEXT             Model identifier (uses backend defaults if not specified)
+  --api-key TEXT               API key for the backend (defaults to env var)
+  --ollama-url TEXT            Ollama API URL (default: http://localhost:11434)
+  --repo-name TEXT             Repository name for output
+  --skip-llm                   Skip LLM summarization (extract and chunk only)
+  --todo PATH                  Path to goals/todo file for critical examination mode
+  --critical                   Enable critical examination mode (focus on gaps and issues)
+  --directives TEXT            Additional plain text directives for LLM analysis
+  --github-token TEXT          GitHub token for PR/review enrichment (or GITHUB_TOKEN env var)
+```
+
+### Extract Only
+
+Extract git history to JSONL file without LLM processing:
+
+```bash
+gitview extract --repo /path/to/repo --output history.jsonl
+```
+
+### Chunk Only
+
+Chunk an extracted JSONL file into phases:
+
+```bash
+gitview chunk history.jsonl --output ./phases --strategy adaptive
+```
+
+### Agent Brief (No LLM)
+
+Compile a compact, agent-oriented history digest — commit stats, a phase
+timeline, and detected storylines — into a single markdown file. Unlike
+`analyze`, this never calls an LLM: it's meant to be generated once (and
+regenerated cheaply after a batch of new commits) and then just read, so an
+AI coding agent doesn't have to re-derive project history from `git log`
+and file exploration at the start of every session.
+
+```bash
+# Write ./AGENT_BRIEF.md (skips automatically if HEAD hasn't moved)
+gitview brief
+
+# Always regenerate, even if already up to date
+gitview brief --force
+
+# Check freshness only (exit 1 if stale); doesn't write anything
+gitview brief --check
+
+# Custom output path
+gitview brief -o docs/BRIEF.md
+
+# Build/update the persistent repository graph (no LLM)
+gitview graph                     # Build or update .gitview/graph.sqlite, print counts
+gitview graph --stats             # Also list most changed / most coupled / most connected files
+gitview graph --rebuild           # Drop and rebuild from scratch
+gitview graph --json              # Machine-readable output
+```
+
+### Evidence-First Analysis (Fewer LLM Calls)
+
+`gitview analyze` builds the repository graph and runs the motif catalogue
+*before* it talks to a model, then spends model calls only where the evidence
+says a narrative is worth it:
+
+| `--llm-budget` | Phase summaries | Story sections |
+|----------------|-----------------|----------------|
+| `full` | every phase goes to the model, with an evidence block in the prompt | 3 model calls; technical evolution and deletions are rendered from evidence |
+| `balanced` (default) | routine phases (docs churn, small config runs, no motifs, no PR narrative) are written from evidence; the rest go to the model | 3 model calls |
+| `minimal` | only phases with strong signals (significant commits, motifs, PR narratives) go to the model | 3 model calls |
+
+A phase's signal score adds up: a significant commit (an addition or deletion
+over 1,000 lines, or a refactor with real churn) 0.35; a motif *event* landing
+in the phase (ownership handover, a dependency first appearing, a split, a
+centrality jump) 0.20; PR narratives 0.15; two or more kinds of activity 0.15;
+a large phase (15+ commits or 3,000+ changed lines) 0.10. Standing patterns
+such as repeated co-change or a stable interface are shown to the model as
+context but never trigger a call on their own. `balanced` narrates at 0.35,
+`minimal` at 0.6.
+
+Every story prompt (executive summary, timeline, full narrative) ends with a
+block of hard facts taken from git — the exact date span, the complete list of
+contributors, submodules from `.gitmodules`, top-level directories, most
+changed files and version strings seen in commit subjects — followed by rules:
+nothing after the last commit, no technologies that are not in the facts or
+the summaries, plans are not implementations. Long histories are split into
+batches that are stitched chronologically; the former merge call, which saw
+only prose and invented the connecting tissue, is gone.
+
+Line counts follow git's own arithmetic: merge commits carry no churn (the
+merged branch's commits are already counted, as with `git log --numstat`) and
+renames are detected, so a moved file is not a deletion plus an insertion.
+Caches carry an extraction version; history extracted by an older GitView is
+re-extracted automatically, and `gitview graph` rebuilds once.
+
+With `--hierarchical`, per-cluster mini-summaries come from evidence too, so a
+narrated phase costs one call instead of one per cluster plus one. The report
+gains an *Architectural Motifs* section, every prompt that is sent carries the
+established facts (clusters, hot files, coupling, motifs), and the run ends
+with `LLM calls this run: N`. `--no-evidence` restores the previous behaviour.
+
+### Structural Evidence & Motifs (No LLM)
+
+GitView's graph is built from git history alone. A *structural provider* — an
+external code analyser — can add the present shape of the code (which file
+imports, calls or inherits from which) at one commit. GitView translates that
+into its own neutral model (`StructuralSnapshot`, `StructuralNode`,
+`StructuralEdge`) and stores it in `.gitview/graph.sqlite` with provenance:
+provider, provider version, the commit it observed and a hash of the raw
+output. Nothing in GitView's core names the analyser; Graphify is simply the
+first implementation of the `StructuralProvider` seam.
+
+```bash
+gitview observe --structural graphify            # store graphify-out/graph.json as an observation
+gitview observe --structural graphify --refresh  # let GitView run `graphify update` first
+gitview graph --structural graphify              # build the graph and observe in one go
+gitview motifs                                   # detect motifs
+gitview motifs --list                            # motif catalog with evidence requirements
+gitview motifs --only hidden_coupling --json
+```
+
+Motifs declare the evidence they need and are skipped, with the reason, when it
+is missing — so `gitview motifs` always works, just with fewer motifs:
+
+| Evidence | Motifs |
+|----------|--------|
+| History only | repeated co-change, ownership transition |
+| History + one observation | hidden coupling, confirmed coupling, stable interface |
+| History + observations at two or more commits | emerging dependency, architectural split, centrality growth |
+
+In a multi-repository layout (git submodules), build Graphify once at the
+superproject root; `gitview observe` run inside a module finds that graph on
+its own and re-bases it under the module's path, so each module's history is
+matched against the structure of the whole system. Edges into other modules
+are dropped (they have no counterpart in this module's history), and the
+observation records the module's own commit.
+
+Observe again after significant work (or from an older commit via `--source`)
+to enable the series motifs; GitView orders observations by their commit's
+position in the history graph and reports, for example, how many commits of
+co-change preceded a dependency becoming explicit in the source.
+```
+
+Commit the result so future sessions (yours or an agent's) can read it
+instead of re-analyzing the repository. `--repo` accepts a local path only
+(unlike `analyze`/`worklog`, which also accept GitHub shortcuts/URLs).
+
+### Work Log (GitHub, No LLM)
+
+Generate a chronological work log from GitHub commit history across **all**
+branches — useful for billing, timesheets, and status reports. `worklog`
+queries GitHub's GraphQL API, deduplicates commits by SHA (a commit merged to
+multiple branches is counted once), resolves the best associated Pull Request
+for each commit, and renders the result as Markdown (default) or CSV. Like
+`brief`, it never calls an LLM.
+
+```bash
+# Markdown work log for a date range (writes an auto-named file)
+gitview worklog --repo org/repo --since 2024-01-01 --until 2024-01-31
+
+# Current directory (auto-detects the GitHub remote)
+gitview worklog --repo . --since 2024-01-01 --until 2024-01-31
+
+# Filter by a GitHub login and export CSV to a specific file
+gitview worklog --repo . --since 2024-01-01 --until 2024-01-31 \
+    --author octocat --format csv -o jan.csv
+
+# Pipe to stdout (auto-detected when output is not a terminal)
+gitview worklog --repo org/repo --since 2024-01-01 --until 2024-01-31 | less
+```
+
+**Options:**
+
+```
+  -r, --repo TEXT        Repository: local path, GitHub shortcut (org/repo), or full URL (default: .)
+  --since TEXT           Start date: YYYY-MM-DD or ISO-8601 timestamp (required)
+  --until TEXT           End date: YYYY-MM-DD or ISO-8601 timestamp, inclusive (required)
+  --author TEXT          Filter commits by GitHub login (optional)
+  --format [markdown|csv]  Output format (default: markdown)
+  -o, --output PATH      Output file path (default: auto-named in current directory)
+  --github-token TEXT    GitHub token (defaults to GITHUB_TOKEN env var)
+```
+
+**Notes:**
+- A GitHub token with at least `repo` read scope is required — pass
+  `--github-token` or set `GITHUB_TOKEN`.
+- Dates accept both `YYYY-MM-DD` and full ISO-8601 timestamps. `--since`
+  defaults to `00:00:00` UTC and `--until` to `23:59:59` UTC.
+- When output is redirected (not a terminal), the log is printed to stdout so
+  it can be piped; otherwise it is written to an auto-named file such as
+  `worklog_org_repo_2024-01-01_2024-01-31.md`.
+
+## File History Tracking & Header Injection
+
+GitView provides powerful file-level change tracking with AI-powered summaries and the ability to inject change histories directly into source files as header comments. This is ideal for deep code analysis, debugging, accountability, and understanding individual file evolution.
+
+### Features
+
+- **Per-File Change Tracking**: Track detailed change history for every file in your repository
+- **AI-Powered Summaries**: Generate intelligent summaries of changes using LLMs (with caching for cost optimization)
+- **Multi-Language Header Injection**: Inject history as comments into source files (18+ languages supported)
+- **Branch Comparison**: Compare file histories between branches with divergence analysis
+- **Incremental Processing**: Checkpoint-based system only processes new commits
+- **Cost Optimization**: 99.9% cost reduction through hash-based caching
+
+### Quick Start - File Tracking
+
+```bash
+# Track all file changes in your repository
+gitview track-files
+
+# Track with AI-powered summaries
+gitview track-files --with-ai
+
+# View history for a specific file
+gitview file-history gitview/cli.py
+
+# Inject history as header comment into a file
+gitview inject-history gitview/cli.py
+
+# Remove injected header
+gitview remove-history gitview/cli.py
+
+# Compare file histories between branches
+gitview compare-branches main feature-branch
+```
+
+### Phase 1: Core File Tracking
+
+Track detailed change history for every file in your repository with incremental processing.
+
+```bash
+# Basic file tracking
+gitview track-files
+
+# Track specific file patterns
+gitview track-files --pattern "*.py"
+
+# Limit commits per file
+gitview track-files --max-commits 50
+```
+
+**Output Structure:**
+```
+output/file_histories/
+├── checkpoint.json              # Resume tracking from last processed commit
+├── files/
+│   ├── gitview_cli.py.history   # Human-readable history
+│   └── gitview_cli.py.json      # Machine-readable JSON
+└── index.json                   # Index of all tracked files
+```
+
+**File History Content:**
+- Commit-by-commit changes with full metadata
+- Lines added/removed per change
+- Author information and timestamps
+- Diff snippets for each change
+- AI summaries (if enabled)
+
+### Phase 2: AI-Powered Summaries
+
+Generate intelligent summaries of file changes using LLMs with cost optimization.
+
+```bash
+# Track with AI summaries (uses caching)
+gitview track-files --with-ai
+
+# Cost estimate before running
+gitview track-files --with-ai --dry-run
+```
+
+**Supported LLM Backends:**
+- **Anthropic Claude** (claude-sonnet-5, claude-haiku-4-5)
+- **Claude Code CLI** (a logged-in local `claude`, billed to the plan)
+- **OpenAI GPT** (gpt-4o, gpt-4o-mini)
+- **Ollama** (llama3, mistral, codellama - runs locally, free)
+
+**Cost Optimization:**
+- Hash-based caching prevents duplicate summaries
+- Incremental processing only analyzes new commits
+- Cache hit rate typically >95% on reruns
+- Estimated cost: $0.10-0.50 per 1000 files (using gpt-4o-mini)
+
+**Cache Location:**
+```
+output/file_histories/summaries_cache.json
+```
+
+**Example AI Summary:**
+```
+Modified FileHistoryTracker.get_file_history() to support incremental
+processing with checkpoint system. Added since_commit parameter to
+iter_commits() to only process new commits after last checkpoint.
+Breaking change: requires checkpoint.json for resume functionality.
+```
+
+### Phase 3: Header Injection
+
+Inject file change histories as header comments into source files for debugging and accountability.
+
+```bash
+# Inject history into a Python file
+gitview inject-history gitview/file_tracker.py
+
+# Inject with limited entries
+gitview inject-history gitview/file_tracker.py --max-entries 5
+
+# Preview without writing (dry-run)
+gitview inject-history gitview/file_tracker.py --dry-run
+
+# Inject into multiple files
+gitview inject-history gitview/*.py
+
+# Remove injected headers
+gitview remove-history gitview/file_tracker.py
+```
+
+**Supported Languages (18+):**
+- Python, JavaScript, TypeScript, Java, Go, Rust, C/C++, C#
+- Ruby, PHP, Swift, Kotlin, Scala, Shell, SQL, R, Perl, Lua, YAML
+
+**Header Format Example (Python):**
+```python
+# ==============================================================================
+# FILE CHANGE HISTORY
+# ==============================================================================
+# File: gitview/file_tracker.py
+# Total changes: 15 commits
+# Authors: John Doe (10), Jane Smith (5)
+#
+# [Recent Changes - Last 10 of 15]
+#
+# 2026-01-22 | abc123f | John Doe
+#   Add incremental checkpoint system for resumable tracking
+#   Changes: +45 -12 lines
+#
+#   Summary: Implemented checkpoint-based resume functionality...
+#
+# 2026-01-20 | def456a | Jane Smith
+#   Fix diff parsing for binary files
+#   Changes: +8 -3 lines
+#
+# ==============================================================================
+# END FILE CHANGE HISTORY
+# ==============================================================================
+
+# Your actual code starts here...
+```
+
+**Use Cases:**
+- Add accountability headers to critical files
+- Include change context in code reviews
+- Debug issues by understanding file evolution
+- Onboarding - new developers see file history inline
+- Compliance and audit trails
+
+### Phase 4: Branch Comparison
+
+Compare file histories between branches with divergence analysis and AI-powered comparison.
+
+```bash
+# Compare two branches
+gitview compare-branches main feature-branch
+
+# Compare with AI analysis of divergences
+gitview compare-branches main feature-branch --with-ai
+
+# Custom output location
+gitview compare-branches main dev --output ./branch-analysis
+```
+
+**Output Structure:**
+```
+output/branch_comparisons/
+├── branches/
+│   ├── main/
+│   │   ├── files/
+│   │   │   ├── gitview_cli.py.json
+│   │   │   └── gitview_tracker.py.json
+│   │   └── branch_metadata.json
+│   └── feature_branch/
+│       ├── files/
+│       └── branch_metadata.json
+└── comparisons/
+    └── main_vs_feature_branch/
+        ├── summary.json
+        ├── divergences.json
+        ├── report.txt
+        └── ai_analysis.json (if --with-ai used)
+```
+
+**Divergence Analysis:**
+- Files unique to each branch
+- Commits that diverged between branches
+- Line change differences
+- Divergence score (0-100) for each file
+
+**Example Report:**
+```
+Branch Comparison: main vs feature-branch
+==========================================
+
+Summary:
+  Files in main: 45
+  Files in feature-branch: 47
+  Files in both: 43
+  Files only in main: 2
+  Files only in feature-branch: 4
+
+Top Divergent Files (score 0-100):
+  1. gitview/file_tracker.py        Score: 87.5
+     - 12 commits only in main
+     - 8 commits only in feature-branch
+     - +234 -156 lines difference
+
+  2. gitview/cli.py                 Score: 65.3
+     - 5 commits only in main
+     - 3 commits only in feature-branch
+     - +89 -45 lines difference
+```
+
+**AI Analysis (with --with-ai):**
+- Semantic comparison of divergent changes
+- Identifies conflicting implementations
+- Suggests merge strategies
+- Highlights breaking changes
+
+### Complete Workflow Example
+
+```bash
+# 1. Initial file tracking with AI summaries
+gitview track-files --with-ai
+
+# 2. View history for a specific file
+gitview file-history gitview/file_tracker.py
+
+# 3. Inject history into critical files
+gitview inject-history gitview/file_tracker.py gitview/cli.py
+
+# 4. Switch to feature branch and track
+git checkout feature-branch
+gitview track-files --with-ai
+
+# 5. Compare branches
+gitview compare-branches main feature-branch --with-ai
+
+# 6. Review divergences and make decisions
+cat output/branch_comparisons/comparisons/main_vs_feature_branch/report.txt
+
+# 7. After merge, update file histories
+git checkout main
+git merge feature-branch
+gitview track-files --with-ai
+
+# 8. Update injected headers
+gitview inject-history gitview/file_tracker.py
+```
+
+### Configuration
+
+File tracking uses the same LLM backend configuration as the main analysis:
+
+```bash
+# Use Anthropic Claude (default)
+export ANTHROPIC_API_KEY="your-key"
+gitview track-files --with-ai
+
+# Use OpenAI GPT
+export OPENAI_API_KEY="your-key"
+gitview track-files --with-ai --backend openai --model gpt-4o-mini
+
+# Use Ollama (local, free)
+ollama serve
+gitview track-files --with-ai --backend ollama --model llama3
+```
+
+### Performance & Costs
+
+**Incremental Processing:**
+- First run: Processes entire git history
+- Subsequent runs: Only processes new commits since last checkpoint
+- 10,000 commit repo: ~5 minutes first run, ~10 seconds for updates
+
+**AI Summary Costs (estimated):**
+- 1,000 files with gpt-4o-mini: ~$0.15-0.30
+- 1,000 files with claude-haiku: ~$0.40-0.80
+- 1,000 files with Ollama: $0 (local)
+- Cache hit rate >95% on reruns = virtually free
+
+**Storage:**
+- Each file history: ~5-50KB depending on commit count
+- AI cache: ~1KB per cached summary
+- 1,000 files: ~50-100MB total
+
+## Critical Examination Mode
+
+For project leads who need objective assessment rather than celebratory narratives, GitView offers a critical examination mode that focuses on gaps, technical debt, and alignment with project goals.
+
+### What Changes in Critical Mode?
+
+**Tone & Focus:**
+- Removes flowery, achievement-focused language
+- Emphasizes objective assessment over celebration
+- Focuses on gaps, issues, and misalignments
+- Identifies what's missing or incomplete
+
+**Analysis:**
+- Evaluates progress against stated objectives
+- Highlights incomplete features and technical debt
+- Questions architectural decisions objectively
+- Identifies delays and resource misalignment
+- Notes concerning patterns and risks
+
+### Usage
+
+**Basic Critical Mode:**
+```bash
+gitview analyze --critical
+```
+
+**With Project Goals/TODO File:**
+```bash
+# Create a goals file (e.g., GOALS.md)
+cat > GOALS.md <<EOF
+# Project Goals Q1 2025
+- Implement user authentication system
+- Add API rate limiting
+- Improve test coverage to 80%
+- Migrate from SQLite to PostgreSQL
+- Complete API documentation
+EOF
+
+# Analyze against goals
+gitview analyze --critical --todo GOALS.md
+```
+
+**With Custom Directives:**
+```bash
+# Add specific analysis focus
+gitview analyze --critical \
+  --todo GOALS.md \
+  --directives "Focus on security vulnerabilities and performance bottlenecks"
+```
+
+**Combined Example:**
+```bash
+# Critical assessment with all options
+gitview analyze \
+  --critical \
+  --todo PROJECT_ROADMAP.md \
+  --directives "Emphasize testing gaps and code quality issues" \
+  --output ./critical-review
+```
+
+### Output in Critical Mode
+
+The LLM will generate:
+
+1. **Critical Executive Summary** - Assesses progress against goals, identifies gaps and delays
+2. **Critical Timeline** - Highlights goal alignment/misalignment per phase
+3. **Critical Technical Assessment** - Identifies architectural flaws and technical debt
+4. **Critical Deletion Analysis** - Notes incomplete cleanup and lingering technical debt
+5. **Comprehensive Critical Assessment** - Full project review with actionable insights
+
+### When to Use Critical Mode
+
+- **Project Reviews**: Objective assessment of development progress
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Alignment**: Measure actual work against stated objectives
+- **Resource Planning**: Understand where effort was spent vs. planned
+- **Risk Assessment**: Identify concerning patterns and project risks
+- **Leadership Reports**: Provide factual assessment to stakeholders
+
+## Storyline Tracking
+
+GitView tracks "storylines" - narrative threads that span multiple phases of development. Instead of just seeing isolated phase summaries, you can follow the arc of features, refactoring efforts, bug fix campaigns, and other initiatives across your project's history.
+
+### What Are Storylines?
+
+Storylines are development threads that GitView automatically detects and tracks:
+
+- **Features**: New functionality being built across multiple phases
+- **Refactoring**: Code cleanup and restructuring efforts
+- **Bug Fixes**: Bug fix campaigns and stability improvements
+- **Tech Debt**: Debt reduction initiatives
+- **Infrastructure**: CI/CD, tooling, and deployment improvements
+- **Documentation**: Documentation efforts
+- **Migrations**: Database or framework migrations
+- **Performance**: Performance optimization work
+- **Security**: Security hardening initiatives
+
+### Multi-Signal Detection
+
+Storylines are detected from multiple sources with confidence scoring:
+
+| Source | Confidence | Description |
+|--------|------------|-------------|
+| PR Labels | 0.9 | GitHub PR labels (feature, bug, refactor) |
+| PR Title Patterns | 0.8 | Patterns like "feat:", "fix:", "[WIP]" |
+| File Clusters | 0.7 | Related files changing together |
+| Commit Messages | 0.6 | Conventional commit patterns |
+| LLM Extraction | 0.5 | AI-detected storylines from summaries |
+
+### Storyline Lifecycle
+
+Storylines progress through states automatically:
+
+```
+EMERGING → ACTIVE → PROGRESSING → COMPLETED
+                  ↘ STALLED → ABANDONED
+```
+
+- **Emerging**: New storyline detected, building confidence
+- **Active**: Confirmed storyline with ongoing work
+- **Progressing**: Active work continues phase-over-phase
+- **Completed**: Storyline reached completion (explicit or inferred)
+- **Stalled**: No activity for 3+ phases
+- **Abandoned**: Stalled for 6+ phases
+
+### CLI Commands
+
+GitView provides a `storyline` command group for exploring tracked storylines:
+
+```bash
+# List all storylines
+gitview storyline list
+
+# Filter by status
+gitview storyline list --status active
+gitview storyline list --status completed
+
+# Filter by category
+gitview storyline list --category feature
+gitview storyline list --category refactor
+
+# Show details for a specific storyline
+gitview storyline show <storyline-id>
+gitview storyline show oauth-impl  # partial ID match works
+
+# Generate comprehensive report
+gitview storyline report
+gitview storyline report --save storyline-report.md
+
+# View ASCII timeline visualization
+gitview storyline timeline
+
+# Export to JSON or CSV
+gitview storyline export --format json
+gitview storyline export --format csv --dest storylines.csv
+```
+
+### Example Output
+
+**Storyline List:**
+```
+┌────────┬──────────────────────────┬────────────┬────────┬──────┬──────────────┐
+│ Status │ Title                    │ Category   │ Phases │ Conf │ ID           │
+├────────┼──────────────────────────┼────────────┼────────┼──────┼──────────────┤
+│ ✓      │ OAuth Implementation     │ feature    │ 1→3    │ 90%  │ oauth-impl.. │
+│ ●      │ API Rate Limiting        │ feature    │ 2→4    │ 85%  │ api-rate-l.. │
+│ ▶      │ Test Coverage Expansion  │ tech_debt  │ 3→4    │ 75%  │ test-cover.. │
+│ ◌      │ Legacy Migration         │ migration  │ 1→2    │ 70%  │ legacy-mig.. │
+└────────┴──────────────────────────┴────────────┴────────┴──────┴──────────────┘
+```
+
+**ASCII Timeline:**
+```
+Storyline                                1  2  3  4  5
+────────────────────────────────────────────────────────
+OAuth Implementation                     ┌────┘
+API Rate Limiting                           ┌────→
+Test Coverage Expansion                        ┌──→
+Legacy Migration                         ┌──╳
+
+Legend: ┌─ start, ─┘ completed, ─→ ongoing, ─╳ stalled
+```
+
+### Output in Reports
+
+When you run `gitview analyze`, storylines are automatically:
+
+1. **Detected** from commits, PRs, and file patterns
+2. **Tracked** across phases with state transitions
+3. **Included** in the main `history_story.md` report
+4. **Persisted** to `output/phases/storylines.json` for incremental analysis
+
+The storyline section in your report includes:
+- Summary of completed, active, and stalled storylines
+- Timeline visualization
+- Cross-phase theme analysis
+- Category breakdown
+
+### Persistence & Incremental Analysis
+
+Storyline data is persisted to `output/phases/storylines.json`, enabling:
+
+- **Incremental updates**: New phases add to existing storyline data
+- **State continuity**: Storyline states persist across runs
+- **Export capabilities**: Use the data in other tools
+
+## GitHub Enrichment (PR & Review Context)
+
+GitView can enrich commit history with Pull Request context from GitHub's GraphQL API, providing richer narratives based on actual PR descriptions and review feedback rather than just commit messages.
+
+### What GitHub Enrichment Provides
+
+- **PR Titles & Descriptions**: Use the "why" from PR descriptions instead of terse commit messages
+- **Review Comments**: Include reviewer feedback and discussion context
+- **Reviewer Attribution**: Track who reviewed and approved changes
+- **PR Labels**: Categorize work by type (feature, bug, refactor, etc.)
+- **Branch Information**: Understand feature branch to main branch flow
+
+### Getting Started
+
+1. **Generate a GitHub Token**:
+   - Go to https://github.com/settings/tokens
+   - Create "Personal access token (classic)"
+   - Select `repo` scope for private repos (or `public_repo` for public only)
+   - Copy the token
+
+2. **Use with GitView**:
+
+```bash
+# Set as environment variable
+export GITHUB_TOKEN="ghp_your_token_here"
+gitview analyze --repo owner/repo --github-token $GITHUB_TOKEN
+
+# Or pass directly
+gitview analyze --repo owner/repo --github-token "ghp_your_token_here"
+```
+
+### Example with GitHub Enrichment
+
+```bash
+# Analyze a GitHub repository with PR context
+export GITHUB_TOKEN="ghp_..."
+gitview analyze \
+  --repo carstenbund/gitview \
+  --github-token $GITHUB_TOKEN \
+  --output ./enriched-analysis
+
+# The resulting narratives will include:
+# - PR descriptions explaining WHY changes were made
+# - Review feedback providing context on design decisions
+# - Labels helping categorize types of work
+```
+
+### How It Improves Narratives
+
+**Without GitHub Enrichment:**
+> "Commit abc123: Fix bug in login flow"
+
+**With GitHub Enrichment:**
+> "PR #42 'Fix authentication race condition' addressed a critical issue where users could be logged out during token refresh. The fix was reviewed by @alice who suggested the retry mechanism that was ultimately implemented. Labels: [bug, security, priority-high]"
+
+### Caching
+
+GitHub API responses are cached locally in `~/.gitview/cache/github` for 24 hours to:
+- Reduce API calls on repeated runs
+- Improve performance for large repositories
+- Stay within GitHub's rate limits
+
+### Rate Limits
+
+GitHub GraphQL API has a points-based rate limit (5,000 points/hour). GitView:
+- Uses efficient batched queries
+- Caches responses to minimize API calls
+- Gracefully falls back if rate limited
+
+## Chunking Strategies
+
+GitView supports three chunking strategies:
+
+### 1. **Adaptive** (Recommended)
+
+Automatically splits history when significant changes occur:
+- LOC changes by >30%
+- Large deletions/additions detected
+- README rewrites
+- Major refactorings
+
+```bash
+gitview analyze --strategy adaptive
+```
+
+### 2. **Fixed Size**
+
+Splits history into fixed-size chunks (e.g., 50 commits per phase):
+
+```bash
+gitview analyze --strategy fixed --chunk-size 50
+```
+
+### 3. **Time-Based**
+
+Splits by time periods (week, month, quarter, year):
+
+```bash
+gitview analyze --strategy time --period quarter
+```
+
+## Output Files
+
+GitView generates several output files:
+
+```
+output/
+├── repo_history.jsonl           # Raw commit data
+├── phases/                       # Phase data
+│   ├── phase_01.json
+│   ├── phase_02.json
+│   ├── phase_index.json
+│   └── storylines.json          # Storyline tracking data
+├── history_story.md              # Main narrative report
+├── timeline.md                   # Simple timeline
+└── history_data.json             # Complete data in JSON
+```
+
+### Main Report (`history_story.md`)
+
+Contains:
+- **Executive Summary**: High-level overview for stakeholders
+- **Timeline**: Chronological phases with descriptive headings
+- **Full Narrative**: Complete story of the codebase evolution
+- **Technical Evolution**: Architectural journey and key decisions
+- **Story of Deletions**: What was removed and why
+- **Storylines**: Cross-phase narrative threads with timeline visualization
+- **Phase Details**: Detailed breakdown of each phase
+- **Statistics**: Comprehensive metrics
+
+## How It Works
+
+### Phase 1: Extract Raw History
+
+Analyzes git commits and extracts:
+- Commit metadata (hash, author, date, message)
+- Lines of code changes (insertions/deletions)
+- File statistics
+- Language breakdown
+- README state and changes
+- Code comments and density
+- Detection of large changes, refactors, etc.
+
+### Phase 2: Chunk into Epochs
+
+Divides history into meaningful phases based on:
+- Significant LOC changes
+- Large deletions or additions
+- Language mix changes
+- README rewrites
+- Major refactorings
+
+### Phase 3: Summarize Each Phase
+
+Uses Claude to generate narrative summaries for each phase, answering:
+- What were the main activities?
+- Why were changes made?
+- What was deleted/added and why?
+- How did documentation evolve?
+- What do commit messages reveal?
+
+### Phase 4: Generate Global Story
+
+Combines phase summaries to create:
+- Executive summary for non-technical readers
+- Chronological timeline with meaningful headings
+- Technical retrospective
+- Story of code deletions and cleanups
+- Full detailed narrative
+
+## Examples
+
+### Analyze a Large Open Source Project
+
+```bash
+gitview analyze \
+  --repo /path/to/large-project \
+  --output ./project-analysis \
+  --strategy adaptive \
+  --repo-name "My Project"
+```
+
+### Quick Analysis Without LLM
+
+Perfect for quick exploration or when you don't have an API key:
+
+```bash
+gitview analyze --skip-llm --output ./quick-analysis
+```
+
+### Extract and Process Later
+
+```bash
+# Extract once
+gitview extract --repo /path/to/repo --output history.jsonl
+
+# Experiment with different chunking strategies
+gitview chunk history.jsonl --strategy adaptive --output ./adaptive-phases
+gitview chunk history.jsonl --strategy fixed --chunk-size 25 --output ./fixed-phases
+```
+
+### Critical Project Assessment
+
+```bash
+# Create a goals file for your project
+cat > PROJECT_GOALS.md <<EOF
+# Q1 2025 Objectives
+- Complete user authentication with OAuth2
+- Implement API rate limiting (1000 req/hour)
+- Achieve 80% test coverage
+- Migrate database to PostgreSQL
+- Document all public APIs
+EOF
+
+# Run critical analysis
+gitview analyze \
+  --critical \
+  --todo PROJECT_GOALS.md \
+  --directives "Focus on security issues and incomplete features" \
+  --output ./project-review-q1
+
+# Review the critical assessment
+cat ./project-review-q1/history_story.md
+```
+
+## Architecture
+
+```
+┌─────────────────────┐
+│   Git Repository    │
+└──────────┬──────────┘
+           │
+           v
+┌─────────────────────┐
+│  Extractor          │  Analyzes commits, extracts metadata
+│  (extractor.py)     │  Output: repo_history.jsonl
+└──────────┬──────────┘
+           │
+           v
+┌─────────────────────┐
+│  Chunker            │  Splits into meaningful phases
+│  (chunker.py)       │  Strategies: adaptive, fixed, time
+└──────────┬──────────┘
+           │
+           v
+┌─────────────────────┐     ┌─────────────────────┐
+│  Evidence Ledger    │<────│  Repository Graph   │  commits, files, authors,
+│  (evidence.py)      │     │  (graph/)           │  PRs, co-change coupling
+│  Decides which      │     └──────────┬──────────┘
+│  phases need a      │                │
+│  model call, and    │     ┌──────────v──────────┐     ┌──────────────────┐
+│  supplies the facts │<────│  Motifs             │<────│  Structural      │
+│  every prompt gets  │     │  (motifs/)          │     │  (structural/)   │
+└──────────┬──────────┘     └─────────────────────┘     │  optional, via a │
+           │                                            │  provider seam   │
+           │                                            └──────────────────┘
+           v
+┌─────────────────────┐     ┌─────────────────────┐
+│  Summarizer         │────>│  Storyline Tracker  │
+│  (summarizer.py)    │     │  (storyline/)       │
+└──────────┬──────────┘     │  Multi-signal       │
+           │                │  detection & state  │
+           v                │  machine lifecycle  │
+┌─────────────────────┐     └──────────┬──────────┘
+│  StoryTeller        │<───────────────┘
+│  (storyteller.py)   │  Generates global narratives
+└──────────┬──────────┘  with storyline context
+           │
+           v
+┌─────────────────────┐
+│  Writer             │  Outputs markdown, JSON, etc.
+│  (writer.py)        │  Includes storyline reports
+└─────────────────────┘
+```
+
+## Requirements
+
+- Python 3.8+
+- Git repository with commit history
+- **One of the following LLM backends** (not needed for `brief`, `graph`, `observe`, `motifs`, `extract`, `chunk`, `worklog`):
+  - **Anthropic Claude** (requires API key)
+  - **Claude Code CLI** (a logged-in local `claude`; billed to the Claude plan, no API key)
+  - **OpenAI GPT** (requires API key)
+  - **Ollama** (runs locally, no API key needed)
+- Optional: a structural analyser such as [Graphify](https://github.com/carstenbund/graphify) for structural motifs
+- Dependencies: gitpython, anthropic, openai, requests, click, rich, pydantic
+
+## LLM Backend Configuration
+
+GitView supports four LLM backends. Without `--backend`, it picks the first available:
+`ANTHROPIC_API_KEY`, then `OPENAI_API_KEY`, then a logged-in `claude` CLI, then Ollama.
+
+### Anthropic Claude (Default)
+
+Get an API key from [Anthropic](https://www.anthropic.com/)
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key-here"
+gitview analyze
+```
+
+Default model: `claude-sonnet-5`. Pass `--model` for another, for example
+`claude-opus-5` (more capable) or `claude-haiku-4-5` (cheaper).
+
+### Claude Code CLI
+
+Runs generation through a locally installed, logged-in `claude` (Claude Code)
+in print mode, so a Claude plan covers the usage and no `ANTHROPIC_API_KEY` is
+needed.
+
+```bash
+claude /login          # once
+gitview analyze --backend claude-cli
+```
+
+The model is a CLI alias (`sonnet` by default, `--model opus` for another).
+No transcript is written, and `max_tokens` and `temperature` have no CLI
+equivalent, so they are ignored.
+
+### OpenAI GPT
+
+Get an API key from [OpenAI](https://platform.openai.com/)
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+gitview analyze --backend openai
+```
+
+Default model: `gpt-4o-mini`. Pass `--model gpt-4o` for a stronger one.
+
+### Ollama (Local)
+
+Install [Ollama](https://ollama.ai/) and pull a model:
+
+```bash
+# Install Ollama
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Pull a model
+ollama pull llama3
+
+# Start Ollama server
+ollama serve
+
+# Use with GitView (no API key needed)
+gitview analyze --backend ollama --model llama3
+```
+
+Popular Ollama models:
+- `llama3` (default, balanced)
+- `mistral` (fast, good quality)
+- `codellama` (optimized for code)
+- `mixtral` (large, powerful)
+
+### Custom Configuration
+
+```bash
+# Specify custom model
+gitview analyze --backend anthropic --model claude-opus-5
+
+# Use custom Ollama URL
+gitview analyze --backend ollama --ollama-url http://192.168.1.100:11434
+
+# Pass API key directly (instead of env var)
+gitview analyze --backend openai --api-key "your-key"
+```
+
+## Use Cases
+
+### Standard Mode (Celebratory Narrative)
+- **Technical Documentation**: Automatically generate project history documentation
+- **Onboarding**: Help new developers understand codebase evolution
+- **Retrospectives**: Review what worked and what didn't
+- **Project Reports**: Create compelling narratives for stakeholders
+- **Code Archaeology**: Understand why code evolved the way it did
+- **Cleanup Planning**: Identify what to remove based on deletion history
+
+### Critical Examination Mode
+- **Project Leadership**: Objective assessment for project leads and managers
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Tracking**: Measure actual progress against roadmap objectives
+- **Resource Analysis**: Understand where development effort was spent
+- **Risk Management**: Identify concerning patterns and project risks
+- **Stakeholder Reports**: Provide factual, critical assessment to executives
+
+### Storyline Tracking
+- **Feature Tracking**: Follow features from inception to completion across phases
+- **Refactoring Visibility**: Track long-running refactoring efforts and their progress
+- **Stalled Work Detection**: Identify initiatives that have stalled or been abandoned
+- **Cross-Phase Analysis**: Understand how work threads connect across time
+- **Project Health**: See the balance of active, completed, and stalled storylines
+- **Timeline Visualization**: ASCII timeline showing storyline arcs
+
+### File Tracking & Header Injection
+- **Deep Code Analysis**: Inject complete change history into files for debugging complex issues
+- **Compliance & Accountability**: Track who changed what and when with inline headers
+- **Code Reviews**: Include file evolution context directly in reviewed files
+- **Developer Onboarding**: New team members see file history without leaving their editor
+- **Branch Divergence Analysis**: Identify conflicts before merging feature branches
+- **Refactoring Decisions**: Understand file evolution patterns to guide architecture changes
+- **Bug Investigation**: Trace file changes to identify when bugs were introduced
+- **Technical Debt Tracking**: Compare branch histories to assess divergence costs
+- **Documentation**: Generate per-file change logs for critical components
+- **AI-Powered Insights**: Get intelligent summaries of complex code changes
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.
+
+## License
+
+MIT License - see LICENSE file for details
+
+
+
+[github-ci]: https://github.com/carstenbund/gitview/actions/workflows/test.yml/badge.svg?branch=main
+[github-link]: https://github.com/carstenbund/gitview
+[pypi-badge]: https://img.shields.io/pypi/v/gitview.svg
+[pypi-link]: https://pypi.org/project/gitview
+[codecov-badge]: https://codecov.io/gh/carstenbund/gitview/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/carstenbund/gitview
+[install-badge]: https://img.shields.io/pypi/dw/gitview?label=pypi%20installs
+[install-link]: https://pypistats.org/packages/gitview