pinit.nvim

Attach private notes to any line of code — without touching the source file.

A Neovim plugin that lets you pin notes to specific lines across your project. Notes live in a .pinit.json sidecar, a 📌 icon appears in the sign column, and a floating window lets you read or edit them instantly.

Requires Neovim ≥ 0.10. No mandatory dependencies.

---

Features

• Pin icon in the sign column on any annotated line
• Floating edit window (markdown, <C-s> / :w to save, <Esc> / q to discard)
• Auto-peek on CursorHold or explicit keymap
• Delete a note with one keymap
• Browse all project notes with Telescope (optional)
• Notes persist in .pinit.json at the project root (git / package.json / *.sln / *.csproj)

---

Installation

lazy.nvim

{
  "adia-dev/pinit.nvim",
  event = { "BufReadPost", "BufNewFile" },
  -- optional: load commands immediately for cmd-based lazy loading
  cmd = { "PinitAdd", "PinitPeek", "PinitDelete", "PinitFind" },
  opts = {},   -- calls setup() with defaults
}

packer.nvim

use {
  "adia-dev/pinit.nvim",
  config = function()
    require("pinit").setup()
  end,
}

vim-plug

Plug 'adia-dev/pinit.nvim'

Then in your Lua config:

require("pinit").setup()

---

Configuration

All options are optional — defaults shown below.

require("pinit").setup({
  sign_text    = "",        -- pin icon in sign column
  sign_hl      = "PinitSign", -- highlight group (override in your colorscheme)
  float_width  = 60,          -- edit/peek float width (columns)
  float_height = 10,          -- edit/peek float max height (rows)
  peek_on_hold = true,        -- auto-peek note under cursor on CursorHold
  keymaps = {
    add    = "<leader>pn",    -- add/edit note on current line
    peek   = "<leader>pp",    -- peek at note on current line
    delete = "<leader>pd",    -- delete note on current line
    find   = "<leader>pf",    -- browse all notes (requires Telescope)
  },
})

Highlight group

PinitSign defaults to a warm yellow. Override it after setup() or in your colorscheme:

vim.api.nvim_set_hl(0, "PinitSign", { fg = "#80ff80" })

---

Default keymaps

Keymap	Action
<leader>pn	Add / edit note on current line
<leader>pp	Peek at note on current line
<leader>pd	Delete note on current line
<leader>pf	Browse all notes (Telescope)

Keymaps are buffer-local and set automatically on every real file buffer.

Inside the edit float

Key	Action
<C-s>	Save and close
:w	Save and close
<Esc> / q	Discard and close

---

User commands

The following commands are available regardless of lazy-loading:

Command	Description
:PinitAdd	Add / edit note on current line
:PinitPeek	Peek at note on current line
:PinitDelete	Delete note on current line
:PinitFind	Browse all notes via Telescope

---

Sidecar format

Notes are stored at <project-root>/.pinit.json:

{
  "src/auth/middleware.lua": {
    "42": "Assumes user is already authenticated — see AuthMiddleware",
    "87": "TODO: replace with async overload once SDK is updated"
  }
}

Important: add to .gitignore

.pinit.json is private — add it to your project's .gitignore:

.pinit.json

Or globally:

echo ".pinit.json" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

---

Edge cases handled

Scenario	Behaviour
Buffer has no backing file (buftype != "" or empty name)	Signs and keymaps are silently skipped
Line number drift after edits	Notes are keyed by line at write time; a warning appears in the peek float if the stored line exceeds current buffer length
Multiple windows on the same buffer	Signs and peek floats work correctly in any active window
.pinit.json deleted externally	Treated as empty — no error
setup() called after buffers are already open	All loaded buffers are retroactively attached
Colorscheme change	PinitSign highlight is re-applied (with default = true, so your colorscheme wins)
Working directory change (DirChanged)	Project root is re-computed for the new cwd

---

Telescope integration

<leader>pf / :PinitFind opens a picker showing every note in the project. Each entry displays the relative path, line number, and first line of the note. Selecting an entry jumps to that file and line (centered on screen).

If Telescope is not installed the command emits a WARN notification and no-ops cleanly.