[PR #566] feat(synopsis): add AI-generated commit narrative synopses #572

New issue

Open

opened 2026-03-02 04:14:01 +03:00 by kerem · 0 comments

kerem commented

2026-03-02 04:14:01 +03:00

Owner

Original Pull Request: https://github.com/git-ai-project/git-ai/pull/566

State: open
Merged: No

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

**Original Pull Request:** https://github.com/git-ai-project/git-ai/pull/566 **State:** open **Merged:** No --- ## 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 ```sh # 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 - [x] 14 unit tests pass (`cargo test --lib synopsis`) - [x] 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](https://claude.com/claude-code)  --- <a href="https://app.devin.ai/review/git-ai-project/git-ai/pull/566" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1"> <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open with Devin"> </picture> </a>