Introduction

madelog records how a project came together and turns the record into one page a company can check.

madelog is a command-line tool that runs next to git. It records the commits you make, the AI sessions attributed to them, and the one-sentence decisions you write down. Every record is hashed onto the one before it. When you are ready, madelog publish renders the log into one static page and sends it to a company in place of a portfolio.

The name stands for what the page is: a log of how the thing was made.

What it records

Everything is an event in .madelog/log.db, an SQLite file inside your repository. Each event has a sequence number, a UUID, a UTC timestamp, a kind, a JSON payload, the hash of the previous event and its own hash. Seven kinds exist, and nothing else is ever written:

Kind	Written by	When	What the payload holds
`intent`	`madelog init`	Once per `init` run	What you are building, for whom, which AI tools, and whether AI sessions are recorded
`commit`	the post-commit hook	Every commit after `init`	Message, author, parents, per-file line counts and status, a diff excerpt of at most 20 lines per file
`ai_session`	the post-commit hook, from Git AI notes	Same commit, one per session with attributed lines	Tool, model, session id, files with AI-written line counts; for Claude Code, the first prompt when the transcript is on this machine
`decision`	`madelog note`	When you run it	One sentence, anchored to the commit you are on; `--private` keeps it off the page
`pattern`	`madelog analyze`, also run by `publish`	Once per detected pattern	A revert, a retry, a fix after AI, or a stall, with the commits involved and one sentence of detail
`summary`	`madelog summarize`, also run by `publish`, and `madelog summary edit`	Once per week, plus once per edit	Two or three paragraphs about one Monday-to-Sunday week, and who wrote them
`hide`	`madelog hide`, or `h` in the preview	When you run it	The id of an AI session the page must not show

No event is updated or deleted. A correction is a new event. Nothing else is recorded: no keystrokes, no screenshots, no files git ignores, no paths that match your redact patterns, no model output. Privacy has the full list and the exact request that leaves the machine on publish. Concepts has every payload field and the hash rule.

What the company sees

The page is one HTML file with inline CSS, no framework and no tracking. It works with JavaScript off. In order:

Intent. What you set out to build and for whom, four figures (commits, decisions, AI sessions, days active), the delivered link and the tools you named.
Timeline. Commits, decisions and AI sessions on one axis. Each point opens a record: the diff excerpt of a commit, or the first prompt of a session. Weekly summaries sit under the axis, each marked as generated when a model or the template wrote it.
Moments. Up to five short stories the analysis picked out: a fix after AI, a decision followed by a new directory, a long gap and how it ended.
Code attribution. How many lines AI sessions proposed, how many were kept unchanged, how many were written by hand. When no Git AI notes exist, the section says so instead of guessing.
The badge. The first and last timestamp, the chain root, the time the server confirmed it, and a link to the server's record.

A page rendered with madelog publish --local says "Not yet published" in the badge. The word "verified" appears only after the root was stored by a server. Page anatomy walks through each section and where its data comes from.

What you do

Three commands carry the work. Everything else exists for when you need it.

$ madelog init                      # once per repository
$ madelog note "chose SQLite over Postgres: one binary, no service"
$ madelog publish                   # when the project is ready to show

madelog init asks four questions, writes .madelog/, adds two lines to .git/hooks/post-commit and creates a device key. From then on every commit is recorded by the hook. madelog note takes one sentence and no editor. madelog publish runs the analysis and the summaries, shows you a preview where you can hide a session or rewrite a summary, renders the page, signs the chain root with the device key and uploads the page.

Where to go next

Installation: the two install scripts, cargo install, checking a download by hand, uninstalling.
Getting started: every command from madelog onboard to a published link, with the output each one prints.
Workflow: a project over three weeks, day by day.
Commands: what each command does, its exit codes, the files it touches and its edge cases, followed by the binary's own --help text.
Configuration: every key in .madelog/config.toml and every environment variable.
FAQ: the five questions people ask first, and what to do when something is not recorded.