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.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
