Koment

Keep the why next to your code — checked, so it can't quietly rot.

The problem

Someone wrote retry 5 times instead of 3, and there was a good reason. Six months later nobody remembers it, so it gets "simplified" back to 3 and the bug returns.

A comment was supposed to prevent that. Comments rot: they sit next to the code without being attached to it, and when the code changes nothing tells you the comment just became a lie. Your AI agent then reads that lie and acts on it.

What koment does

You record the reason outside the source, anchored to the exact lines it explains. Then koment watches those lines. Change them, and it says so:

$ koment check
internal/auth/token.go
  drifted   gotcha        internal/auth/token.go  01KZN63VC5SZASDYJBMPDC03WB
    Without it, clients whose clock runs fast get logged out mid-request. Bit
    us in #412.
1 annotation across 1 file: 1 drifted
koment: 1 annotation no longer resolves; revisit it or update the anchor

Exit code 1. The build stops. Nobody silently inherits a reason that no longer describes the code.

The records are YAML in .koment/, in your git repository. No database, no service, no account. They review in the same pull request as the change that motivated them.

See it running → — koment's own annotations, published by a workflow you can copy.

For AI agents

This is where it earns its keep. Agents write explanatory comments constantly, and they edit code without reading why it was written that way. koment makes both of those fail immediately, while the agent is still working:

• It writes a comment → the edit is refused, with instructions to record the reasoning as an annotation instead.
• It edits annotated code without checking → the turn cannot finish until the annotation is revisited.

One MCP server serves Claude Code, Cursor, Codex, opencode, Hermes, Zed and the rest, so every agent reads the same reasoning through the same interface. Set yours up →

Humans get the same loop in the editor: a squiggle under the comment, and a quick fix offering convert to annotation or keep it, on the record.

Install

brew install koment-dev/tap/koment

mise use -g github:koment-dev/koment          # mise
go install github.com/koment-dev/koment/cmd/koment@latest
docker run --rm -v "$PWD:/repo" -w /repo ghcr.io/koment-dev/koment:3 check

Try it in a minute

From inside any git repository:

koment bootstrap

That sets up .koment/ and wires whichever agents you use. Now record a reason and watch it get checked: