# 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

```text
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.