git-narrate (CLI: narrate)

AI-Assisted Conventional Commits & Architectural PR Narrative Generator
Alternative names: loregit | agentscribe | commit-story

git-narrate is a high-performance, zero-dependency Go CLI tool designed to bridge the gap between AI coding agent transcripts (such as Claude Code and OpenClaw) and Git diffs. It extracts the architectural intent and rationale ("why" a change was made) from agent logs and correlates them with actual modified files to produce structured Conventional Commits and complete PR descriptions.

---

⚡ Quick Demo & Workflow

┌───────────────────────────┐      ┌───────────────────────────┐
│ AI Agent Transcript Logs  │      │   Git Working Directory   │
│  (Claude Code / OpenClaw) │      │  (staged / unstaged diff) │
└─────────────┬─────────────┘      └─────────────┬─────────────┘
              │                                  │
              ▼                                  ▼
      ┌───────────────┐                  ┌───────────────┐
      │  narrate      │                  │  git diff     │
      │  ingest       │                  │  parser       │
      └───────┬───────┘                  └───────┬───────┘
              │                                  │
              └────────────────┬─────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │    pkg/analyzer     │
                    │ (Correlation Engine)│
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │  narrate rebase &   │
                    │  narrate pr-body    │
                    └─────────────────────┘

---

🚀 Features

• Zero External CGO Dependencies: Built with pure Go (Go 1.22+) using standard libraries.
• Lightning Fast: Executes correlation engine and formatting in under 50ms.
• Multi-Agent Transcript Support: Auto-detects Claude Code (.json/.jsonl) and OpenClaw execution logs.
• Intent Matrix Extraction: Pairs user prompts, reasoning blocks, and tool executions directly with Git hunks.
• Conventional Commit Generator: Outputs type(scope): message with detailed Why: rationales and file statistics.
• Automated PR Descriptions: Generates Markdown PR descriptions featuring ## Summary, ## Intent & Architectural Choices, ## Files Modified, and ## Test Status.

---

📦 Installation & Quickstart

Method 1: 1-Line go install (Recommended)

Requires Go 1.22+:

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

Method 2: Download Pre-compiled Standalone Binaries (No Go Required)

Download pre-built binaries for your platform directly from GitHub Releases:

• 🐧 Linux: narrate-linux-amd64, narrate-linux-arm64
• 🍎 macOS: narrate-darwin-amd64, narrate-darwin-arm64 (Apple Silicon M1/M2/M3)
• 🪟 Windows: narrate-windows-amd64.exe

Method 3: Build from source

git clone https://github.com/arsyadal/git-narrate.git
cd git-narrate
go build -o narrate ./cmd/narrate

---

📁 Project Structure

git-narrate/
├── .github/
│   └── workflows/
│       ├── ci.yml               # Automated CI matrix tests (Linux, macOS, Windows)
│       └── release.yml          # Automated binary cross-compilation & GitHub Release
├── cmd/
│   └── narrate/
│       └── main.go              # CLI Entrypoint & Subcommand routing
├── docs/
│   ├── ARTICLE_DEVTO_MEDIUM.md  # Technical article draft for Dev.to / Medium / Hashnode
│   ├── AWESOME_LISTS_SUBMISSION.md # Submission templates for Awesome-Go & Awesome-Git
│   └── demo.tape                # VHS script to record CLI terminal GIF
├── pkg/
│   ├── config/
│   │   └── config.go            # CLI Configuration & ENV loader
│   ├── parser/
│   │   ├── parser.go            # Interface & Auto-detector router
│   │   ├── claudecode.go        # Claude Code transcript parser (.json/.jsonl)
│   │   └── openclaw.go          # OpenClaw log parser
│   ├── git/
│   │   └── git.go               # Pure Go exec wrapper for Git commands (diff, status, commit)
│   ├── analyzer/
│   │   ├── models.go            # Internal AST & Log Event Data Models
│   │   └── engine.go            # Correlation engine (matches diffs with agent prompts)
│   └── formatter/
│       ├── commit.go            # Conventional Commit message formatter
│       └── pr.go                # Markdown PR description renderer
├── go.mod
└── README.md

---

🛠️ Usage & Commands

1. narrate ingest

Processes an AI agent transcript log file, extracts the intent matrix, and caches session metadata to .git/narrate_session.json.

narrate ingest --log=path/to/claude_transcript.jsonl

2. narrate rebase

Correlates Git diffs with the ingested transcript (or log passed via --log) and generates Conventional Commit groups.

# Rebase using uncommitted working tree diffs
narrate rebase

# Rebase using staged diffs only
narrate rebase --staged

# Rebase using a specific Git commit range
narrate rebase --commit-range=HEAD~3..HEAD

# Automatically perform git commit for each generated story group
narrate rebase --staged --commit

3. narrate pr-body

Generates a complete, markdown-formatted Pull Request description.

# Output PR description to stdout
narrate pr-body

# Save PR description to a Markdown file
narrate pr-body --out=PR.md

---

📊 Conventional Commit Output Example

=== Commit #1 ===
feat(auth): add JWT authentication middleware

Why: Implement user authentication token verification in HTTP requests to secure API endpoints

Modified files:
- pkg/auth/auth.go (A, +35/-0)
- pkg/auth/auth_test.go (A, +20/-0)

---

📄 PR Description Markdown Output Example

# 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 |

**Total Stats**: 1 files changed, +35 additions, -0 deletions.

## Test Status

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

---

🧪 Testing

Run all unit tests across the codebase:

go test -v ./...

---

📜 License

MIT License