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.
Start one when you create the repository. It takes a minute on day one, and an afternoon of detective work after 27 commits, two computers, and three agents.
Two ways to use it
You can keep a colophon as you go or reconstruct one later. Keeping it as you go is easier and far more accurate.
Keep one as you go
Add COLOPHON.md when you create the repository, and ask your agents to update it whenever a new tool, model, computer, or phase of work starts, and before each release. Each entry comes from the agent doing the work, so almost everything is observed rather than remembered.
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.
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 the COLOPHON.md instructions at github.com/liederdigital/colophon-md and follow them to create 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 when something changes and before each release. 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. Update it when a new tool, model, computer, or phase of work starts, and before each release. Follow the instructions in instructions.md at github.com/liederdigital/colophon-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.
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.
Don’t other tools already track AI code?
Some do, line by line. Agent Trace and Git AI record which lines an agent wrote, and the Linux kernel asks for an Assisted-by line on each commit.
Those records are precise, but they only cover work done after they were set up, and they’re written for machines. COLOPHON.md is the summary a person can read, and it works after the fact. Use both.
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, and personal details that have nothing to do with how the project was made.
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.