# g4a - the reasoning layer for AI-written code Git stores what changed. The reasoning behind it is lost. g4a captures it. Add it to your existing project. Change nothing about your workflow. Unlock 10x for both humans and AI agents. --- ## The problem Every AI coding agent thinks before it writes. Claude Code reads 20 files, considers 3 approaches, rejects 2, tests edge cases, and picks the best path. Cursor explores your codebase, reasons about patterns, and adapts. Codex plans multi-file changes before executing them. Then at commit time, all of that thinking is thrown away. This happens with every agent, every commit, every tool. The reasoning is generated, used once, and discarded. The most valuable artifact of the development process - the WHY behind every decision - is lost forever. ## What this causes **PR review time increased 91%.** Teams using AI merge 98% more PRs that are 154% larger, but review time increased 91%. Reviewers stare at diffs and reverse-engineer intent. (Source: Faros AI, 10,000+ devs across 1,255 teams) **46% of developers actively distrust AI-written code.** Not because the code is bad - because they can't see the reasoning. Only 3% highly trust it. (Source: Stack Overflow 2025 Survey, 49,000+ respondents) **66% waste time on "almost right" AI code.** The biggest frustration: AI solutions that are close but not quite. Debugging AI-generated code is more time-consuming than writing it yourself - because the reasoning behind it is invisible. (Source: Stack Overflow 2025 Survey) **Debugging is terrifying.** When agent code breaks in production, there's no trail. The agent is gone. Its reasoning is gone. You're reverse-engineering intent from diffs while the clock is ticking. **Teams don't benefit.** 70% say agents boost personal productivity, only 17% say they help team collaboration. Reasoning lives in private sessions and dies there. (Source: Stack Overflow 2025 Survey, AI Agents section) Salesforce already rebuilt their review infrastructure because "traditional pull request review assumes reviewers can reconstruct intent by scanning diffs sequentially" - and that assumption broke under AI code volume. Code grew 30%, PRs expanded beyond 20 files and 1,000+ lines, and review latency rose quarter over quarter. g4a makes that intent-reconstruction capability available to every team. (Source: Salesforce Engineering Blog, January 2026 - https://engineering.salesforce.com/scaling-code-reviews-adapting-to-a-surge-in-ai-generated-code/) **AI agents start from zero, every time.** Every agent re-discovers the same things. Every rejected alternative is re-explored. Every deliberate tradeoff is invisible. The codebase has no memory of the decisions that shaped it. --- ## Real example: the payment refactor An agent refactors payment processing. The commit says: "refactor: Update payment calculation to use Decimal." 8 files changed across checkout, billing, refunds, and settlement. WITHOUT g4a: The reviewer spends 25 minutes reading 8 diffs, can't tell why the change was made, approves because tests pass. Three weeks later, the nightly settlement job is off by $0.03 on 10,000 transactions. $300 missing. Finance escalates. Someone runs git blame, finds the commit, reads "Update payment calculation to use Decimal," and has nothing else to go on. WITH g4a: The reasoning record shows the agent switched from float to Decimal because batch settlements accumulate floating-point errors ($0.03 drift after 10,000 test transactions). It explored 3 alternatives: (1) keep float + round at end (rejected - error accumulates), (2) integer cents (rejected - would touch 23 files), (3) Decimal everywhere (chosen). It flagged LOW confidence on the settlement job's CSV export formatting. The reviewer reads this in 3 minutes, checks the one flagged line, fixes it, approves. The settlement works perfectly. The reasoning is in the repo forever. --- ## How g4a helps humans **PR reviews go from guessing to reading.** Instead of reverse-engineering intent from diffs, reviewers read the agent's actual reasoning: intent, confidence, alternatives, what was tested, what was flagged as risky. A 25-minute review becomes 3 minutes with higher confidence. **Debugging has a trail.** When something breaks, g4a why gives you the complete decision history. Every change, every agent, what they intended, what they were worried about. **Trust is earned, not assumed.** Every AI-generated change carries a confidence score and full explanation. Low-confidence changes get scrutiny. High-confidence changes flow faster. **Onboarding is instant.** New developers run g4a why and read the decision history instead of spending weeks guessing from diffs. ## How g4a helps AI agents **Agents understand past decisions.** A new agent reads .g4a/ and immediately knows why code looks the way it does. It doesn't re-explore. It doesn't accidentally revert a deliberate choice. **Agents stop duplicating work.** Agent B reads Agent A's exploration trail and starts from where Agent A left off instead of re-discovering the same things. **Agents coordinate through shared context.** When multiple agents work on the same codebase, they read each other's reasoning and avoid conflicts. **Your codebase gets smarter over time.** The .g4a/ directory is institutional memory. Every decision, every rejected alternative, every risk assessment - accumulated over months. The longer g4a runs, the more context every future agent has. --- ## The solution g4a captures the reasoning that AI agents already produce and stores it alongside the code in git. 1. pip install g4a (or brew install lcbasu/g4a/g4a), then g4a init 2. Use your AI coding agent normally - nothing changes 3. g4a silently captures reasoning in the background 4. Reasoning stored in .g4a/ inside your repo 5. Push to GitHub/GitLab/Bitbucket - reasoning travels with the code Commands: - g4a log: recent commits with reasoning - g4a why : decision trail for any function - g4a show HEAD: diff + reasoning side by side - g4a web: visual report in browser ## Designed for all AI coding agents **Claude Code (launching first):** Direct transcript parsing. No API call needed. **Cursor, Codex, Copilot, Windsurf, Aider:** Git hook fallback, infers reasoning from diffs. **Custom agents:** Agent-agnostic schema. Any tool that commits through git works. ## Storage - .g4a/ directory inside your repo. No server. No account. - One file per commit, one file per session. CBOR (IETF RFC 8949) + zstd compression. An internet standard, not a proprietary format. - Secret masking before any data hits disk. Irreversible. - 10-50 KB per commit. 1,000 commits = 10-50 MB. - Self-describing JSON Schema for future compatibility. --- Website: https://www.git4aiagents.com/ GitHub: https://github.com/lcbasu/git4aiagents Author: Lokesh Basu (@lcbasu) License: CC-BY-4.0