From f769ed5e7d50c5a30aacc18c570346602919bf4b Mon Sep 17 00:00:00 2001
From: The_miro <amir@abdelbaki.eu>
Date: Thu, 23 Jul 2026 11:03:22 +0200
Subject: [PATCH] feat(nvim): auto-reload buffers changed on disk by Claude
 Code

Claude Code can write files outside claudecode.nvim's diff-review
pipeline (plain Bash tool calls), leaving open buffers stale. Turn on
autoread and run :checktime on FocusGained/BufEnter/CursorHold(I) plus
claudecode.nvim's own ClaudeCodeDiffClosed/ClaudeCodeSendComplete User
autocmds, so buffers refresh the moment you leave the Claude Code
terminal or a diff/edit lands, without clobbering unsaved local edits.

Verified live against the installed plugin set: all four core events
and both User autocmds register and resolve to :checktime.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/md/editors.md | 13 +++++++++++++
 nvim/init.lua      | 22 ++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/docs/md/editors.md b/docs/md/editors.md
index 4567d2f..1c833d1 100644
--- a/docs/md/editors.md
+++ b/docs/md/editors.md
@@ -84,6 +84,19 @@ Config lives in `nvim/`. Deployed to `~/.config/nvim/` during `shell` module ins
 
 `nvim/cyberqueer-airline.vim` — a custom vim-airline theme using the CyberQueer palette, providing hot-pink/violet segments in the status bar.
 
+### Auto-Reload After External Edits
+
+Claude Code can write files outside `claudecode.nvim`'s diff-review pipeline (plain Bash tool calls), which would otherwise leave an already-open buffer stale. `autoread` is on, plus `:checktime` fires on:
+
+| Trigger | Catches |
+|---------|---------|
+| `FocusGained` / `BufEnter` | Leaving/closing the Claude Code terminal split and landing back on a buffer |
+| `CursorHold` / `CursorHoldI` | A background split you never re-enter (default `updatetime` is 4s) |
+| `User ClaudeCodeDiffClosed` | A proposed diff being accepted/rejected — refreshes immediately instead of waiting for the next tick above |
+| `User ClaudeCodeSendComplete` | A file edit landing while a Claude client is connected — same immediate refresh |
+
+Unmodified buffers reload silently; buffers with unsaved local edits still get Vim's normal "changed outside Vim" (`W11`) prompt instead of being clobbered.
+
 ### Keybindings
 
 All custom bindings live in `nvim/init.lua`. Leader is `<Space>` (`vim.g.mapleader = " "`) — Space otherwise duplicates `l` (move right) in normal mode, so it was free to claim.
diff --git a/nvim/init.lua b/nvim/init.lua
index 06b7385..89bc39a 100644
--- a/nvim/init.lua
+++ b/nvim/init.lua
@@ -138,6 +138,7 @@ vim.opt.hlsearch       = true   -- highlight all search matches (clear with :noh
 vim.opt.history        = 1000   -- keep 1000 entries in command and search history
 vim.opt.wildmenu       = true   -- show a completion menu for : commands
 vim.opt.wildmode       = "list:longest" -- first tab lists completions, second completes to longest common prefix
+vim.opt.autoread       = true   -- silently reload unmodified buffers changed on disk (e.g. by Claude Code); see the autocmds below
 
 -- ── Keymaps ───────────────────────────────────────────────────────────────────
 -- window navigation (normal mode)
@@ -169,6 +170,27 @@ vim.api.nvim_create_autocmd("BufEnter", {
     end,
 })
 
+-- reload files changed on disk (e.g. by Claude Code) ─────────────────────────
+-- Claude Code can write files outside claudecode.nvim's diff-review pipeline
+-- (plain Bash tool calls), leaving any already-open buffer stale. FocusGained/
+-- BufEnter catches it the moment you leave the Claude Code terminal split and
+-- land back on the buffer; CursorHold(I) catches it in a background split you
+-- never re-enter (default 'updatetime' is 4s). autoread (set above) means
+-- unmodified buffers reload silently; buffers with unsaved local edits still
+-- get the normal "changed outside Vim" prompt instead of being clobbered.
+vim.api.nvim_create_autocmd({ "FocusGained", "BufEnter", "CursorHold", "CursorHoldI" }, {
+    pattern  = "*",
+    command  = "checktime",
+})
+
+-- claudecode.nvim fires these the moment an edit lands or a diff is resolved,
+-- so buffers refresh immediately instead of waiting for the next FocusGained/
+-- BufEnter/CursorHold tick above.
+vim.api.nvim_create_autocmd("User", {
+    pattern = { "ClaudeCodeDiffClosed", "ClaudeCodeSendComplete" },
+    command = "checktime",
+})
+
 -- calendar.vim steals <C-hjkl> for month nav; restore window movement
 -- The plugin sets buffer-local mappings on FileType calendar, so we override
 -- them with { buffer = true } mappings of our own that fire after the plugin's.