{ "markdown": "
\n\n\"koment\n\n# koment\n\n**Keep the _why_ next to your code — checked, so it can't quietly rot.**\n\n[![Release](https://img.shields.io/github/v/release/koment-dev/koment?label=release)](https://github.com/koment-dev/koment/releases/latest)\n[![CI](https://img.shields.io/github/actions/workflow/status/koment-dev/koment/ci.yml?branch=main&label=ci)](https://github.com/koment-dev/koment/actions/workflows/ci.yml)\n[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/koment-dev/koment?label=openssf+scorecard)](https://scorecard.dev/viewer/?uri=github.com/koment-dev/koment)\n[![Open VSX](https://img.shields.io/open-vsx/v/koment/koment-dev?label=open%20vsx)](https://open-vsx.org/extension/koment/koment-dev)\n[![License](https://img.shields.io/github/license/koment-dev/koment)](https://github.com/koment-dev/koment/blob/main/LICENSE)\n[![Annotations](https://img.shields.io/badge/annotations-browse-brightgreen)](https://why.koment.dev/)\n\n
\n\n## The problem\n\nSomeone wrote `retry 5 times` instead of 3, and there was a good reason. Six\nmonths later nobody remembers it, so it gets \"simplified\" back to 3 and the bug\nreturns.\n\nA comment was supposed to prevent that. Comments rot: they sit next to the code\nwithout being attached to it, and when the code changes nothing tells you the\ncomment just became a lie. Your AI agent then reads that lie and acts on it.\n\n## What koment does\n\nYou record the reason **outside** the source, anchored to the exact lines it\nexplains. Then koment watches those lines. Change them, and it says so:\n\n```console\n$ koment check\ninternal/auth/token.go\n drifted gotcha internal/auth/token.go 01KZN63VC5SZASDYJBMPDC03WB\n Without it, clients whose clock runs fast get logged out mid-request. Bit\n us in #412.\n1 annotation across 1 file: 1 drifted\nkoment: 1 annotation no longer resolves; revisit it or update the anchor\n```\n\nExit code 1. The build stops. Nobody silently inherits a reason that no longer\ndescribes the code.\n\nThe records are YAML in `.koment/`, in your git repository. No database, no\nservice, no account. They review in the same pull request as the change that\nmotivated them.\n\n**[See it running →](https://why.koment.dev/)** — koment's own annotations,\npublished by [a workflow you can copy](docs/guides/publish-annotations.md).\n\n## For AI agents\n\nThis is where it earns its keep. Agents write explanatory comments constantly,\nand they edit code without reading why it was written that way. koment makes\nboth of those fail *immediately*, while the agent is still working:\n\n- **It writes a comment** → the edit is refused, with instructions to record the\n reasoning as an annotation instead.\n- **It edits annotated code without checking** → the turn cannot finish until\n the annotation is revisited.\n\nOne MCP server serves Claude Code, Cursor, Codex, opencode, Hermes, Zed and the\nrest, so every agent reads the same reasoning through the same interface.\n[Set yours up →](docs/guides/agents/)\n\nHumans get the same loop in the editor: a squiggle under the comment, and a\nquick fix offering *convert to annotation* or *keep it, on the record*.\n\n## Install\n\n```bash\nbrew install koment-dev/tap/koment\n```\n\n
\nOther ways\n\n```bash\nmise use -g github:koment-dev/koment # mise\ngo install github.com/koment-dev/koment/cmd/koment@latest\ndocker run --rm -v \"$PWD:/repo\" -w /repo ghcr.io/koment-dev/koment:3 check\n```\n\nIn GitHub Actions, `uses: koment-dev/koment@v3`. Or take a checksum-listed\nbinary for Linux, macOS or Windows on amd64/arm64 from the\n[latest release](https://github.com/koment-dev/koment/releases/latest) — every\nother channel is built from those same artifacts.\n\n
\n\n## Try it in a minute\n\nFrom inside any git repository:\n\n```bash\nkoment bootstrap\n```\n\nThat sets up `.koment/` and wires whichever agents you use. Now record a reason\nand watch it get checked:\n\n```bash\nkoment add src/auth.go \\\n --excerpt 'if token.Expiry.Before(now.Add(-clockSkew)) {' \\\n --kind gotcha \\\n --title 'Skew subtraction keeps fast clocks logged in' \\\n --body 'Without it, clients whose clock runs fast get logged out\n mid-request. Bit us in #412.'\n\nkoment check # ok\n```\n\n**Now edit that line and run `koment check` again.** It fails, and tells you\nwhich reasoning no longer matches its code. That is the entire product; the rest\nis delivering it to the people and agents who need it.\n\n```bash\nkoment ui # read them in a browser\nkoment show src/auth.go\n```\n\n## How it works\n\n1. You annotate a snippet. koment records the prose, exact excerpt, surrounding\n source context, the commit you were on, and who you are.\n2. The record lands in `.koment/annotations/.yaml`, one file per\n annotation. Concurrent agents create independent files instead of replacing\n one shared list.\n3. Resolution searches the current file for that excerpt and produces exactly\n one status:\n\n | | meaning | build |\n |---|---|---|\n | `ok` | found where it was last seen | passes |\n | `ambiguous` | several contextual candidates remain | **fails** |\n | `drifted` | file exists, the annotated code is gone | **fails** |\n | `orphaned` | the file is gone | **fails** |\n\n4. `koment check` exits non-zero on `ambiguous`, `drifted` or `orphaned`. That\n is the whole mechanism: uncertain rationale is worse than no annotation, so\n it has to be impossible to ignore.\n5. When it fails, `koment reanchor --excerpt ''` repoints it —\n keeping its id and creation date, recapturing context and the line for you.\n Nothing re-attaches automatically; a person confirms the reasoning still holds.\n\nAnchoring is by **excerpt**, never by line number — line numbers rot on the next\nedit above them. The commit hash *is* recorded, but only to reconstruct history;\nit never decides whether an annotation still applies. Those are two different\nquestions with two different mechanisms.\n\nLocal writes change the checkout you are already reviewing. Served writes never\ntouch a replica or push a default branch: they create an exact annotation on a\ndeterministic branch and return only after its pull request exists. Static\npublications remain immutable and read-only.\n\n## Three ways to run it\n\nPick one. Each is a place to stop, not a step you have to take, and **moving\nbetween them is not a migration** — all three read the same `.koment/` in git,\nso there is nothing to export, import or back up.\n\n| | you run | you get |\n|---|---|---|\n| **local** | the CLI, `koment ui --write`, and `koment mcp --write` | humans and agents read and write the same checked records. Nothing to host. |\n| **published** | [one workflow file](docs/guides/publish-annotations.md) → GitHub Pages | everyone reads the annotations in a browser. No server, no auth to design, no cost. |\n| **served** | the container or the [Helm chart](#kubernetes) | authenticated, commit-stamped GitHub snapshots for several repositories, cross-repository search, reviewed annotation PRs, metrics |\n\n## Several repositories\n\nOne deployment serves many. Identity is assigned independently of provider path,\nand every refresh resolves a branch to one immutable commit before replacing a\nrepository's active snapshot:\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/koment-dev/koment/main/schema/server.schema.json\nrepositories:\n - id: payments\n name: Payments API\n provider: github\n remote: you/payments\n default_branch: main\n default: true\n - id: web\n name: Customer Web\n provider: github\n remote: you/web\n default_branch: main\n```\n\nThe service starts only when a non-loopback listener has either trusted-proxy\nidentity or scoped bearer credentials. Private repositories and reviewed writes\nalso require a GitHub token. The [Helm chart documentation](distribution/helm/koment/README.md)\nshows the secret formats and boundary.\n\nLocal commands need none of this configuration — koment finds the owning\ncheckout by walking up from the working directory.\n\n## Kubernetes\n\nkoment publishes an **OCI** Helm chart to `oci://ghcr.io/koment-dev/charts/koment`:\n\n```bash\nhelm install koment oci://ghcr.io/koment-dev/charts/koment \\\n --set repositories[0].remote=you/your-repo \\\n --set metrics.enabled=true \\\n --set metrics.serviceMonitor.enabled=true \\\n --set metrics.dashboard.enabled=true\n```\n\nThe application port authenticates source, rationale, UI and MCP; only liveness\nand readiness are public. Metrics use a separate listener so an ingress cannot\naccidentally expose them with application authentication. The chart includes a\nGrafana dashboard, ServiceMonitor, hardened pod defaults, optional NetworkPolicy\nand disruption controls, and a digest-pinned `helm test` probe.\n\n## Configuration\n\nEvery flag can be set from the environment. `--flag-name` becomes\n`KOMENT_FLAG_NAME`, and an explicit flag always wins.\n\n| | |\n|---|---|\n| `KOMENT_CONFIG` | strict served repository YAML |\n| `KOMENT_CREDENTIALS_FILE` | secret file of SHA-256 bearer hashes and repository scopes |\n| `KOMENT_GITHUB_TOKEN_FILE` | provider token file for private reads and reviewed writes |\n| `KOMENT_LISTEN` | local UI or unified service address |\n| `KOMENT_HUMAN_WRITES` | allow identities from the trusted OIDC proxy to create reviewed annotations |\n| `KOMENT_TRUSTED_PROXIES` | CIDRs allowed to assert forwarded human identity |\n| `KOMENT_SYNC_INTERVAL` | provider snapshot refresh interval |\n| `KOMENT_METRICS` | separate metrics listener; off unless set |\n| `KOMENT_WRITE` | enable local UI or stdio MCP mutations |\n| `KOMENT_OUT` | static publication output directory |\n\nGit is the only authoritative record. Local reads resolve the YAML directly\nagainst the working tree; disposable read models cannot restore or overwrite\nGit.\n\n`koment --help` lists every flag alongside its variable.\n\n## Work where the code lives\n\nThe reference [VS Code extension](integrations/editors/vscode/README.md) starts `koment lsp`,\nrenders annotation bodies as virtual inline text, reports drift and prohibited\ncomments as diagnostics, and adds native add, reanchor, convert and explicit\nacknowledgement actions. The prose is never inserted into the source buffer.\nEvery release attaches a signed VSIX and publishes the same artifact to the VS\nCode Marketplace and Open VSX.\n\nOther editors can use the standard hover, diagnostics, code-lens, code-action\nand execute-command surface from `koment lsp` without reimplementing storage or\nanchoring.\n\nClaude Code can install the repository's own project-scoped marketplace plugin:\n\n```text\n/plugin marketplace add koment-dev/koment\n/plugin install koment@koment-dev\n```\n\nIt bundles writable MCP configuration, injects the strict procedure at session\nstart and runs the policy gate before Claude can finish a turn. Install a\nreleased `koment` binary and run `koment agents install` in the repository first.\n\nOpenCode ships a parallel plugin at\n[`integrations/agent-plugins/opencode/`](integrations/agent-plugins/opencode/).\nAdd `@koment/opencode-koment` to the `plugin` array in `opencode.json`; OpenCode\ninstalls it at startup. It requires the released `koment` binary on `PATH`,\ndenies ordinary explanatory comment intent and runs the policy gate on session\nend. ADR 0144 records the package and generated-adapter boundary.\n\nCodex ships the same policy surface as a local marketplace at\n[`integrations/agent-plugins/codex/`](integrations/agent-plugins/codex/).\nInstall that checkout path with `codex plugin marketplace add`, then run\n`codex plugin add koment@koment-dev`. The release workflow also produces a\nsigned archive. The plugin provides writable MCP tools, a standing skill and\ntrusted lifecycle hooks. ADR 0151 records the package boundary.\n\n## Give it to your agents\n\n```bash\nkoment agents install\nkoment mcp --write\n```\n\nThe generated repository adapters give agents a strict procedure and configure\nthe writable stdio server. It has three read tools:\n\n- **`koment_get(file, repository?)`** — annotations for the file an agent is about to edit\n- **`koment_search(query, repository?)`** — find reasoning by topic; omitting `repository` searches all of them\n- **`koment_repositories()`** — what this deployment serves, with counts\n\nWrite mode adds four tools:\n\n- **`koment_add`** — create agent-attributed rationale\n- **`koment_reanchor`** — explicitly move an existing anchor\n- **`koment_convert_comment`** — record a comment as rationale, then remove it\n- **`koment_acknowledge_comment`** — retain an exceptional comment only after an explicit acknowledgement\n\nThose four mutation tools operate on a local checkout. The authenticated served\nMCP surface exposes `koment_add` and returns the deterministic branch, commit and\npull-request URL; source-mutating conversion and reanchor stay local so the\nservice cannot overwrite an agent's separate worktree.\n\nEvery annotation arrives with its resolution status *and* its repository, so a\nstale one is never presented as current and a result is never detached from its\nscope. When a path exists in several repositories `koment_get` **refuses and\nnames the candidates** rather than guessing.\n\n| | | |\n|---|---|---|\n| [Claude Code](docs/guides/agents/claude-code.md) | [Cursor](docs/guides/agents/cursor.md) | [VS Code](docs/guides/agents/vscode.md) |\n| [Zed](docs/guides/agents/zed.md) | [Codex](docs/guides/agents/codex.md) | [opencode](docs/guides/agents/opencode.md) |\n| [Hermes](docs/guides/agents/hermes.md) | [OpenClaw](docs/guides/agents/openclaw.md) | [Anything else](docs/guides/agents/other.md) |\n\n## Publish it\n\nYour reviewers are not going to install anything. Give them a URL: one workflow\nfile renders every annotation to static HTML plus `annotations.json` and\n`search.json`, then puts the atomic snapshot on GitHub Pages with no server,\ndatabase or authentication to design.\n\n```yaml\n- uses: actions/checkout@v7\n- uses: koment-dev/koment@v3\n- run: koment check\n- run: koment site --out dist\n```\n\nEvery page names the commit it was rendered from, so a snapshot can never pass\nfor the current tree. `koment check` in the same workflow means a build that\nwould publish drift fails first.\n\n**[The whole workflow, ready to copy →](docs/guides/publish-annotations.md)**\n\nA site renders your source as well as your annotations, so publishing one from a\nprivate repository publishes that source. Grouped publications render one\nsnapshot per repository and connect them through the ordinary repository\nswitcher; there is no selector landing page.\n\n## Documentation\n\n- **[Publishing](docs/guides/publish-annotations.md)** — the copy-paste workflow, and moving to a served instance later\n- **[Contributor setup](docs/start/contributing.md)** — establish a verified development checkout\n- **[Getting started](docs/start/quickstart.md)** · **[Writing good annotations](docs/guides/write-good-annotations.md)** · **[CLI reference](docs/reference/cli.md)** · **[CI](docs/guides/enforce-in-ci.md)**\n\n## What koment is not\n\n- **Not general project documentation.** koment holds knowledge bound to a\n *place* in the code; broad project guidance belongs in the documentation\n system your team already uses.\n- **Not a memory system.** A consolidating store paraphrases, merges and\n eventually forgets. koment is a record, not a belief.\n- **Not line-precise.** Anchors are snippets.\n\n## Prior art\n\n[Codetations / Magic Markup](https://github.com/elmisback/codetations) is the\nclosest existing work — document-external annotations with LLM re-anchoring. The\nanchoring problem dates to [Microsoft Research, 2001](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-2001-107.pdf)\nand is still unsolved in the general case. The UI owes its shape to\n[konflate](https://github.com/home-operations/konflate), which makes an\ninvisible layer visible for Flux the way koment tries to for rationale.\n\n## License\n\n[AGPL-3.0-or-later](LICENSE) is the open-source grant for the repository except\n`integrations/editors/zed/`. That extension code alone is\n[GPL-3.0-or-later](integrations/editors/zed/LICENSE) so Zed may build and\ndistribute it through its registry; the koment binary it starts remains AGPL.\nBoth license files are verbatim texts so automated scanners identify them\ncorrectly. [ADR 0145](docs/explanation/decisions/0145-license-the-zed-extension-under-gplv3.md)\nrecords the narrow exception.\n\nThe complete corresponding source is this repository,\n, which satisfies the AGPL §13 obligation\nfor anyone interacting with a koment server over a network.\n\nCommercial licences are available on request for organisations whose policy\nexcludes AGPL, or that want warranty or indemnification — write to\n[licensing@koment.dev](mailto:licensing@koment.dev).\n\nReleases ≤ v0.6.0 were distributed under the MIT licence and remain MIT in\nperpetuity. The last MIT-tagged source may be forked from\n[`v0.6.0`](https://github.com/koment-dev/koment/tree/v0.6.0) under those terms\nindefinitely. The decision is recorded in [ADR 0117](docs/explanation/decisions/0117-relicense-to-agpl-with-commercial-dual-licensing.md).\n\n**Does using koment make my code AGPL?** No. koment is a *tool*; annotations\nit writes are data, not derivative works of the tool. The same legal class\napplies as compiling a program with GCC: the tool's licence governs the tool,\nnot what you build with it. This is the intent of every OSI-approved AGPL\ndeployment that processes external input; if your organisation's counsel\ndisagrees, the commercial licence resolves it.\n", "bytes": 17588, "sha": "0967c30a4734295acb0a5c457aa5f6ac9536aa7dcdb005c7d8521be9fad92230", "repo_slug": "janpuc/koment", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_janpuc_koment_04060d14/readme" }