oleks
3c5851e95e
mcp-neovim-server no longer runs as a per-session npx stdio child.
It is now a MetaMCP namespace upstream on emmett (one persistent
process), reached over Streamable-HTTP via the mcp-session-pool:
Claude Code -> pool.localhost:12010/p/neovim/mcp
-> MetaMCP neovim namespace -> mcp-neovim-server -> nvim socket
- .mcp.json: stdio npx server -> streamable-http pool endpoint
- agents/companion.md + skills: tool names are now 3-segment
(mcp__neovim__neovim__vim_*) — the MetaMCP aggregation shape; the
surface description and unavailability runbook updated for the
three-link path (nvim socket / MetaMCP / session)
- README: connection-path diagram
Host side (servers/emmett, deployed separately): neovim added to
services.mcp-session-pool.upstreams; metamcp.nix seeds the neovim
mcp_servers row + mapping and adds nodejs to the unit PATH.
138 lines
6.3 KiB
Markdown
138 lines
6.3 KiB
Markdown
---
|
|
name: claude-code-handoff
|
|
description: |
|
|
Delegate buffer-editing work to the in-editor Claude Code session
|
|
managed by `coder/claudecode.nvim`. Use whenever a request would
|
|
*change code in a buffer*: refactor, generate, explain-and-edit,
|
|
fix a diagnostic. Opens (or focuses) the Claude Code split, attaches
|
|
the relevant buffer/selection, sends an instruction, and tells the
|
|
user how to accept/reject the resulting diff. Avoids duplicating
|
|
Claude Code's diff UX from outside the editor. Trigger on
|
|
"refactor this", "fix this in nvim", "generate the function in this
|
|
buffer", "have Claude edit my file", "send this to Claude in nvim",
|
|
"let Claude in the editor handle it".
|
|
disable-model-invocation: false
|
|
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__neovim__neovim__*
|
|
---
|
|
|
|
# claude-code-handoff — let the in-editor Claude do the editing
|
|
|
|
Owner: `nvim-agentic-companion:companion`. This skill is the bridge
|
|
between *you* (the outer Claude Code session) and the **inner**
|
|
Claude Code session running in the user's nvim via
|
|
`coder/claudecode.nvim`. The inner session has the buffer, selection,
|
|
diagnostics, project root, and the diff-accept/reject UI. It is the
|
|
right tool for any edit that the user should review before it lands.
|
|
|
|
## When this skill fires
|
|
|
|
- The user wants buffer contents *modified*: refactor, rename, fix,
|
|
generate, complete, restructure.
|
|
- The change is bigger than a one-line vim substitute the user could
|
|
do themselves.
|
|
- The user wants a diff to look at before committing.
|
|
|
|
## When this skill does *not* fire
|
|
|
|
- Pure navigation (`editor-act`).
|
|
- Pure questions about state (`editor-introspect`).
|
|
- Edits to *config* files via the declarative NixVim path (those are
|
|
yours to edit with the `Edit` tool, then run `nix run .#deploy`).
|
|
|
|
## The configured keymaps (current NixVim setup)
|
|
|
|
These are defined under `<leader>a*` in
|
|
`/home/oleks/projects/servers/emmett/nixos/neovim.nix`:
|
|
|
|
| Mode | Keys | Command | Purpose |
|
|
| ---- | ------------ | ------------------------ | -------------------------- |
|
|
| n | `<leader>ac` | `:ClaudeCode` | Toggle the Claude split |
|
|
| n | `<leader>af` | `:ClaudeCodeFocus` | Move cursor to the split |
|
|
| n | `<leader>ar` | `:ClaudeCode --resume` | Resume previous session |
|
|
| n | `<leader>aC` | `:ClaudeCode --continue` | Continue last session |
|
|
| n | `<leader>ab` | `:ClaudeCodeAdd %` | Add current buffer |
|
|
| v | `<leader>as` | `:ClaudeCodeSend` | Send visual selection |
|
|
| n | `<leader>aa` | `:ClaudeCodeDiffAccept` | Accept the proposed diff |
|
|
| n | `<leader>ad` | `:ClaudeCodeDiffDeny` | Reject the proposed diff |
|
|
| n | `<leader>am` | `:ClaudeCodeSelectModel` | Pick model for next sess. |
|
|
| n | `<leader>aS` | `:ClaudeCodeStatus` | Check IDE↔Claude link |
|
|
| n | `<leader>aT` | `:ClaudeCodeTreeAdd` | Add file from neo-tree |
|
|
|
|
## The full `:ClaudeCode*` command surface
|
|
|
|
When driving the editor via `mcp__neovim__neovim__vim_command` you have more
|
|
than the keymaps above. The complete set:
|
|
|
|
- `:ClaudeCode` — toggle the terminal split.
|
|
- `:ClaudeCodeFocus` — smart focus/toggle (idempotent).
|
|
- `:ClaudeCodeSelectModel` — model picker, then open terminal.
|
|
- `:ClaudeCodeSend` — send the current visual selection.
|
|
- `:ClaudeCodeAdd <file-path> [start-line] [end-line]` — attach a file
|
|
(or a precise range within it) to the in-editor session's context.
|
|
Use the range form when only part of a large file is relevant.
|
|
- `:ClaudeCodeDiffAccept` / `:ClaudeCodeDiffDeny` — resolve the
|
|
proposed diff in the diff tab.
|
|
- `:ClaudeCodeStatus` — print whether the WebSocket IDE link is alive.
|
|
Use this when the user reports the inner Claude "not seeing" their
|
|
edits.
|
|
- `:ClaudeCodeTreeAdd` — pick the file currently focused in `neo-tree`
|
|
and add it to context.
|
|
|
|
If a future nvim update remaps any of these, prefer `:ClaudeCodeStatus`
|
|
to verify the bridge before debugging further.
|
|
|
|
If the user remaps these, re-introspect via `editor-introspect` before
|
|
quoting them.
|
|
|
|
## Handoff procedure
|
|
|
|
1. **Confirm the split is open.** Either ask `editor-introspect` to
|
|
check for a Claude Code buffer/window, or just run
|
|
`:ClaudeCode` via `mcp__neovim__neovim__vim_command` — the command is
|
|
idempotent (toggles, but if already visible the user sees no
|
|
surprise).
|
|
|
|
2. **Attach the right context.**
|
|
- If a buffer-level change: `:ClaudeCodeAdd %` (current buffer)
|
|
or `:ClaudeCodeAdd <path>` (a specific file).
|
|
- If a selection-level change: the user must have a visual
|
|
selection. If they don't, ask them to make one, *or* offer
|
|
`editor-act` to highlight the relevant range first.
|
|
|
|
3. **Send the instruction.** Phrase it as the user would speak to an
|
|
agent that already has the file open. Example: instead of "in
|
|
neovim.nix add a keymap for ...", say "add a `<leader>tw` keymap
|
|
that toggles wrap, next to the existing wrap-toggle block."
|
|
Send via `:ClaudeCodeSend` (after selection) or by typing the
|
|
prompt into the Claude Code buffer (`mcp__neovim__neovim__vim_command`
|
|
plus an explicit feedkeys is overkill — usually the user can type
|
|
it themselves once focus is in the split).
|
|
|
|
For *partial-file* context (large file, only one function matters)
|
|
prefer `:ClaudeCodeAdd <path> <start> <end>` over sending the
|
|
entire buffer. The inner Claude sees a precise range; cheaper and
|
|
more accurate. Example: `:ClaudeCodeAdd src/foo.rs 120 180`.
|
|
|
|
4. **Brief the user.** One sentence: where the conversation is
|
|
happening (the split), what to expect (a proposed diff), and the
|
|
accept/reject keys. Example:
|
|
> Sent to the Claude Code split. You'll see a proposed diff —
|
|
> `<leader>aa` to accept, `<leader>ad` to reject.
|
|
|
|
5. **Stop.** Don't try to mirror or predict the inner session's
|
|
output. The user will come back with the result, and you can
|
|
resume from there.
|
|
|
|
## Avoiding double-work
|
|
|
|
If the user is already inside the Claude Code split typing to the
|
|
inner session, **do not also try to do the edit yourself**. Either:
|
|
|
|
- Stay quiet on the editing question and only handle introspection
|
|
/ navigation side requests, or
|
|
- Acknowledge: "the inner Claude is on it — ping me back if it
|
|
stalls or you want a second opinion."
|
|
|
|
The whole point of the handoff is to avoid two agents editing the
|
|
same buffer with different mental models.
|