Inspiration
Every software engineering team has experienced the silent panic of a broken production release.
Under release deadlines, code reviews often reduce to skimming green and red lines in a pull request. Even experienced engineers miss subtle breaking changes: a renamed optional argument, an updated error-handling contract, or a modified exception class. Compounding the problem, compiling changelogs and release notes is a tedious manual chore that developers routinely postpone.
We asked ourselves:
What if an AI could act as a 24/7 principal architect during code reviews—instantly calculating the blast radius, radar-flagging breaking changes before they hit production, and writing the release notes for you?
This question inspired GitTogether: an intelligent visual diff and breaking-change detection engine designed to give developers total confidence before merging.
What it does
GitTogether transforms raw git diffs, commits, and GitHub PRs into actionable architectural intelligence in seconds:
Client-Side Unified & Word-Level Diffing: Computes unified line-by-line diffs with intra-line character-level highlights entirely in the browser without server round-trip latency.
Universal GitHub Ingestion: Accepts public GitHub repository URLs (https://github.com/:owner/:repo), Pull Requests (/pull/:number), or commit hashes (/commit/:sha), dynamically chunking multi-file changes into interactive chips with additions/deletions telemetry.
Real-Time Streaming Reasoning (SSE): Streams AI evaluation chunk-by-chunk using Server-Sent Events, letting users observe the model's analytical deduction in real-time.
Architectural Blast Radius Assessment: Explains in plain English how the change impacts module isolation, data flow, external dependencies, and runtime performance.
Breaking Change Radar: Categorizes contract breaks with severity classification: $$\text{Severity} \in {\text{High}, \text{Medium}, \text{Low}}$$ highlighting exact affected callers, thrown exceptions, and required migration steps.
Automated SemVer Recommendation: Analyzes breaking change severity $\mathcal{S}$ to determine the semantic version bump $\Delta V$: $$\Delta V = \begin{cases} \text{\textbf{Major}} & \text{if } \exists , s \in \text{BreakingChanges} \text{ where } s.\text{severity} = \text{High} \ \text{\textbf{Minor}} & \text{if } |\text{BreakingChanges}| > 0 \text{ or new backward-compatible capabilities exist} \ \text{\textbf{Patch}} & \text{otherwise (bug fixes and optimizations)} \end{cases}$$ One-Click Markdown Release Notes: Generates GitHub-flavored release notes cleanly partitioned into Added, Changed, Fixed, and Breaking Changes, with one-click clipboard copying.
How we built it
In accordance with the Devpost: Build With AI Basics Hackathon standards, GitTogether was constructed using Spec-Driven AI Development:
AI Planning Artifacts: We started by codifying the system boundaries in
scope.md , defining functional acceptance criteria and demo scripts in
prd.md , and standardizing API contracts and data models in
spec.md . Zero-Dependency Architecture: The backend runs on native Node.js 18+ with zero external npm dependencies. By relying exclusively on native http, fetch, and streaming primitives, the repository has zero security vulnerabilities, requires no npm install, and deploys instantly anywhere. Client-Side Diff Engine: Unified line matching and intra-line word diffing are computed with an optimized Longest Common Subsequence (LCS) algorithm running in $\mathcal{O}(N \cdot M)$ time directly in JavaScript. Server-Sent Events (SSE) Pipeline: /api/analyze initiates an SSE stream (Content-Type: text/event-stream), piping token deltas from Claude 3.5 Sonnet directly to the frontend's visual inspector. Zero-Config Demo Mode: For judges and reviewers without an API key, GitTogether includes a local pre-computed streaming engine simulating realistic real-time reasoning across three production scenarios.
Challenges we ran into
Unauthenticated GitHub Rate Limiting: Public requests to GitHub's REST API are capped at 60 requests/hour per IP. When users imported repositories or commits, API rate limits could block ingestion. We engineered a resilient multi-tier fallback: querying the REST API first, then scraping commit hashes from unauthenticated commit Atom/RSS feeds, and directly streaming the .diff endpoint. Intra-Line Word-Level Diffing in Vanilla JS: Highlighting character modifications without heavy third-party libraries (like diff2html or highlight.js) required writing a custom word tokenizer and diff reconciliation engine that preserves whitespace, punctuation, and syntax highlighting tokens simultaneously. Parsing Structured JSON from Streaming LLMs: Streaming tokens in real time while concurrently generating valid JSON creates a tension: JSON cannot be parsed until the final token arrives. We resolved this by streaming partial raw text into a live terminal inspector, and progressively extracting and validating the final normalized JSON payload upon the [DONE] event.
Accomplishments that we're proud of
⚡ 100% Zero-Dependency Architecture: We built the entire application using native Node.js 18+ HTTP/stream primitives and vanilla browser APIs. There is no node_modules directory, zero npm dependencies to install, zero supply-chain security vulnerabilities, and lightning-fast sub-second cold starts. Anyone can clone the repo and run it instantly with just node server.js.
🎯 Built a Pure Vanilla JS Word-Level Diffing Engine: Instead of importing heavy external diff libraries (like diff2html or jsdiff), we engineered a lightweight client-side diff algorithm from scratch. It calculates line-by-line unified diffs with intra-line character and word-level highlighting, executing in real-time right in the browser with zero server round trips.
🛡️ Bulletproof GitHub Ingestion with Multi-Tier Fallbacks: Public GitHub REST APIs enforce strict rate limits (60 calls/hr). We created an autonomous multi-tier fallback pipeline: if the GitHub REST API encounters rate limiting, GitTogether automatically falls back to scraping commit feeds and streaming GitHub’s .diff endpoints directly. It seamlessly handles whole repositories (.git), pull requests, and commit hashes alike.
🌊 Live SSE Token Streaming with Zero Latency: Rather than making users wait 10–15 seconds behind an opaque loading spinner, we implemented an authentic Server-Sent Events (SSE) streaming inspector. Users watch Claude 3.5 Sonnet reason through the code changes chunk-by-chunk in real time.
🧠 Accurate Contract Break Radar & SemVer Automation: Our prompt engineering and normalization pipeline reliably identifies breaking changes across multiple severity levels (e.g., catching positional parameter breaks and new thrown exceptions), automatically deriving the correct SemVer version bump (Major, Minor, or Patch) to prevent accidental breaking releases.
🎮 Zero-Config Demo Mode for Frictionless Judging: We designed an out-of-the-box Demo Mode featuring three real-world pre-computed scenarios (Breaking API Refactor, Redis Caching, and Security Patch) with simulated progressive streaming, allowing hackathon judges and community reviewers to evaluate the full end-to-end experience without needing an Anthropic API key or credit card.
📐 Practicing True Spec-Driven Development: We strictly adhered to the AI planning methodology, starting with
scope.md ,
prd.md , and
spec.md before writing code. This disciplined approach kept us laser-focused on core value, prevented scope creep, and enabled rapid, error-free iteration.
What we learned
Spec-Driven AI Works: Spending the first phase drafting scope.md, prd.md, and spec.md eliminated 90% of architectural ambiguity and prevented scope creep during development. Zero-Dependency Power: Modern Node.js provides first-class fetch, URL parsing, and streams. Dispensing with npm bloat makes projects blazing fast, ultra-secure, and effortless to run with a single command: node server.js. The Value of Blast-Radius Telemetry: Presenting diffs alongside semantic architectural impacts transforms code review from a line-checking chore into an executive design review.
What's next for GitTogether — AI Visual Diff & Architectural Intelligence
GitHub Action & PR Bot: Automatically analyze every incoming PR and post the Breaking Change Radar and SemVer recommendation as an automated review comment. TypeScript AST Contract Analysis: Integrating AST-level type diffing to automatically verify interface compatibility across TypeScript packages. Slack & Discord Webhook Alerts: Pushing high-severity release blocker notifications to team channels whenever a breaking change is merged into main.
Log in or sign up for Devpost to join the conversation.