koment

Name: koment
Author: janpuc

by janpucversion 1.1.0i★ –iRuns on your computer

Registry nameio.github.janpuc/koment

Install

Overview

Description from the maker (original English)

Read and write checked code rationale stored outside source comments.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Other

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
The registry lists no key to fill in.

You need

DockerDocker installed

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "koment": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/janpuc/koment:1.1.0",
        "mcp",
        "--write"
      ]
    }
  }
}

Run this in your terminal

claude mcp add koment -- docker run -i --rm ghcr.io/janpuc/koment:1.1.0 mcp --write

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "koment": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/janpuc/koment:1.1.0",
        "mcp",
        "--write"
      ]
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "koment": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/janpuc/koment:1.1.0",
        "mcp",
        "--write"
      ]
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account janpuc, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Otheri

More stars than 0% of the other 32583 servers in this category
Published to the registry more recently than 22% of the other 32583 servers in this category
Basic checks equal to or better than 100% of the other 32583 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is koment safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (1.1.0) reached the registry 3 months ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Docker on your computer.

What can I use instead?

In the same category: Spec Driven Development, Remote Desktop Commander, sync. labs

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Spec Driven Development

by formulahendry

MCP Server that facilitates spec-driven development workflows, not just Vibe Coding.

Runs on your computer★ 440MITUpdated 14 months ago

Install

Remote Desktop Commander

by desktop-commander

Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.

Runs in the cloud★ 211Updated yesterday

Install

sync. labs

by synchronicity-labs

Lipsync videos, dub them into other languages, make talking videos and open sync. Studio.

Computer or cloudUpdated today

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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 →](https://why.koment.dev/) — 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

Other ways

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

In GitHub Actions, uses: koment-dev/koment@v3. Or take a checksum-listed binary for Linux, macOS or Windows on amd64/arm64 from the latest release — every other channel is built from those same artifacts.

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:

koment add src/auth.go \

--excerpt 'if token.Expiry.Before(now.Add(-clockSkew)) {' \ --kind gotcha \ --title 'Skew subtraction keeps fast clocks logged in' \ --body 'Without it, clients whose clock runs fast get logged out mid-request. Bit us in #412.'

koment check # ok

Now edit that line and run `koment check` again. It fails, and tells you which reasoning no longer matches its code. That is the entire product; the rest is delivering it to the people and agents who need it.

koment ui        # read them in a browser

koment show src/auth.go

How it works

You annotate a snippet. koment records the prose, exact excerpt, surrounding source context, the commit you were on, and who you are.
The record lands in .koment/annotations/ .yaml, one file per annotation. Concurrent agents create independent files instead of replacing one shared list.
Resolution searches the current file for that excerpt and produces exactly one status:

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

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.
When it fails, koment reanchor --excerpt ' ' 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 → GitHub Pages	everyone reads the annotations in a browser. No server, no auth to design, no cost.
served	the container or the Helm chart	authenticated, commit-stamped GitHub snapshots for several repositories, cross-repository search, reviewed annotation PRs, metrics

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/koment-dev/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/koment-dev/charts/koment:

helm install koment oci://ghcr.io/koment-dev/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 --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 and publishes the same artifact to the VS Code Marketplace and Open VSX.

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 koment-dev/koment

/plugin install koment@koment-dev

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.

OpenCode ships a parallel plugin at integrations/agent-plugins/opencode/. Add @koment/opencode-koment to the plugin array in opencode.json; OpenCode installs it at startup. It requires the released koment binary on PATH, denies ordinary explanatory comment intent and runs the policy gate on session end. ADR 0144 records the package and generated-adapter boundary.

Codex ships the same policy surface as a local marketplace at integrations/agent-plugins/codex/. Install that checkout path with codex plugin marketplace add, then run codex plugin add koment@koment-dev. The release workflow also produces a signed archive. The plugin provides writable MCP tools, a standing skill and trusted lifecycle hooks. ADR 0151 records the package boundary.

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

Only the beginning is shown; read the rest in the repo

koment

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Otheri

Common questions

Alternatives

Spec Driven Development

Remote Desktop Commander

sync. labs

README from the maker

koment

The problem

What koment does

For AI agents

Install

Try it in a minute

How it works

Three ways to run it

Several repositories

Kubernetes

Configuration

Work where the code lives

Give it to your agents