GitNarrator
Turn your git history into intelligent, human-readable narratives — powered by Claude, inside VS Code.
What it does
GitNarrator reads your repository's git history and generates a narrative: what changed, why it probably changed, who drove what work, and where the codebase seems to be heading. It's the briefing you wish existed when you return to a project after 3 weeks, or when a new developer joins the team.
Why I built this
git log --oneline gives you commit messages. git diff gives you lines. Neither answers the question I actually ask every Monday morning: "What happened in this codebase last week?" I found myself manually reading through 40-60 commits trying to reconstruct a story that should just exist. The problem gets worse on PRs with 30 files changed — you're diff-reading, not understanding. GitNarrator makes temporal codebase understanding a one-keystroke operation.
How to run it
Prerequisites
- Node.js 18+
- VS Code 1.85+
- An Anthropic API key (get one at console.anthropic.com)
Local development
git clone https://github.com/YOUR_USERNAME/gitnarrator
cd gitnarrator
npm install
# Press F5 in VS Code to launch Extension Development Host
First use
- Open any git repository in VS Code
Ctrl+Shift+P → "GitNarrator: Set Anthropic API Key"Ctrl+Shift+P → "GitNarrator: Narrate This Repo"
Install from marketplace (once published)
Search "GitNarrator" in VS Code Extensions, or:
code --install-extension YOUR_PUBLISHER.gitnarrator
Architecture decisions
child_process over VS Code Git API — VS Code's internal Git API is undocumented and unstable across versions. Direct execFile('git', [...]) calls give precise control, are testable without VS Code running, and work reliably across all platforms.
Structured log extraction, not raw diffs — Sending full git diffs to Claude would burn tokens and hit context limits on any non-trivial repo. diffAnalyzer.ts extracts signals (files changed, insertion/deletion counts, most-changed files) and sends structured metadata instead.
Streaming responses — Narratives take 3-8 seconds to generate. Showing the response word-by-word (via client.messages.stream()) makes the wait feel purposeful rather than broken.
VS Code SecretStorage for API keys — Never settings.json (which syncs to cloud and shows in plaintext). SecretStorage is OS keychain-backed, encrypted at rest.
Cache by HEAD hash — The narrative for the same commit history doesn't change. Results are cached in globalState keyed by HEAD hash + time period, invalidated after 1 hour or when HEAD changes.
What I used AI for
- Claude (this session) designed the architecture, wrote all source files, and wrote this README
- All prompt engineering in
src/claude/prompts.ts was written by hand and iterated manually — this is the core IP
- The git signal extraction logic in
diffAnalyzer.ts was written by hand — AI-generated versions were too naive about what "meaningful change" means
- Webview HTML/CSS was AI-generated but the streaming message protocol was designed manually
What I would change with 4 more weeks
- Branch comparison — "What changed between
main and this feature branch?" is the PR reviewer's core question. Currently only supports time-based and commit-range queries.
- Team insights — Surface patterns like "Alice owns auth/, Bob owns the API layer" from commit authorship. Useful for new developers understanding ownership.
- Scheduled digests — Weekly email/Slack summary of what happened in a repo, auto-sent every Monday morning. Solves the problem passively.
- Multi-repo workspace — Monorepos or projects with multiple repos need cross-repo narrative: "what shipped across all services this sprint?"
- Local model support — Support Ollama as a free alternative for users who can't use the Anthropic API (privacy, cost).
GitNarrator
