koment

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

Readable code answers what. It cannot answer why this and not the obvious alternative, what bit us here before, or what breaks if you "simplify" this. Comments are the usual home for that and they rot — they duplicate the code, drift from it silently, and nothing ever tells you they have stopped being true.

koment puts that reasoning beside the code instead: prose anchored to a verbatim snippet, stored in .koment/ in git, reviewable in the same pull request as the change that motivated it. Then it checks the anchor. When the annotated code changes, koment check fails the build rather than serving a note that no longer describes anything.

Your agents read it too. One MCP server gives Claude Code, Cursor, Codex, Zed, Hermes and the rest the same reasoning through the same interface — because an agent that cannot see why something was built a certain way will happily refactor the reason away.

See it running → — koment's own annotations, rendered by koment onto GitHub Pages by the workflow you can copy.

How it works

1. You annotate a snippet. koment records the prose, exact excerpt, surrounding source context, the commit you were on, and who you are.

2. The record lands in .koment/annotations/<id>.yaml, one file per annotation. Concurrent agents create independent files instead of replacing one shared list.

3. Resolution searches the current file for that excerpt and produces exactly one status:

   	meaning	build
   ok	found where it was last seen	passes
   moved	still there, different line	passes
   ambiguous	several contextual candidates remain	fails
   drifted	file exists, the annotated code is gone	fails
   orphaned	the file is gone	fails

4. koment check exits non-zero on ambiguous, drifted or orphaned. That is the whole mechanism: uncertain rationale is worse than no annotation, so it has to be impossible to ignore.

5. When it fails, koment reanchor <id> --excerpt '<new text>' repoints it — keeping its id and creation date, recapturing context and the line for you. Nothing re-attaches automatically; a person confirms the reasoning still holds.

Anchoring is by excerpt, never by line number — line numbers rot on the next edit above them. The commit hash is recorded, but only to reconstruct history; it never decides whether an annotation still applies. Those are two different questions with two different mechanisms.

Local writes change the checkout you are already reviewing. Served writes never touch a replica or push a default branch: they create an exact annotation on a deterministic branch and return only after its pull request exists. Static publications remain immutable and read-only.

Three ways to run it

Pick one. Each is a place to stop, not a step you have to take, and moving between them is not a migration — all three read the same .koment/ in git, so there is nothing to export, import or back up.

Quick start

Install from the latest release. Every release carries checksum-listed binaries for Linux, macOS and Windows on amd64 and arm64. The setup Action, mise, container, Helm chart, editor package, and registry metadata all consume those same release artifacts. With mise:

mise use -g github:janpuc/koment

cd ~/your-project
koment agents install
koment add src/auth.go \
  --excerpt 'if token.Expiry.Before(now.Add(-clockSkew)) {' \
  --kind gotcha \
  --body 'The skew subtraction is deliberate. Without it, clients whose clock
          runs fast get logged out mid-request. Bit us in #412.'

koment check
koment comments check
koment ui --write

Now edit that line and run koment check again. It fails — because the reasoning you wrote no longer describes the code, and silently keeping it is exactly how comments rot.

Several repositories

One deployment serves many. Identity is assigned independently of provider path, and every refresh resolves a branch to one immutable commit before replacing a repository's active snapshot:

# yaml-language-server: $schema=https://raw.githubusercontent.com/janpuc/koment/main/schema/server.schema.json
repositories:
  - id: payments
    name: Payments API
    provider: github
    remote: you/payments
    default_branch: main
    default: true
  - id: web
    name: Customer Web
    provider: github
    remote: you/web
    default_branch: main

The service starts only when a non-loopback listener has either trusted-proxy identity or scoped bearer credentials. Private repositories and reviewed writes also require a GitHub token. The Helm chart documentation shows the secret formats and boundary.

Local commands need none of this configuration — koment finds the owning checkout by walking up from the working directory.

Kubernetes

koment publishes an OCI Helm chart to oci://ghcr.io/janpuc/charts/koment:

helm install koment oci://ghcr.io/janpuc/charts/koment \
  --set repositories[0].remote=you/your-repo \
  --set metrics.enabled=true \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.dashboard.enabled=true

