git-narrator

Your commits are a story. Most devs never read it. This does.

Automatically groups git commits by theme and generates structured narrative episodes from them. Runs nightly via cron or on demand.

🇮🇹 Versione italiana disponibile in fondo

---

What it does

git log (last 7 days)
    │
    ▼
Group commits by theme (Claude API)
    │
    ├── Group A: "logging system refactor"  →  Episode 1
    ├── Group B: "new dashboard features"   →  Episode 2
    └── Group C: "build fixes"              →  Episode 3
    │
    ▼
Save as structured markdown with metadata
(title, summary, technical_details, tags, date)

Each episode is a readable account of what was built and why — not a changelog, but a narrative that can be used for documentation, content, or memory.

---

Output example

## The Night the Dashboard Stopped Crashing

Three commits. One root cause hiding behind two symptoms.

The watcher was spawning a new process on every file change
instead of debouncing. At 847 files, that meant 847 parallel
processes at 2:07 AM...

---

Features

• Thematic grouping — commits clustered by topic, not by time
• Dual-pass generation — fast model for draft, precise model for final
• Structured output — title, summary, body, tags, one-liner hook
• Incremental — skips commits already processed (manifest-based)
• Cron-ready — designed to run nightly (or whenever you want)

---

Quick start

pip install anthropic gitpython
export ANTHROPIC_API_KEY=your_key

# Generate episodes from last 7 days of commits
python story_agent.py

# From a specific date
python story_agent.py --since 2026-05-01

# Stats
python story_agent.py --stats

---

Changelog

Version	Date	Status
v1.0	2026-05-29	ACTIVE — dual-pass haiku+sonnet, cron + stop hook
v0.1	2026-03	REPLACED by v1.0 — single-pass, no thematic grouping

---

Part of

TITANIUM_OS — personal cognitive OS. Full source: NODES/STORY_AGENT/story_agent.py

---

Versione italiana

I tuoi commit sono una storia. La maggior parte degli sviluppatori non la legge mai. Questo lo fa.

Raggruppa automaticamente i commit git per tema e genera episodi narrativi strutturati. Gira ogni notte via cron o su richiesta.

Come funziona: prende il git log degli ultimi 7 giorni → raggruppa per tema (Claude API) → genera un episodio narrativo per ogni gruppo → salva come markdown strutturato.

Caratteristiche:

• Raggruppamento tematico — commit per argomento, non per orario
• Generazione dual-pass — modello veloce per la bozza, preciso per il finale
• Incrementale — salta i commit già processati
• Pronto per cron — pensato per girare di notte in automatico

Codice sorgente: TITANIUM_OS → NODES/STORY_AGENT/story_agent.py