How We Correlated LLM Tool Calls with Git Diff Hunks to Automate PR Narratives

arsyadal — Wed, 05 Aug 2026 14:38:04 +0000

TL;DR: AI coding agents like Claude Code and OpenClaw generate tons of code edits, but their commit history and PR descriptions are often messy or lack architectural rationale. We built git-narrate (narrate) in pure Go to correlate agent transcripts directly with Git diffs in < 50ms, producing clean Conventional Commits and intent-aware PR descriptions automatically.

The Problem: AI Code Agents are Fast, But Git History Suffers

As developer workflows shift toward agentic coding tools—such as Claude Code, Cursor, Aider, and OpenClaw—the volume of code written per session has skyrocketed. Agents execute multiple file edits, create new modules, refactor functions, and run terminal commands within a single session.

However, when it comes time to commit and create a Pull Request, developers face two major friction points:

Vague or Blob Commit Messages: Commits like "AI generated code" or "updated files" obscure why a particular architectural decision was made.
Time-Consuming PR Descriptions: Reviewers need to understand the intent behind code edits. Manually summarizing 10+ modified files from memory or skimming agent logs takes significant effort.

We asked: What if your CLI could parse the AI agent's internal transcript log, extract the developer's original prompt and reasoning, and automatically match every modified file hunk with its architectural intent?

Enter git-narrate.

Arsitektur & How `git-narrate` Works Under the Hood

git-narrate is written in Go 1.22+ with zero external CGO dependencies. It operates in three main stages:

┌───────────────────────────┐      ┌───────────────────────────┐
│ AI Agent Transcript Logs  │      │   Git Working Directory   │
│  (Claude Code / OpenClaw) │      │  (staged / unstaged diff) │
└─────────────┬─────────────┘      └─────────────┬─────────────┘
              │                                  │
              ▼                                  ▼
      ┌───────────────┐                  ┌───────────────┐
      │  pkg/parser   │                  │    pkg/git    │
      └───────┬───────┘                  └───────┬───────┘
              │                                  │
              └────────────────┬─────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │    pkg/analyzer     │
                    │ (Correlation Engine)│
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │    pkg/formatter    │
                    │  (Commit & PR Body) │
                    └─────────────────────┘

Stage 1: Abstracting Transcripts (`pkg/parser`)

AI agent transcripts come in various formats:

Claude Code: Multi-line .jsonl or single .json exports containing USER_INPUT, PLANNER_RESPONSE, and tool_calls (write_file, FileEdit, replace_file_content).
OpenClaw: Text log format featuring [PROMPT], [TOOL], and [REASONING] line tags.

Our parser auto-detects the format and converts it into a unified internal Event AST:

type AgentEvent struct {
    Timestamp   time.Time      `json:"timestamp"`
    Kind        AgentEventKind `json:"kind"` // user_prompt, tool_call, reasoning
    Content     string         `json:"content"`
    ToolName    string         `json:"tool_name,omitempty"`
    TargetFiles []string       `json:"target_files,omitempty"`
}

Stage 2: Hunk-Level Diff Parsing (`pkg/git`)

Instead of depending on libgit2 or CGO bindings, git-narrate wraps standard os/exec commands to execute git diff --no-color.

It parses unified diff headers (diff --git a/file b/file), calculates added/deleted line counts per file hunk, and determines file status (M for modified, A for added, D for deleted, R for renamed).

Stage 3: The Correlation Engine (`pkg/analyzer`)

The core innovation of git-narrate is its Intent Matrix Correlation:

Path Normalization: Both agent target paths (e.g. pkg/auth/auth.go) and Git diff paths are normalized.
Rationale Mapping: For every modified file in the diff, the correlation engine searches back through preceding AgentEvents in the transcript to find the exact user prompt or agent reasoning that triggered that change.
Conventional Scope & Type Inference:
- _test.go or test/ → type: test
- .md or docs/ → type: docs
- File directory structure (cmd/narrate, pkg/auth) → scope: narrate, scope: auth
- Keyword heuristics (fix, refactor, add) → type: fix / refactor / feat

Benchmark & Performance

Because git-narrate relies strictly on standard Go data structures and light text scanning, execution speed is exceptionally fast:

Operation	Average Execution Time
`narrate ingest` (1MB JSONL transcript)	~18ms
`narrate rebase` (Git diff correlation)	~24ms
`narrate pr-body` (Markdown rendering)	~12ms

Total runtime is consistently under 50ms, making it invisible in developer terminal workflows or pre-commit hooks.

How to Use `git-narrate` Today

1. Installation

go install github.com/arsyadal/git-narrate/cmd/narrate@latest

(Or download pre-compiled binaries for Linux, macOS, or Windows directly from GitHub Releases).

2. Ingesting Agent Log & Rebasing Commits

# Step 1: Ingest agent transcript log
narrate ingest --log=session_transcript.jsonl

# Step 2: Preview Conventional Commit story
narrate rebase --staged

# Step 3: Automatically commit grouped changes
narrate rebase --staged --commit

3. Generating a Markdown PR Description

narrate pr-body --out=PR.md

Outputs a clean, structured PR description ready for GitHub/GitLab:

# Pull Request Description

## Summary
Implement user authentication and JWT validation middleware for API routing.

## Intent & Architectural Choices
### `feat(auth)`: add JWT authentication middleware
- **Intent**: Implement user authentication token verification in HTTP requests to secure API endpoints
- **Impacted Scope**: `auth`

## Files Modified
| File | Status | Added | Deleted | Rationale |
| --- | --- | --- | --- | --- |
| `pkg/auth/auth.go` | `A` | +35 | -0 | Implement user authentication token parser |

## Test Status
- [x] Unit tests updated / added.
- [x] Automated test suite executed cleanly.

Conclusion & Open Source Community

git-narrate brings clarity and architectural maintainability back to Git repositories in the age of AI agent coding.

We would love your feedback, contributions, and ideas!

⭐️ Star the GitHub Repo: https://github.com/arsyadal/git-narrate
💬 Open an Issue / PR: Feature requests for new AI agent log formats are welcome!

DEV Community: arsyadal