git-diff-llm-context

Vibe Coders' Companion: Get git diffs with surrounding source context, file location links, and clean markdown formatting ready to pipe directly into LLMs (like Claude, ChatGPT, or Cursor).

A zero-dependency Node.js library and CLI utility that parses Git diffs and compiles them into a structured, token-optimized Markdown context for LLM prompt ingestion, complete with surrounding lines of code.

⚡ Features

• Zero Runtime Dependencies: Ultra lightweight and fast.
• Surrounding Context Lines: Extracted directly from local files to give the LLM full visibility of adjacent helper functions and variable definitions.
• File URI Links: Formats files with clickable local file:// links for direct IDE navigation.
• New & Deleted File Summaries: Cleanly formats newly added code and warns about deleted files.
• Command-Line & Programmatic APIs: Run it from scripts, terminal pipes, or integrate it into prompt compilers.

📦 Installation

npm install git-diff-llm-context

🚀 Usage

1. CLI Usage

Run the utility to print the compiled markdown context to standard output. You can pipe this directly to LLM command-line tools:

# Get staged and unstaged changes compiled with 5 lines of context
npx git-diff-llm-context

# Specifying a git diff target (e.g. staged changes only)
npx git-diff-llm-context --cached

# Get changes compared to main branch with 10 context lines
npx git-diff-llm-context main -c 10

# Save output to a markdown file
npx git-diff-llm-context -o prompt-context.md

2. Programmatic API

You can import the compiler in your scripts or prompt pipelines:

import { compileDiffContext } from 'git-diff-llm-context';

const result = await compileDiffContext({
  target: '--cached',  // Staged changes only (optional)
  contextLines: 8,      // Surrounding lines to show (default: 5)
  cwd: process.cwd()    // Directory path (optional)
});

console.log(result.markdown);
/*
# Git Diff Context Report

## Changed Files:
- [src/index.ts](file:///Users/username/project/src/index.ts) (Modified)

---

### File: `src/index.ts`
Status: Modified

```diff
  export function runTask(task: Task) {
    console.log("Starting task...");
-   const status = task.execute();
+   const status = await task.execute();
    return status;
  }

*/

---

## ⚙️ CLI Options

```text
Usage: git-diff-llm-context [target] [options]

Arguments:
  target                Git diff target (e.g., --cached, HEAD~1, main...feature)

Options:
  -c, --context <num>   Number of context lines to display (default: 5)
  -o, --output <file>   Save Markdown report to a specific file
  -h, --help            Show help info

📄 License

MIT License.