Open source · CC-BY-4.0

The reasoning layer
for AI-written code

Git stores what changed. The reasoning behind it is lost.
g4a captures it. No server, no database, everything in git.

Faster PR reviews Fearless debugging Earned trust
1
$ brew install lcbasu/g4a/g4a
One time, global install
2
$ cd your-project && g4a init
Run in each repo. Commit the .g4a folder to git.

That's it. Use your AI agent normally. Reasoning is captured on every commit.

The difference

git log vs g4a log

Same commit. One tells you what changed. The other tells you why.

$ git log --oneline
a1b2c3d refactor: Update payment to use Decimal
e4f5g6h fix: Handle null user in auth middleware
i7j8k9l feat: Add billing dashboard

That's it. No reasoning. No context.
Why Decimal? Why not integer cents?
What was tried and rejected?
What risks were flagged?
$ g4a log
a1b2c3d claude-code (120 events)
refactor: Update payment to use Decimal
User
"Refactor payments to use Decimal"
Intent
Float arithmetic drifts $0.03 after 10K batch transactions. Decimal is exact.
Dead end
Tried integer cents first - tests failed, APIs expect decimal format (23 files).
Risk flagged
CSV export line 47 may truncate Decimal [confidence: 0.6]
Chain
Read 6 files > tried int cents > test fail > pivot to Decimal > 8 files edited > tests pass
How to use

Any developer. Any system. Anytime.

Pull the latest commits and you have the full reasoning history. No setup beyond git. Works through GitHub, GitLab, Bitbucket, or any internal git host.

$

g4a log

Full reasoning chain for every commit. Every file read, every approach tried, every dead end, every decision. The complete story behind the code.

?

g4a why "auth"

Search the decision trail by file, function, or keyword. Find why any decision was made, across any commit, by any agent.

>

g4a log --short

Compact summary when you just need the highlights. What changed, what the agent intended, which files were touched.

AI

Future AI agents read it too

Any agent reads the reasoning before modifying shared code. No re-exploration. No accidentally reverting deliberate choices. The codebase compounds intelligence.

Why it matters

Faster reviews. Fearless debugging. Earned trust.

When the reasoning is visible, everything changes - for humans reviewing AI code and for AI agents building on each other's work.

PR

PR reviews: 25 min to 3 min

Instead of reading 8 diffs and guessing why the auth middleware order changed, reviewers read the agent's actual reasoning: what it intended, what alternatives it rejected, and what it flagged as risky. Low-confidence changes get scrutiny. High-confidence changes flow faster.

DB

Debugging has a trail

When agent code breaks in production, there is no trail. The agent is gone. With g4a, g4a why settlement_job gives you every change, every agent's intent, every dead end it explored, every risk it flagged. No more reverse-engineering meaning from diffs at 2am.

HU

Humans trust what they can see

46% of developers distrust AI code - not because it is bad, but because the reasoning is invisible. g4a makes every AI change carry a confidence score, full explanation, and list of alternatives considered. Trust becomes data-driven, not gut-feel.

AI

AI agents trust each other's work

Agent B reads Agent A's reasoning and immediately knows: this was changed to Decimal because of precision drift. Integer cents was rejected because it would touch 23 files. No re-exploration. No accidentally reverting a deliberate choice. Agents build on documented decisions instead of guessing.

ON

Onboarding in minutes, not weeks

New developer joins the team. Instead of spending weeks figuring out why the codebase looks this way, they run g4a why auth and read the decision history. "Why is this Decimal and not float?" - there is an answer. The codebase documents itself.

TM

Team knowledge stops dying

70% individual productivity gain, only 17% team gain. The gap exists because reasoning lives in private sessions and dies there. g4a makes every agent's exploration, every rejected alternative, every architectural decision visible to the entire team - forever.

The problem

Every AI agent thinks before it writes.
Then throws the thinking away.

91%

PR review time increased

Teams merge 98% more PRs that are 154% larger, but review time grew 91%. Reviewers reverse-engineer intent from diffs.

Faros AI - 10,000+ devs
46%

Actively distrust AI code

Not because the code is bad - because they can't see the reasoning. Only 3% highly trust it.

Stack Overflow 2025 - 49K devs
66%

Waste time on "almost right" code

Debugging AI code is harder than writing it yourself - because the reasoning behind it is invisible.

Stack Overflow 2025
4x

Individual vs team gap

70% say AI boosts personal productivity. Only 17% say it helps team collaboration. Reasoning dies in private sessions.

Stack Overflow 2025
Architecture

Everything lives in git. Forever.

No external server. No database. No account. No hosting. Works through GitHub, GitLab, Bitbucket, or any internal git host at Google, Amazon, or anywhere else.

Zero dependencies

Reasoning travels with the code. Clone the repo on any machine, you get the full history. Fork it, reasoning forks too.

Security

Credentials, API keys, passwords, and tokens are detected and masked before any data hits disk. Irreversible by design.

Compact

10-50 KB per commit. 1,000 commits = 10-50 MB. Within every hosting platform's limits.

5 years from now

The reasoning is still there. Delete .g4a/, still a valid git repo. Always additive, never destructive.

Open schema

Self-describing format. Any future tool can parse every record without knowing g4a.

All agents

Claude Code (direct), Cursor, Copilot, Codex, Windsurf, Aider (git hook), and any custom agent.

Git stores what changed.
g4a stores why.

View on GitHub Read the HLD