comments.nvim and editor-native comments for agents

Why Hunk caught my attention, where the workflow felt awkward for me, and why I built comments.nvim inside Neovim instead.

28 May 2026•3 min read

neovim

agents

tooling

I really like tools that don’t force one editor, one model, or one agent workflow.

That’s what made Hunk interesting to me.

If you haven’t seen it, Hunk is a CLI that opens a diff against your main branch and lets you leave comments for an agent directly on the code. Those comments are stored in a simple JSON structure, and the agent can read them, act on them, and clean them up afterward.

The idea is excellent.

It works with whichever agent you prefer — Claude Code, Codex, Cursor, and others — because the interface is simple: diff + comments + a small instruction file telling the agent how to use them.

That instruction file part is especially good.

Hunk ships with a SKILL.md, so you can reference it in the agent prompt and the agent immediately knows where to find the comments, how to interpret them, and how to remove them once resolved.

Hunk prompt showing agent instructions for comment resolution — The SKILL.md piece is what makes the workflow portable across agents without tying it to one coding tool.

It also became popular very quickly. I even noticed Mitchell Hashimoto wrote about it recently — which caught my attention even more, especially since Ghostty is my current terminal and I tend to pay attention to tools he finds worth calling out.

Mitchell Hashimoto post about Hunk — Seeing Mitchell mention Hunk is part of what pushed me to try the workflow more seriously.

Why I built a Neovim version

After using Hunk for a bit, though, I ran into a few things that made the workflow awkward for me:

no Vim-style navigation
some rough edges around commenting and navigation
and, more generally, this felt like something that really wanted to live inside Neovim

I could have tried fixing those things upstream.

Instead, I ended up building a separate Neovim plugin around the same core idea.

So comments.nvim is basically my attempt to bring that workflow fully into the editor:

comments live in .comments/comments.json
they’re attached to lines with extmarks, so they survive edits in the session
line numbers and line text are synced back on save
comments can be created, edited, previewed, and deleted without leaving Neovim
and there’s a small API for integrations with tools like Telescope or snacks

comments.nvim showing inline comments inside Neovim — The same basic workflow, but living directly inside the editor instead of beside it.

I also included a SKILL.md with the plugin, so agents can read the stored comments, address them, and remove them after completion.

comments.nvim skill prompt for agents — Like Hunk, the goal is to keep the protocol simple enough that any agent can participate.

Technically, it’s a pretty small plugin.

But I think the workflow itself is much more important than the implementation: leaving structured, per-line instructions for an agent in a way that is editor-native, durable enough, and not tied to any one AI tool.

Main inspiration: Hunk