AI Ledger

A drop-in kit that makes any AI coding tool document every change it makes: what you asked, what it actually did, why, what else it could have done, and how to check it. A Git hook enforces the rule, so no tool or person can skip it. The ledger stays on your computer unless your repository is confirmed private (see Privacy).

Why this exists

"I asked the AI for X, but it did Y" is common, and it usually goes unnoticed until later. The ledger fixes that by making the AI write down, for every task:

• Your request, word for word, next to what it changed.
• The Assumptions it made, so you see where it guessed instead of asking.
• An honest Request vs Result section that says where it deviated and why.
• Concepts explained in plain English, so you learn the techniques it used instead of pasting code you don't understand.
• How to Verify steps, so you can confirm the result yourself.

Over time, the log becomes the project's change history and a record of how your requests turn into code.

---

Install

You need Git. Nothing else (no Node, no Python).

Works with existing projects and new ones. For a new project, create its folder and run git init inside it first. If you forget, the installer stops and tells you, without changing anything.

macOS / Linux

git clone https://github.com/MJ0006/ai-ledger.git
./ai-ledger/install.sh path/to/your/project

Windows (PowerShell)

git clone https://github.com/MJ0006/ai-ledger.git
.\ai-ledger\install.ps1 path\to\your\project

One-liners (run inside your project folder)

curl -fsSL https://raw.githubusercontent.com/MJ0006/ai-ledger/main/install.sh | bash

irm https://raw.githubusercontent.com/MJ0006/ai-ledger/main/install.ps1 | iex

After installing, start a new conversation in your AI tool (or reload it). AI tools read their rules when a conversation starts, so a chat that was already open won't know about the ledger.

Add --local to force local-only mode, or --shared to require a private repository (for example ./install.sh --local path/to/project). With the one-liner, use | bash -s -- --local.

What the installer does

• Installs at your repository root, even if you run it from a subfolder.
• Never overwrites your files. Existing files are kept, and for CLAUDE.md, AGENTS.md, and the other tool files it appends a marked block (<!-- ai-ledger:start --> … <!-- ai-ledger:end -->).
• Is safe to re-run. (To refresh an existing install with a newer version, see Updating.)
• Sets git config core.hooksPath .githooks, unless you already use Husky or another hook setup. In that case it changes nothing and prints the lines to add to your existing hooks.
• Chooses the privacy mode (below) and tells you which one it picked and why.

Privacy: what gets uploaded

The ledger quotes your requests word for word. If you ever type an API key, password, or internal detail into an AI request, it could end up in the ledger, so the ledger is treated as private.

Mode	When	What happens on git push
local (default)	The repo is public, has no remote, is offline, or isn't on GitHub/GitLab	Nothing ledger-related is uploaded. All ledger files (.ai_ledger/, the hooks, and AGENTS.md/CLAUDE.md/etc. created by the installer) are listed in .git/info/exclude, a per-computer ignore list that is never pushed.
shared	origin is confirmed private on GitHub or GitLab	The ledger is committed and pushed so your team shares it. The installer prints a warning: if you ever make the repo public, the ledger (and any secrets in it) becomes public too.

Protections:

• The installer asks GitHub/GitLab whether origin is private (no login needed). Any doubt means local.
• In shared mode, the pre-push hook re-checks on every push and blocks it if the repository has become public (or can't be confirmed private), with the steps to fix it.
• In local mode, the pre-push hook blocks any push whose commits contain .ai_ledger/ files.
• In local mode, a tool file you already had and commit (e.g. your own CLAUDE.md) is not given the rules, because that would publish them. The other tool files still carry them.
• The rules forbid the AI from writing secrets into the ledger. It must write [REDACTED] instead.

Switch modes at any time:

bash .ai_ledger/scripts/set-mode.sh local    # keep on this computer (removes ledger files from the repo)
bash .ai_ledger/scripts/set-mode.sh shared   # share with the team: refused unless the repo is private

Before making a repository public, run set-mode.sh local and commit. Copies pushed earlier are still in the git history: change any keys or passwords they contain, and remove them from history with git filter-repo.

This is the beginning of the README. Read the rest at the original. Read the full README ↗