Skip to content

docs: say that the diff and send keys come from the example config - #546

Merged
ThomasK33 merged 1 commit into
mainfrom
docs/readme-diff-keys-from-example
Nov 12, 2026
Merged

docs: say that the diff and send keys come from the example config#546
ThomasK33 merged 1 commit into
mainfrom
docs/readme-diff-keys-from-example

Conversation

@ThomasK33

@ThomasK33 ThomasK33 commented Nov 12, 2026

Copy link
Copy Markdown
Member

Why

README.md says "Accept: :w (save) or <leader>aa" and "Reject: :q or <leader>ad", and tells the reader to use <leader>as to send a selection or a tree file. A reader takes these as plugin behavior. The plugin sets none of the three keys. They are mappings in the lazy.nvim spec of the Installation section (README.md:58, :60-63, :66-67).

What changed

Three places in README.md and one in a fixture README. The new text names the command and says where the key comes from.

Line Old New Evidence
README.md:214 "use <leader>as to send it to Claude" "run :ClaudeCodeSend ... (the keys in the Installation spec map <leader>as to it)" :ClaudeCodeSend is defined at lua/claudecode/init.lua:946. The spec maps it at README.md:58.
README.md:215 "press <leader>as on a file" "run :ClaudeCodeTreeAdd on a file ... (the keys ... map <leader>as to it in the file types that the spec lists)" :ClaudeCodeTreeAdd is defined at init.lua:1049. The spec maps it for NvimTree, neo-tree, oil, minifiles, netrw and snacks_picker_list at README.md:60-63.
README.md:251-252 "Accept: :w (save) or <leader>aa" and "Reject: :q or <leader>ad" "Accept: :w (save) or :ClaudeCodeDiffAccept" and "Reject: :q or :ClaudeCodeDiffDeny", then a paragraph: run these in the proposed buffer, the plugin sets no keymaps for the diff, and the spec maps <leader>aa and <leader>ad to the two commands The commands are defined at init.lua:1209 and :1216. The spec maps the keys at README.md:66-67.
fixtures/issue-289/README.md:58 "the README-default <leader>as" "the <leader>as mapping from the README's Installation spec, which this fixture sets" The fixture sets the key itself (fixtures/issue-289/init.lua:100).

The commands and :w and :q behave as the new text says. I ran the real module in headless Neovim 0.12.3 (isolated home): :w accepts and :q in the proposal window rejects, in the vertical and the unified layout. :ClaudeCodeDiffAccept and :ClaudeCodeDiffDeny act on the diff of the current buffer, so the new text says to run them in the proposed buffer (they only warn elsewhere).

Scope

I grepped every tracked Markdown file for <leader>, modifier keys and the words keymap, keybinding, shortcut, mapped and bound.

  • Plugin keymaps. The plugin sets no <leader> key. grep -rn '<leader>' lua plugin --include=*.lua finds nothing. Its only keymap calls are <C-z> in terminal mode (lua/claudecode/utils.lua:28) and the Snacks instance keys (terminal/snacks.lua:626, :640). The diff modules set no keymap. The README statements about <C-z> and the Snacks keys are therefore correct and I did not touch them.
  • Example blocks. Every other key in README.md (<leader>ac, <C-,>, <M-,>, <C-h> and the rest) sits inside an explicit example config. They claim nothing about the plugin.
  • Fixture READMEs. I checked each <leader> mention in them against the fixture's own Lua. All 25 appear there. For the diff and send keys I also read the mapping: fixtures/repro/init.lua:78-79, fixtures/remote-diff/init.lua:96-97, fixtures/issue-238/init.lua:144-145 and fixtures/issue-289/init.lua:100 call vim.keymap.set, and fixtures/snacks-explorer/lua/plugins/dev-claudecode.lua:18-19 uses a lazy keys entry. So these READMEs describe the fixture and are correct.
  • Not changed.
    • ARCHITECTURE.md:111-113 shows <leader>da and <leader>dq keymaps that nothing sets. PR docs: rewrite the lock file and diff sketches of ARCHITECTURE.md to match the code #543 rewrites that section.
    • fixtures/issue-289/init.lua:20 has the code comment "the README-default <leader>as keymap". It is code, not a README.
    • CHANGELOG.md and scripts/fixtures/changelog-released.md mention <leader>as. They are release notes of past versions.
    • dev-config.lua (the local development spec, described in the Local Interface & Invariants section of README.md) maps <leader>a* keys. It is documented as a spec and claims no default.

