feat(synopsis): add AI-generated commit narrative synopses

[jwiegley]

Summary

• Adds a new git ai synopsis command that generates blog-article-style narrative descriptions of commits, capturing the full story behind a change — not just the diff, but the thinking and exploration that led to it
• Collects three input sources: the Claude Code AI conversation (auto-detected from ~/.claude/projects/), the commit diff, and the commit message, then sends them to the Anthropic Claude API
• Stores synopses as git notes under refs/notes/ai-synopsis, which can be pushed/pulled alongside the repository

Motivation

Traditional commits record what changed. When working with AI assistants, there's rich context — dead ends explored, tradeoffs weighed, approaches debated — that gets lost at commit time. This feature captures that context as a readable narrative for future readers of the code.

New Commands

# Generate a synopsis for the most recent commit
git ai synopsis generate

# Generate for a specific commit, with explicit API key
git ai synopsis generate --commit abc1234 --api-key $KEY

# Generate without conversation context; target shorter output
git ai synopsis generate --no-conversation --length brief

# Preview the prompt that would be sent (no API call)
git ai synopsis generate --dry-run

# Read back a stored synopsis
git ai synopsis show HEAD
git ai synopsis show abc1234

# List all commits with synopses
git ai synopsis list

Implementation Details

Module layout (src/synopsis/):

File	Responsibility
types.rs	Core structs: Synopsis, SynopsisMetadata, ConversationLog, DiffBundle, SynopsisInput
config.rs	SynopsisConfig with defaults from env vars
conversation.rs	Claude Code JSONL parser; project-hash derivation; time-window filter
collector.rs	Assembles all three input sources; conversation loading is non-fatal
generator.rs	Builds the structured prompt; calls Anthropic Messages API via minreq
storage.rs	Reads/writes git notes under refs/notes/ai-synopsis
commands.rs	generate, show, list CLI subcommands

Conversation auto-detection: Claude Code stores sessions as JSONL files under ~/.claude/projects/<project-hash>/. The hash is derived by replacing / path separators with - and stripping the leading -. The most recently modified .jsonl file in that directory is used and filtered to exchanges within the configurable time window (default: 60 min before the last exchange).

API call: Uses minreq (already a project dependency) to POST to https://api.anthropic.com/v1/messages. Requires ANTHROPIC_API_KEY (or --api-key). Model defaults to claude-opus-4-6, overridable via GIT_AI_SYNOPSIS_MODEL or --model.

Storage: Synopsis JSON (metadata + markdown content) is stored as a git note via git notes --ref=ai-synopsis add -f -F -, using the same stdin-piped pattern as the existing authorship tracking system.

Test Plan

• 14 unit tests pass (cargo test --lib synopsis)
• Project builds cleanly with no errors (cargo build)
• Manual: git ai synopsis generate on a real repo with Claude Code session
• Manual: git ai synopsis show HEAD reads back the stored note
• Manual: git ai synopsis generate --dry-run shows prompt without API call
• Manual: git ai synopsis generate --no-conversation works without a JSONL file present

🤖 Generated with Claude Code

---

[git-ai-cloud-dev]

Stats powered by Git AI

🧠 you    █░░░░░░░░░░░░░░░░░░░  6%
🤖 ai     ░███████████████████  94%

More stats

• 0.0 lines generated for every 1 accepted
• 0 seconds waiting for AI
• Top model: claude:: (182 accepted lines, 0 generated lines)

AI code tracked with git-ai

[git-ai-cloud]

Stats powered by Git AI

🧠 you    █░░░░░░░░░░░░░░░░░░░  6%
🤖 ai     ░███████████████████  94%

More stats

• 0.0 lines generated for every 1 accepted
• 0 seconds waiting for AI
• Top model: claude:: (182 accepted lines, 0 generated lines)

AI code tracked with git-ai

[devin-ai-integration]

Devin Review found 1 potential issue.

View 6 additional findings in Devin Review.

[devin-ai-integration]

🔴 Byte-index slicing of String panics on multi-byte UTF-8 characters

In render_conversation, the expression &line[..remaining] at line 269 performs byte-index slicing on a String. If remaining falls in the middle of a multi-byte UTF-8 character (e.g., emoji, CJK characters, accented letters in conversation text), Rust will panic at runtime with byte index N is not a char boundary.

Root Cause and Impact

The line variable is built from user conversation text via format!("{}{}", prefix, exchange.text.trim()). Conversation logs from Claude Code sessions can easily contain non-ASCII characters (code comments in other languages, emoji, special symbols, etc.).

The remaining value is computed from max_chars.saturating_sub(out.len()), where both max_chars and out.len() are byte counts. However, when used as &line[..remaining], this byte offset may land inside a byte sequence of a multi-byte character in line, causing a panic.

For example, if line contains "**User**: café\n\n" and remaining is 14, the slice &line[..14] would cut into the middle of the é character (which is 2 bytes in UTF-8), causing a runtime panic.

Impact: Any synopsis generation that involves conversation text with multi-byte UTF-8 characters and hits the truncation path will crash the process.

Suggested change

	out.push_str(&line[..remaining]);
	let safe_remaining = line.floor_char_boundary(remaining);
	out.push_str(&line[..safe_remaining]);

---

Was this helpful? React with 👍 or 👎 to provide feedback.