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
.jsonlor single.jsonexports containingUSER_INPUT,PLANNER_RESPONSE, andtool_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.goortest/→type: test -
.mdordocs/→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!
Top comments (0)