koment

<div align="center">

<img src="internal/ui/assets/koment-logo.svg" alt="koment comment bubble" width="104">

# koment

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

[![CI](https://img.shields.io/github/actions/workflow/status/janpuc/koment/ci.yml?branch=main&label=ci)](https://github.com/janpuc/koment/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/actions/workflow/status/janpuc/koment/release.yml?branch=main&label=release)](https://github.com/janpuc/koment/actions/workflows/release.yml)
[![Annotations](https://img.shields.io/badge/annotations-browse-brightgreen)](https://janpuc.github.io/koment/)
[![License](https://img.shields.io/github/license/janpuc/koment)](https://github.com/janpuc/koment/blob/main/LICENSE)

</div>

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 →](https://janpuc.github.io/koment/)** — koment's own
annotations, rendered by koment onto GitHub Pages by [the workflow you can
copy](docs/publishing.md).

## 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.

| | you run | you get |
|---|---|---|
| **local** | the CLI, `koment ui --write`, and `koment mcp --write` | humans and agents read and write the same checked records. Nothing to host. |
| **published** | [one workflow file](docs/publishing.md) → GitHub Pages | everyone reads the annotations in a browser. No server, no auth to design, no cost. |
| **served** | the container or the [Helm chart](#kubernetes) | authenticated, commit-stamped GitHub snapshots for several repositories, cross-repository search, reviewed annotation PRs, metrics |

## Quick start

Install from the [latest release](https://github.com/janpuc/koment/releases/latest).
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:

```bash
mise use -g github:janpuc/koment
```

```bash
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
# 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](charts/koment/README.md)
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`:

```bash
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.

| | |
|---|---|
| `KOMENT_CONFIG` | strict served repository YAML |
| `KOMENT_CREDENTIALS_FILE` | secret file of SHA-256 bearer hashes and repository scopes |
| `KOMENT_GITHUB_TOKEN_FILE` | provider token file for private reads and reviewed writes |
| `KOMENT_LISTEN` | local UI or unified service address |
| `KOMENT_HUMAN_WRITES` | allow identities from the trusted OIDC proxy to create reviewed annotations |
| `KOMENT_TRUSTED_PROXIES` | CIDRs allowed to assert forwarded human identity |
| `KOMENT_SYNC_INTERVAL` | provider snapshot refresh interval |
| `KOMENT_METRICS` | separate metrics listener; off unless set |
| `KOMENT_WRITE` | enable local UI or stdio MCP mutations |
| `KOMENT_OUT` | static publication output directory |

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](editors/vscode/README.md) 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:

```text
/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

```bash
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