Blast Radius

Two Markdown files. Nothing loads them. A wrong sentence here misleads a reader and breaks no behavior.

Verification

  • mise run format-check: exit 0 (358 files, 0 changed).
  • Citation check over the seven READMEs and ARCHITECTURE.md: 764 citations, 1 flagged. The flagged one is [plugin/claudecode.lua:pcall(require, "claudecode")], an expression that main already cites. This change adds no citation.
  • I did not run mise run all. The change is documentation only, and no test, script or CI file reads these files. CI runs the full suite on the pushed head.
  • git merge-tree --write-tree of the head and origin/main is clean.

Generated with xum • Model: anthropic:claude-sonnet-5-5 • Thinking: xhigh

@ThomasK33
docs: say that the diff and send keys come from the example config
accdf94 
README.md said 'Accept: :w or <leader>aa' and 'Reject: :q or <leader>ad', and
told the reader to use <leader>as to send a selection or a tree file. The
plugin sets none of these keys. They are mappings in the Installation spec.
The lines now name the commands (:ClaudeCodeDiffAccept, :ClaudeCodeDiffDeny,
:ClaudeCodeSend, :ClaudeCodeTreeAdd) and say that the spec maps the keys.
The issue-289 fixture README called its own <leader>as mapping a README
default. It now says that the fixture sets it.
@ThomasK33

ThomasK33 commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

@codex review

@ThomasK33

ThomasK33 commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

@codex security review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T05:02:20.176288Z accdf94 Manual request
🔒 Security Review ✅ Completed 2026-11-12T05:04:01.994252Z accdf94 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: accdf94faf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026