The application port authenticates source, rationale, UI and MCP; only liveness and readiness are public. Metrics use a separate listener so an ingress cannot accidentally expose them with application authentication. The chart includes a Grafana dashboard, ServiceMonitor, hardened pod defaults, optional NetworkPolicy and disruption controls, and a digest-pinned helm test probe.

Configuration

Every flag can be set from the environment. --flag-name becomes KOMENT_FLAG_NAME, and an explicit flag always wins.

Git is the only authoritative record. Local reads resolve the YAML directly against the working tree; disposable read models cannot restore or overwrite Git.

koment <command> --help lists every flag alongside its variable.

Work where the code lives

The reference VS Code extension starts koment lsp, renders annotation bodies as virtual inline text, reports drift and prohibited comments as diagnostics, and adds native add, reanchor, convert and explicit acknowledgement actions. The prose is never inserted into the source buffer. Every release attaches a signed VSIX; the same VSIX is published to the VS Code Marketplace and Open VSX when the repository publisher tokens are configured.

Other editors can use the standard hover, diagnostics, code-lens, code-action and execute-command surface from koment lsp without reimplementing storage or anchoring.

Claude Code can install the repository's own project-scoped marketplace plugin:

/plugin marketplace add janpuc/koment
/plugin install koment@janpuc-tools

It bundles writable MCP configuration, injects the strict procedure at session start and runs the policy gate before Claude can finish a turn. Install a released koment binary and run koment agents install in the repository first.

Give it to your agents

koment agents install
koment mcp --write

The generated repository adapters give agents a strict procedure and configure the writable stdio server. It has three read tools:

• koment_get(file, repository?) — annotations for the file an agent is about to edit
• koment_search(query, repository?) — find reasoning by topic; omitting repository searches all of them
• koment_repositories() — what this deployment serves, with counts

Write mode adds four tools:

• koment_add — create agent-attributed rationale
• koment_reanchor — explicitly move an existing anchor
• koment_convert_comment — record a comment as rationale, then remove it
• koment_acknowledge_comment — retain an exceptional comment only after an explicit acknowledgement

Those four mutation tools operate on a local checkout. The authenticated served MCP surface exposes koment_add and returns the deterministic branch, commit and pull-request URL; source-mutating conversion and reanchor stay local so the service cannot overwrite an agent's separate worktree.

Every annotation arrives with its resolution status and its repository, so a stale one is never presented as current and a result is never detached from its scope. When a path exists in several repositories koment_get refuses and names the candidates rather than guessing.

Publish it

Your reviewers are not going to install anything. Give them a URL: one workflow file renders every annotation to static HTML plus annotations.json and search.json, then puts the atomic snapshot on GitHub Pages with no server, database or authentication to design.

- uses: actions/checkout@v5
- uses: janpuc/koment@v0.2.0
- run: koment check
- run: koment site --out dist

Every page names the commit it was rendered from, so a snapshot can never pass for the current tree. koment check in the same workflow means a build that would publish drift fails first.

The whole workflow, ready to copy →

A site renders your source as well as your annotations, so publishing one from a private repository publishes that source. Grouped publications render one snapshot per repository and connect them through the ordinary repository switcher; there is no selector landing page.

Documentation

• Publishing — the copy-paste workflow, and moving to a served instance later
• Bootstrap — what it is, the data model, running it, releases
• Getting started · Writing good annotations · CLI reference · CI

What koment is not

• Not general project documentation. koment holds knowledge bound to a place in the code; broad project guidance belongs in the documentation system your team already uses.
• Not a memory system. A consolidating store paraphrases, merges and eventually forgets. koment is a record, not a belief.
• Not line-precise. Anchors are snippets.

Prior art

Codetations / Magic Markup is the closest existing work — document-external annotations with LLM re-anchoring. The anchoring problem dates to Microsoft Research, 2001 and is still unsolved in the general case. The UI owes its shape to konflate, which makes an invisible layer visible for Flux the way koment tries to for rationale.

License

MIT