claude-plugin-nvim-agentic/DEPENDENCIES.md

Dependencies

This plugin bundles nothing. It ships only configuration — plugin.json, .mcp.json, one agent, three skills — and ties together a chain of components that must already exist on the system. The README says it plainly: "This plugin doesn't ship those — it depends on them."

The plugin's only direct dependency is the mcp-session-pool endpoint in .mcp.json (http://pool.localhost:12010/p/neovim/mcp). Everything else listed here is what makes that endpoint actually return the vim_* tools.

Connection path

Claude Code session
  └─ .mcp.json → http://pool.localhost:12010/p/neovim/mcp   (Streamable-HTTP)
       └─ mcp-session-pool (:12010, M=1 session pooler, /repin endpoint)
            └─ nvim-mcp-bridge — supergateway (:12016, --stateful)
                 └─ mcp-neovim-server (stdio child)
                      └─ /run/user/1000/nvim.sock           (nvim msgpack-RPC)
                           └─ the running Neovim

Editor side

Dependency	Role	Notes
Neovim	The target editor the companion reads and drives.	Must run with an RPC socket (serverstart → /run/user/1000/nvim.sock, via NixVim extraConfigLuaPre). Requires ≥ 0.10 — the editor-introspect skill uses vim.fn.getregion.
coder/claudecode.nvim	Neovim plugin loaded inside nvim.	Provides the :ClaudeCode* commands and <leader>a* keymaps that claude-code-handoff drives. Without it the handoff skill has nothing to delegate to.

MCP bridge chain (emmett systemd services)

Dependency	Role	Notes
mcp-neovim-server	stdio MCP server that attaches to nvim's msgpack-RPC socket and exposes the vim_* tools.	npm package, fetched on demand via npx -y mcp-neovim-server. Reads NVIM_SOCKET_PATH.
supergateway	Wraps the stdio mcp-neovim-server as a Streamable-HTTP endpoint.	npm package, fetched via npx -y supergateway. Run --stateful so the pool has a session to pin.
Node.js / npx	Runtime for the two npm packages above.	The only hard install of the chain — npx -y fetches the packages themselves on demand.
mcp-session-pool	M=1 session pooler on :12010. The single endpoint .mcp.json targets.	Bridges sessionless clients (Claude Code) to the sessionful bridge upstream; re-pins via /pools/neovim/repin. Defined under ~/projects/servers/emmett/mcp-session-pool/.
nvim-mcp-bridge	Socket-gated systemd service (:12016) supervising supergateway + mcp-neovim-server.	Started by a systemd.path inotify watch on the nvim socket; stops when the socket disappears. Defined in ~/projects/servers/emmett/nixos/nvim-mcp-bridge.nix.

Helpers the bridge service shells out to

Dependency	Role
inotify-tools (inotifywait)	Watches the nvim socket; the bridge exits when the socket is deleted (nvim quit).
curl	The bridge's ExecStartPost POSTs /pools/neovim/repin to the pool.
bash + coreutils	The bridge unit's PATH — npm spawns sh.

Outer

Dependency	Role	Notes
claude CLI (Claude Code)	Hosts this plugin.	neovim.nix also launches the in-editor session as claude --agent nvim-agentic:companion (coder/claudecode.nvim's terminal_cmd).

Host assumption

The pool and bridge run as systemd services under user oleks on emmett (the local laptop), so the per-user nvim socket at /run/user/1000/nvim.sock is directly reachable. The pool.localhost hostname is an /etc/hosts alias (127.0.0.1) set in ~/projects/servers/emmett/nixos/configuration.nix.

Diagnosing a missing chain

If the vim_* tools are absent from a Claude Code session, walk the three breakable links in order:

1. nvim — running, and did it create the socket at {{nvim_socket}}? (ls it.) No socket ⇒ restart nvim.
2. bridge / pool — systemctl status nvim-mcp-bridge; pool status at http://127.0.0.1:12010/pools/neovim.
3. this session — MCP servers attach once, at claude launch. A session started before the bridge was up never registers the tools ⇒ restart Claude Code.