Copy link
Copy Markdown

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: accdf94faf

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@ThomasK33
ThomasK33 added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 74f301a Nov 12, 2026
6 checks passed
@ThomasK33
ThomasK33 deleted the docs/readme-diff-keys-from-example branch November 12, 2026 05:37
@ThomasK33 ThomasK33 mentioned this pull request Nov 12, 2026
Merged
hareki pushed a commit to hareki/claudecode.nvim that referenced this pull request Nov 13, 2026
@ThomasK33
docs: use one name for the proposal buffer and finish the cleanup and…
9bfc39c 
… I/O citations (coder#549)

## Why

The READMEs name the buffer that holds Claude's proposed text in two
ways. `README.md:1144` and `:1148`, `ARCHITECTURE.md` and 8 of the 16
uses in `lua/claudecode/README.md` say "proposal buffer".
`lua/claudecode/README.md` and the new paragraph in `README.md:254`
(from coder#546) also say "proposed buffer". The advisor of coder#546 asked for
one name for one thing.

The advisor of coder#547 named two small items in `ARCHITECTURE.md`. This PR
takes them too, after coder#546 and coder#547 landed.

- The Resource Cleanup sketch calls `M.stop()` with no condition. The
real `VimLeavePre` callback runs `stop` only when `M.state.server` is
set, and otherwise clears the @-mention queue
(`lua/claudecode/init.lua:514-525`).
- The I/O bullet says the TCP server "writes with libuv's asynchronous
`write`" and cites nothing for it.

## What changed

**1. The rename.** Nine words in two files. Each "proposed buffer"
becomes "proposal buffer", and nothing else changes (a word-level diff
shows 9 changes of "proposed" to "proposal" and no other change).

| File | Lines | Count |
|---|---|---|
| `README.md` | 254 | 1 |
| `lua/claudecode/README.md` | 181, 182, 183 (twice), 184, 187 (twice),
208 | 8 |

I read each changed sentence in its new form. All nine read correctly,
for example "A write of the proposal buffer (`:w`, `:wq`, `:x`, `ZZ`
...)" and "Both layouts keep the proposal buffer's `'bufhidden'` at
`hide`". The other phrases in these two files already use "proposal"
(`proposal window`, `proposal lines`, `proposal buffers`). `proposed
changes` in `README.md` is a different thing and stays.

**2. Resource Cleanup sketch** (`ARCHITECTURE.md`). The sketch now shows
the `if M.state.server then M.stop() else clear_mention_queue() end` of
the real callback, with its `ClaudeCodeShutdown` group. Every code line
comes from `init.lua:514-525`, except two: the label `-- init.lua,
M.setup (shortened)` and the trailing comment on `M.stop()`, which the
old sketch had and which describes `M.stop` correctly. The other comment
line is the real comment at `init.lua:520`. The lead-in "Automatic
cleanup on shutdown:" had the same unconditional wording, so it now says
that the autocmd that `setup` creates runs `stop` only when the server
runs, and otherwise only clears the queue, with citations. This agrees
with the Performance bullet ("runs `stop` when the server runs").

**3. I/O citation** (`ARCHITECTURE.md`). The write clause now cites
`[lua/claudecode/server/client.lua:write]`. `write` is `local function
write(client, data, callback)` at `client.lua:81`, and it calls
`client.tcp_handle:write` at `:84` and `:90`.

## Scope

The two README files above and the two `ARCHITECTURE.md` items. Left
unchanged on purpose:

- **Other bullets and sketches of `ARCHITECTURE.md`.** Not audited again
here.
- **Code comments and strings under `lua/`** (9 uses of "proposed
buffer" in lowercase, plus `Proposed buffer ID` at `diff.lua:1187`).
They sit in `diff.lua` (8) and `init.lua` (1). Both files are recorded
in `covered.lock`, so a comment edit needs a new record, which is too
much for a wording fix.
- **`fixtures/issue-218/README.md` (2) and
`fixtures/issue-238/README.md` (7).** They describe repro scripts. The
sample output in `fixtures/issue-238/README.md` (`proposed buffer
bufhidden = "hide"`) is what `scripts/repro_issue_238.lua` prints
(`:260` and `:279`). A rename of the prose alone leaves two names in one
README, and a rename of the output changes a script string. They stay as
they are, because the fixture READMEs record what those scripts print.

## Blast Radius

Three Markdown files. Nothing loads them. A wrong sentence here misleads
a reader and breaks no behavior.

## Verification

- Word-level diff of the two READMEs against `main`: exactly 9 changes
of "proposed" to "proposal", no other change.
- `grep` for "proposed buffer" in `README.md`,
`lua/claudecode/README.md` and `ARCHITECTURE.md` finds 0 after the
change.
- The merge of `main` (coder#547 and coder#538) was clean and added no "proposed
buffer" to a README.
- `mise run format-check`: exit 0 (358 files, 0 changed).
- Citation check over the seven READMEs and `ARCHITECTURE.md`: 809
entries (733 citations, 26 relative links and 50 test paths), 1 flagged.
The flagged one is `[plugin/claudecode.lua:pcall(require,
"claudecode")]`, an expression that `main` already cites. A negative
control with three wrong symbols in the new citations flagged all three
(bad 4, then 1 after the restore). The validator matches a plain name
such as `write` only as a whole word anywhere in the file, so I also
confirmed the definitions of `write` (`client.lua:81`) and
`clear_mention_queue` (`init.lua:150`) with `grep`.
- I did not run `mise run all`. The change is documentation only, and no
test, script or CI file reads these files. CI runs the full suite on the
pushed head.
- `git merge-tree --write-tree` of the head and `origin/main` is clean.

---
_Generated with [`xum`](https://github.com/coder/xum) • Model:
`anthropic:claude-sonnet-5-5` • Thinking: `xhigh`_
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ThomasK33