Why keep one
Someone will inherit your project: a client, the next developer, or you, a year from now. They’ll want to know how it was built, and the Git history won’t tell them.
A commit’s author is whichever account made the commit, not necessarily who or what wrote the code. A missing AI note doesn’t prove a person wrote it alone. A tool’s config file shows it was set up, not that it was used.
COLOPHON.md answers the question in one plain page. It works with any agent, or none.
Think of it as the credits at the end of a film, and as a maintenance log: who built each part, which model reviewed it, and who signed off. When version 1.1.8 turns out worse than 1.1.7, or a bug turns up in production, the colophon shows which agents and models were working on the project at the time, and in which mode. If a model version later turns out to have had a flaw, you’ll know which projects, and which weeks, to check.
Start one when you create the repository. It takes a minute on day one. Reconstructing this site’s own history afterward took an evening, three AI tools, and a lot of digging.
What it looks like nine months later
A made-up example: one web app, five AI tools, three devices, two people. Each row is a tool or a person; each mark is a piece of work. The line is the project itself, handed from tool to tool.
Swipe sideways to see the whole timeline.
- Built
- Reviewed
- Approved
- Release
When a checkout bug turns up in v1.3, the colophon shows what changed: on August 28, Claude Code built checkout on Sonnet 5.5 instead of Opus 5.5. The two Unknowns are honest gaps, because those tools didn’t show which model they used.
Show the same history as rows in COLOPHON.md
| Date | Who or what | Role | Where it ran | Model and setting | What changed |
|---|---|---|---|---|---|
| Sep 10 | You | Approved | github.com | Not applicable | Released v1.3 |
| Aug 28 | Claude Code | Built | Terminal on a MacBook Pro | Sonnet 5.5 | Faster checkout |
| Jul 24 | You | Approved | github.com | Not applicable | Released v1.2 |
| Jul 18 | Claude Code | Reviewed | Terminal on a MacBook Pro | Opus 5.5 | Reviewed the sign-up pull request |
| Jul 14 | A collaborator, using Codex | Built | Codex, on their laptop | GPT-6-Astra, high | New sign-up flow |
| Jun 5 | You | Approved | github.com | Not applicable | Released v1.1 |
| Jun 2 | GitHub Copilot | Built | Chrome, on github.com | Unknown | Fixed the pricing table |
| May 14 | Claude Code | Built | Terminal on a MacBook Pro | Opus 5.5 | Sharing |
| Apr 22 | Grok bot | Built | iPhone, through the GitHub command line | Unknown | Two copy changes, by voice |
| Mar 19 | You | Approved | github.com | Not applicable | Released v1.0 |
| Mar 14 | Codex | Reviewed | Codex app on your Mac | GPT-6-Sol | Reviewed the billing pull request |
| Mar 10 | Claude Code | Built | Terminal on a MacBook Pro | Opus 5.5 | Billing |
| Feb 24 | Google Antigravity | Built | Mac app | Argon 4 | Accounts |
| Feb 3 | Google Antigravity | Built | Mac app | Argon 4 | First version |
Two ways to use it
There are two modes: proactive, where you keep a colophon as you go, and forensic, where you reconstruct one later. Proactive is easier and far more accurate.
Proactive mode
Keep one as you go. Add COLOPHON.md when you create the repository, and ask your agents to update it whenever the tool, model, model setting, or computer changes, when a new phase of work starts, and before each release. Each agent writes its own entry in the same commit as its work, so almost everything is observed rather than remembered, and approving the pull request approves the entry.
Forensic mode
Reconstruct one after the fact, for a project that already has history. The agent reads the Git log and any session logs your coding agents saved, fills in what it can, and marks the rest Unknown. Those logs stay on the computer where the work happened, so run it on each computer you used. If you’d rather hand it off, Lieder Digital can reconstruct it for you.
The one rule
Every fact in a colophon is one of three kinds, and the file says which.
- Observed
- Seen directly: in the work session, the files, or the history.
- Owner-confirmed
- Stated by the person responsible for the project.
- Unknown
- Not established, and written down as Unknown so no one mistakes a guess for a fact.
An honest Unknown is worth more than a confident guess.
Add one to your project
-
Give your agent the instructions
Use the copy button above and paste the instructions into your coding agent. Or, if it can read web pages, send it this line:
Read https://colophon.md/instructions.md and follow it to create or update COLOPHON.md for this repository. -
Let it write the first version
On a new project, the agent records the session it’s working in. On an existing one, it reads the Git history and any saved session logs. Either way, it writes COLOPHON.md at the root.
-
Fill in what it couldn’t know
Confirm which model you used, who reviewed what, and anything that happened outside the repository.
-
Keep it current
Add these lines to your AGENTS.md, or whichever instructions file your agents read, so each one updates the colophon itself, in the same commit or pull request as its work. You approve it when you approve the pull request; there’s nothing extra to fill in. A colophon is a summary, not a log, so it doesn’t need a line for every commit.
## Colophon This project keeps COLOPHON.md, a short record of how it was made. Agents update it themselves, in the same commit or pull request as their work: add a row when the tool, model, model setting, or computer changes, when you review someone else's work, and before each release. Never hold up a commit for it. Follow the instructions at https://colophon.md/instructions.md.
Prefer to do it by hand? Download the template and fill it in yourself.
Where it fits
COLOPHON.md sits beside the files a repository already has. Each one answers a different question.
| File | What it records | Written for |
|---|---|---|
| README.md | What the project is and how to use it | People using it |
| AGENTS.md | How to work on the project | AI agents |
| LICENSE | Who may use it, and on what terms | Everyone |
| CREDITS, NOTICE | The code and people it depends on | Everyone |
| COLOPHON.md | How the project was made | Whoever inherits it |
Questions
Are any fields required?
No. It’s plain Markdown. The template is a starting point; leave out whatever doesn’t apply.
Won’t this slow us down?
It shouldn’t, and if it does, something’s wrong. Agents write the entries themselves, in the same commit or pull request as their work, with every field they can fill already filled. Reviewing the pull request is the sign-off. Anything nobody can confirm is marked Unknown, and the work moves on.
Is this an official standard?
Not yet. It’s an open convention that anyone can use, change, or ignore. The more projects keep one, the more people will know to look for it. The instructions and template are in the public domain under CC0.
Isn’t this what git blame is for?
They answer different questions. Git blame shows, line by line, which commit last changed each line and which account made it. That’s the Git identity, not necessarily the person or tool that wrote the code, and a later edit or reformat replaces it.
A colophon steps back to the whole project and records what Git can’t see: which agents and models did the work, on which computers, and who directed and reviewed it.
Doesn’t something like this already exist?
Pieces of it do, and COLOPHON.md is meant to sit on top of them. AI declaration files such as AI-DECLARATION.md state how much AI was involved, as a single level. Line-by-line tools such as Agent Trace and Git AI record exactly which lines an agent wrote. Commit notes like Co-Authored-By name the tool on each commit, but they’re optional, many people turn them off, and they don’t say where the tool ran, who reviewed the work, or which release it shipped in. The Linux kernel asked for an Assisted-by line on AI-assisted commits, but the line no longer names the model, and in October a patch proposed dropping it.
None of these is something a client or a future maintainer can read in a minute. COLOPHON.md is that readable summary: agents cite those records as evidence where they exist and fill in the gaps where they don’t. It also works after the fact.
Who’s using it?
It’s brand new, so not many projects yet. You can see every public repository with a COLOPHON.md using GitHub’s code search (you’ll need to be signed in to GitHub). Some results are older book-style colophons that predate this convention.
Can someone reconstruct one for me?
Yes. If a project already has months of history across several tools and computers, Lieder Digital, the studio behind COLOPHON.md, can reconstruct its colophon for you, with the evidence for each entry. It’s useful for agencies handing a project to a client, and for buyers checking a codebase before they take it over.
Can a colophon prove who wrote the code?
No. It’s a good-faith account. That’s why it keeps what was observed, what the owner confirmed, and what’s unknown apart.
What should stay out of it?
Passwords and keys, private chat or session links, client records, computer names and usernames (say “a MacBook Pro,” not its name), and personal details that have nothing to do with how the project was made. If the project belongs to a client, decide with them whether the file is published at all.
What if I didn’t use AI?
Then say so. A colophon can just as well record that a project was written by hand, in which editor, and when.
Why “colophon”?
In printing, the colophon is the note at the back of a book that records how it was made: the typeface, the paper, the printer. Many websites keep a colophon page for the same reason. COLOPHON.md brings the idea to the repository.