nvim-control 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08c676f066c44ce25e9ad128f91a2dd67580a159562e2b2a4b3e63715fb09d09'
+  data.tar.gz: dd970515d69b6eaf5689b0b210e91727fa3e150e5cd0a83df2109a7a5fab412c
+SHA512:
+  metadata.gz: 9159f7f3a2588fcd78e5b4adf116957929a0592d032b7ee646a194e69e91b612e454e3a82fc27d074152d38363cb1a1026001c40788243473e89304d798e3043
+  data.tar.gz: 6e4bd4ebac7638f01180fa1c871969046fd1f9e05e328fd3a15aeadefb3a1be537c86e2842131a7be720b6a66d8c92c7517921155bc6dead9607322dbba5b532

data/AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+## Project overview
+`nvim-control` is a Ruby gem that bridges running Neovim instances and agentic
+coding tools. By default, it extracts live context from the editor via a Unix
+socket connection and outputs JSON with cursor position, current file, visual
+selection and diagnostics. It can also run explicit control actions, such as Ex
+commands and key input, against the running editor.
+
+**Version**: 1.0.0
+**Ruby**: >= 4.0.0
+**Dependencies**: `neovim` gem (~> 0.10.0), `logger` gem (~> 1.7)
+
+## Commands
+- **Test all**: `bundle exec rspec`
+- **Test unit**: `bundle exec rspec --exclude-pattern "spec/integration/**/*"`
+- **Test integration**: `bundle exec rspec spec/integration/`
+- **Test single file**: `bundle exec rspec path/to/spec.rb`
+- **Lint**: `bundle exec rubocop`
+- **Run tool**: `bin/nvim-control`
+- **Build gem**: `gem build nvim-control.gemspec`
+
+## Architecture
+### Entry point
+`bin/nvim-control` - CLI executable that dispatches to `NvimControl::CLI.run`
+and prints JSON to stdout.
+
+### Core components (`lib/nvim_control/`)
+- `cli.rb` - Parses arguments and dispatches to the read flow (`Fetcher`) or a
+  control action (`Controller`)
+- `fetcher.rb` - Read flow with a static `fetch` method. Orchestrates data
+  extraction, handles all error types, and returns JSON responses
+- `controller.rb` - Control flow that runs explicit Ex commands or key input
+  against Neovim and returns JSON with a `context_after` snapshot
+- `connector.rb` - Manages Neovim socket connection using the `neovim` gem.
+  Reads socket path from `NVIM_CONTROL_SOCKET` env var or defaults to
+  `nvim-control.sock` in current directory
+- `data_extractor.rb` - Static methods to extract cursor position, current file
+  path, visual selection (with text content), and diagnostics from Neovim
+- `errors.rb` - Custom error classes: `ConnectionError` (socket failures) and
+  `OperationError` (Neovim operation failures)
+- `version.rb` - Gem version constant
+
+### Data Flow
+1. User runs `nvim-control` CLI
+2. `CLI.run` dispatches to `Fetcher.fetch` (read) or `Controller.run` (control)
+3. `Connector` attaches to Neovim via Unix socket
+4. `DataExtractor` methods query Neovim for context data
+5. JSON output returned to stdout (or error JSON on failure)
+
+### JSON output format
+Success:
+```json
+{
+  "cursor": { "line": 43, "col": 3 },
+  "file": "/path/to/file.rb",
+  "selection": null,
+  "diagnostics": []
+}
+```
+
+Error:
+```json
+{
+  "error": "Connection failed",
+  "details": "Failed to connect to Neovim socket: No such file"
+}
+```
+
+## Code style
+- Ruby 4.0, line length max 80 chars
+- Use double quotes for strings, frozen string literals enabled
+- Classes in `NvimControl` module with descriptive names
+- Private constants at class bottom with `private_constant`
+- Error handling with custom error classes in `errors.rb`
+- Use `attr_reader` for private instance variables
+- RSpec with expect syntax, monkey patching disabled
+- Follow Rubocop rules in `.rubocop.yml`
+
+## Testing
+- Unit tests mock the Neovim client
+- Integration tests require a running Neovim instance with socket
+- Test files mirror lib structure: `spec/lib/nvim_control/`
+
+## Integration examples
+The gem is designed for use with agentic coding tools like Claude Code,
+OpenCode, Amp Code, Codex, and Gemini. See README.md for integration examples
+including Claude Code skill configuration and OpenCode custom tool setup.

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+# 1.0.0
+- Initial release.

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 Mathias Jean Johansen
+
+Permission to use, copy, modify, and distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/MIGRATION.md

@@ -0,0 +1,239 @@
+# Migration guide: `nvim-context` → `nvim-control`
+
+A step-by-step runbook to publish the renamed gem, deprecate the old one,
+rename the GitHub repo, and rewire your dotfiles. Ordered to minimise the
+window where tooling is broken.
+
+> This is a working artifact. Delete it when done — do not commit it to the
+> repo.
+
+---
+
+## 0. Pre-flight (do these first)
+
+1. **Push the branch work to `main`** (you have 10 unpushed commits):
+   ```sh
+   cd ~/Code/majjoha/nvim-context
+   git log --format='%G? %h %s' origin/main..HEAD   # confirm all signed (G)
+   git push origin main
+   ```
+2. **Confirm RubyGems ownership of the old gem** (needed for deprecation):
+   ```sh
+   gem signin                 # if not already signed in
+   gem owner nvim-context     # confirm your email is listed
+   ```
+3. **Confirm the gem name is free** (should be — verified earlier):
+   ```sh
+   gem list -r -e nvim-control   # expect no remote match
+   ```
+
+---
+
+## 1. Rename the GitHub repository
+
+GitHub auto-redirects the old URL, but you should update the remote.
+
+1. Rename via the API (or Settings → rename in the web UI):
+   ```sh
+   gh repo rename nvim-control --repo majjoha/nvim-context
+   ```
+2. Update your local remote:
+   ```sh
+   cd ~/Code/majjoha/nvim-context
+   git remote set-url origin git@github.com:majjoha/nvim-control.git
+   git remote -v   # confirm
+   ```
+3. **Optionally rename the local working directory** to match (cosmetic):
+   ```sh
+   cd ~/Code/majjoha
+   mv nvim-context nvim-control
+   ```
+   If you do this, update any shell bookmarks / mise trust paths that point
+   at the old directory.
+
+> GitHub keeps a redirect from `majjoha/nvim-context` → `majjoha/nvim-control`,
+> so the README's `gh`/marketplace URLs and the CI badge resolve either way.
+> The redirect breaks only if someone later creates a NEW repo at the old
+> name — unlikely for a personal namespace.
+
+---
+
+## 2. Publish the new gem (`nvim-control`)
+
+1. Build from a clean checkout (active Ruby must be 4.0.5):
+   ```sh
+   cd ~/Code/majjoha/nvim-control      # or nvim-context if you didn't rename
+   ruby -v                              # expect 4.0.5
+   gem build nvim-control.gemspec       # → nvim-control-1.0.0.gem
+   ```
+2. Push to RubyGems:
+   ```sh
+   gem push nvim-control-1.0.0.gem
+   ```
+   - If you have MFA on (the gemspec sets `rubygems_mfa_required`), you'll be
+     prompted for an OTP.
+3. Verify:
+   ```sh
+   gem list -r -e nvim-control          # shows 1.0.0
+   ```
+4. Clean up the local artifact (it's gitignored, but tidy anyway):
+   ```sh
+   trash nvim-control-1.0.0.gem
+   ```
+
+---
+
+## 3. Deprecate / archive the old gem (`nvim-context`)
+
+You cannot delete a published gem version after 30 minutes, and `yank`
+should be reserved for broken releases — not renames. Two non-destructive
+options; **A is recommended.**
+
+### Option A — Deprecation release (recommended)
+Publish one final `nvim-context` version whose post-install message points
+users to `nvim-control`. This keeps existing installs working while signalling
+the move.
+
+1. In a scratch copy of the OLD gem (e.g. `git stash` aside or a tag checkout),
+   bump the version to `1.0.1` and add a `post_install_message` to the
+   gemspec:
+   ```ruby
+   s.version = "1.0.1"
+   s.post_install_message = <<~MSG
+     nvim-context has been renamed to nvim-control.
+     Please switch: gem install nvim-control
+     See https://github.com/majjoha/nvim-control
+   MSG
+   ```
+2. Build and push that `1.0.1`:
+   ```sh
+   gem build nvim-context.gemspec
+   gem push nvim-context-1.0.1.gem
+   ```
+
+### Option B — Yank (only if you want it gone from installs)
+```sh
+gem yank nvim-context -v 1.0.0
+```
+This removes 1.0.0 from the index (anyone with it stays working, but new
+installs fail). Use ONLY if you're sure nothing depends on it. Not reversible
+to the same version number.
+
+> Recommendation: **Option A.** It's the polite, non-breaking path for a
+> rename and matches ecosystem convention.
+
+---
+
+## 4. Rewire your dotfiles
+
+Your dotfiles (`~/.dotfiles`, a git repo on `main`) reference the old name in
+7 active spots. Do this AFTER step 2 (the new gem must be published, since the
+mise `gem:` backend installs from RubyGems).
+
+### 4a. mise (the gem install)
+`~/.dotfiles/.config/mise/config.toml` line 41:
+```diff
+- "gem:nvim-context" = "latest"
++ "gem:nvim-control" = "latest"
+```
+Then re-resolve and install:
+```sh
+cd ~/.dotfiles
+mise install          # installs gem:nvim-control, drops gem:nvim-context
+mise uninstall "gem:nvim-context@1.0.0"   # remove the old one if it lingers
+```
+The `mise.lock` entries (lines ~1237-1239) update automatically on
+`mise install`; commit the regenerated lock.
+
+Verify the binary resolves globally now:
+```sh
+which nvim-control    # should resolve via mise's gem-backend bindir
+nvim-control read     # connection-error JSON is fine (no socket)
+```
+
+### 4b. OpenCode command file
+Rename the command so the slash-command matches:
+```sh
+cd ~/.dotfiles/.config/opencode/command
+git mv nvim-context.md nvim-control.md
+```
+Edit `nvim-control.md` body: `!`nvim-context`` → `!`nvim-control``.
+
+### 4c. Neovim tmux-agent
+`~/.dotfiles/.config/nvim/lua/tmux_agent.lua:208`:
+```diff
+- M.send_text("/nvim-context " .. query)
++ M.send_text("/nvim-control " .. query)
+```
+(This sends a slash-command; ensure the OpenCode command rename in 4b matches.)
+
+### 4d. Agent instructions + walkthrough skill
+- `~/.dotfiles/.config/agents/AGENTS.md:290` — `nvim-context` → `nvim-control`.
+- `~/.dotfiles/.config/agents/skills/walkthrough/SKILL.md` — 4 spots:
+  - line 13: `Bash(nvim-context *)` → `Bash(nvim-control *)`
+  - line 34: `nvim-context read` → `nvim-control read`
+  - line 39: `NVIM_CONTEXT_SOCKET` → `NVIM_CONTROL_SOCKET`
+  - line 115: `nvim-context ex "..."` → `nvim-control ex "..."`
+- `~/.dotfiles/.config/agents/skills/walkthrough/scripts/walkthrough-goto.sh`
+  — lines 70, 83, 84: `nvim-context` → `nvim-control`.
+
+### 4e. Claude permissions
+`~/.dotfiles/.claude/settings.json:45`:
+```diff
+- "Bash(nvim-context:*)",
++ "Bash(nvim-control:*)",
+```
+
+### 4f. The `v` socket function and `nvim-control.sock`
+Already updated to `nvim-control.sock` in `~/.dotfiles/.config/zsh/aliases.zsh`
+(checked earlier — no change needed). Confirm the `v` function and the
+jump-to-server `find ... -name nvim-control.sock` still match.
+
+> Bulk option for 4c-4e (review the diff before committing):
+> ```sh
+> cd ~/.dotfiles
+> grep -rIl 'nvim-context\|nvim_context\|NVIM_CONTEXT' .config .claude/settings.json \
+>   | grep -v '.claude/plans/' \
+>   | xargs sed -i '' \
+>       -e 's/nvim-context/nvim-control/g' \
+>       -e 's/NVIM_CONTEXT_SOCKET/NVIM_CONTROL_SOCKET/g'
+> ```
+> Then handle the file RENAMES (4b) separately with `git mv`, and re-read the
+> diff — sed is blunt; verify nothing unintended changed (e.g. prose).
+
+### 4g. Disposable plan file (skip)
+`~/.dotfiles/.claude/plans/jaunty-seeking-sifakis.md` references the old name
+but is a disposable planning artifact — leave it or delete it; don't bother
+rewriting.
+
+### 4h. Commit the dotfiles
+```sh
+cd ~/.dotfiles
+git add -A
+git status          # review — confirm no stray changes
+git commit -m "Rename nvim-context references to nvim-control."
+```
+
+---
+
+## 5. Verify end to end
+
+```sh
+# In a project dir, start a server and exercise the tool by name:
+cd ~/some-project
+nvim --listen "$PWD/nvim-control.sock" &      # or use your `v` function
+NVIM_CONTROL_SOCKET="$PWD/nvim-control.sock" nvim-control read
+NVIM_CONTROL_SOCKET="$PWD/nvim-control.sock" nvim-control ex "echo 'hi'"
+```
+Both should return JSON. Then confirm the agent skills resolve the new
+binary (run a walkthrough / tmux-agent flow).
+
+---
+
+## Order summary (why this sequence)
+1. Push commits → 2. Rename repo → 3. Publish new gem → 4. Deprecate old gem
+→ 5. Rewire dotfiles (needs new gem live) → 6. Verify.
+
+The only hard dependency: **dotfiles mise rewire (4a) requires the new gem
+published (step 2)**, because the `gem:` backend pulls from RubyGems. Repo
+rename (1) and gem publish (2) are independent and can swap order.

data/README.md

@@ -0,0 +1,197 @@
+# `nvim-control`
+![CI](https://github.com/majjoha/nvim-control/workflows/CI/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/nvim-control.svg)](
+https://badge.fury.io/rb/nvim-control)
+
+`nvim-control` is a bridge between running Neovim instances and agentic coding
+tools. By default, it extracts context from the editor via a Unix socket
+connection and outputs JSON with the cursor position, current file, visual
+selection and diagnostics. It can also execute explicit control actions such as
+running Ex commands or sending key input back to Neovim.
+
+It allows agentic coding tools running outside Neovim to answer questions such
+as:
+- What does this line do?
+- Can you convert the current line to uppercase?
+- What does the method under my cursor do?
+- Are these lines idiomatic Ruby?
+
+## Motivation
+While the Neovim community provides several plugins for integrating agentic
+coding assistants into the editor (see the [AI section in the Awesome Neovim
+repository](https://github.com/rockerboo/awesome-neovim?tab=readme-ov-file#ai)),
+it seems that few tools offer a way to let any agentic coding tool running
+*outside* Neovim retrieve the state of the editor in an agnostic manner.
+
+The goal with `nvim-control` is to separate concerns, so Amp Code, Claude Code,
+Codex, etc., can query the current state of a Neovim session by calling this
+tool. When editor mutations are needed, they must go through explicit control
+subcommands instead of piggybacking on the default read-only flow. See the
+[Integration with agentic tools](#integration-with-agentic-tools) section below
+for suggestions on how to set this up.
+
+## Installation
+```sh
+gem install nvim-control
+```
+
+## Setup
+When starting Neovim ensure that you open it using the `--listen` flag and pass
+a path to the socket as follows:
+
+```sh
+nvim --listen $(pwd)/nvim-control.sock
+```
+
+Alternatively, you can set the `NVIM_CONTROL_SOCKET` environment variable to
+specify the socket path:
+
+```sh
+export NVIM_CONTROL_SOCKET=/tmp/nvim-control.sock
+nvim --listen $NVIM_CONTROL_SOCKET
+```
+
+If no environment variable is set, the tool defaults to `nvim-control.sock` in
+the current directory.
+
+## Usage
+### Read context
+Once Neovim is running, you can retrieve the current context by running
+`nvim-control` or `nvim-control read`.
+
+This will output JSON containing the current file, cursor position, visual
+selection (if any), and diagnostics in this format:
+
+```json
+{
+  "cursor": {
+    "line": 43,
+    "col": 3
+  },
+  "file": "/path/to/current/file.rb",
+  "selection": null,
+  "diagnostics": []
+}
+```
+
+### Control Neovim explicitly
+Control actions are opt-in subcommands. They also return JSON, including a
+`context_after` snapshot so agents can verify what changed.
+
+Supported control subcommands:
+- `nvim-control ex "..."` runs an Ex command.
+- `nvim-control keys "..."` sends raw key input.
+
+Example response:
+```json
+{
+  "ok": true,
+  "action": "ex",
+  "command": "write",
+  "result": null,
+  "context_after": {
+    "cursor": { "line": 43, "col": 3 },
+    "file": "/path/to/current/file.rb",
+    "selection": null,
+    "diagnostics": []
+  }
+}
+```
+
+### Useful examples
+Read the current editor state:
+```sh
+nvim-control
+```
+
+Save the current buffer:
+```sh
+nvim-control ex "write"
+```
+
+Open the quickfix list after diagnostics or a grep:
+```sh
+nvim-control ex "copen"
+```
+
+Open a vertical split:
+```sh
+nvim-control ex "vsplit"
+```
+
+Open a diff split against another file:
+```sh
+nvim-control ex "diffsplit other.rb"
+```
+
+Send keys to write the file from command-line mode:
+```sh
+nvim-control keys $':write\r'
+```
+
+Send keys to open the quickfix list:
+```sh
+nvim-control keys $':copen\r'
+```
+
+### Integration with agentic tools
+#### Amp Code
+```sh
+amp skill add majjoha/nvim-control/nvim-read
+amp skill add majjoha/nvim-control/nvim-control
+```
+
+#### Claude Code
+```sh
+# Add the repository as a marketplace
+/plugin marketplace add majjoha/nvim-control
+
+# Install the plugin
+/plugin install nvim-control@nvim-control
+```
+
+The plugin provides the `nvim-read` skill which gives Claude Code access to
+your live Neovim editor state. Install the `nvim-control` skill as well if you
+want the agent to run explicit Neovim commands.
+
+#### Codex
+```sh
+$skill-installer install \
+  https://github.com/majjoha/nvim-control/tree/main/.codex/skills/nvim-read
+$skill-installer install \
+  https://github.com/majjoha/nvim-control/tree/main/.codex/skills/nvim-control
+```
+
+#### Gemini
+TBD.
+
+#### OpenCode
+<details>
+<summary><code>~/.config/opencode/command/nvim-read.md</code></summary>
+<pre>
+---
+description: Show current Neovim context
+---
+
+!`nvim-control`
+</pre>
+</details>
+
+<details>
+<summary><code>~/.config/opencode/command/nvim-control.md</code></summary>
+<pre>
+---
+description: Run an explicit Neovim control command
+---
+
+!`nvim-control ex "$ARGUMENTS"`
+</pre>
+</details>
+
+## Disclaimer
+Since building software with AI can still be divisive, it might be worth
+pointing out here that `nvim-control` itself has been built using OpenCode and
+Claude Code, but with human guidance and continuous review of its work.
+
+## License
+See [LICENSE](https://github.com/majjoha/nvim-control/blob/main/LICENSE).

data/bin/nvim-control

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require_relative "../lib/nvim_control"
+
+exit(NvimControl::CLI.run(argv: ARGV))

data/lib/nvim_control/cli.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module NvimControl
+  class CLI
+    class << self
+      def run(argv:, stdout: $stdout)
+        case argv
+        in [] | [READ_ACTION]
+          read_context(stdout: stdout)
+        in [action, payload] if Controller.supported_action?(action)
+          run_control(action: action, payload: payload, stdout: stdout)
+        else
+          write_invalid_arguments(stdout: stdout)
+        end
+      end
+
+      private
+
+      def read_context(stdout:)
+        write_response(Fetcher.fetch, stdout: stdout)
+      end
+
+      def run_control(action:, payload:, stdout:)
+        response = Controller.run(action: action, payload: payload)
+
+        write_response(response, stdout: stdout)
+      end
+
+      def write_invalid_arguments(stdout:)
+        stdout.puts(
+          JSON.generate(
+            ok: false,
+            error: "Invalid arguments",
+            details: usage
+          )
+        )
+        ERROR_EXIT_CODE
+      end
+
+      def write_response(response, stdout:)
+        stdout.puts(response)
+
+        successful_response?(response) ? SUCCESS_EXIT_CODE : ERROR_EXIT_CODE
+      end
+
+      def successful_response?(response)
+        payload = JSON.parse(response)
+
+        return false unless payload.is_a?(Hash)
+        return false if payload.key?("error")
+        return false if payload["ok"] == false
+
+        true
+      rescue JSON::ParserError
+        false
+      end
+
+      def usage
+        actions = ([READ_ACTION] + Controller.supported_actions).join("|")
+
+        "Usage: nvim-control [#{actions}] [payload]"
+      end
+
+      READ_ACTION = "read"
+      SUCCESS_EXIT_CODE = 0
+      ERROR_EXIT_CODE = 1
+      private_constant :READ_ACTION,
+                       :SUCCESS_EXIT_CODE,
+                       :ERROR_EXIT_CODE
+    end
+  end
+end

data/lib/nvim_control/connector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "neovim"
+
+module NvimControl
+  class Connector
+    def initialize(client: nil)
+      @socket_path = ENV["NVIM_CONTROL_SOCKET"] || DEFAULT_SOCKET_PATH
+      @client = client || begin
+        Neovim.attach_unix(socket_path)
+      rescue StandardError => e
+        raise ConnectionError,
+              "Failed to connect to Neovim socket: #{e.message}",
+              e.backtrace
+      end
+    end
+
+    def connect
+      yield client if block_given?
+    rescue StandardError => e
+      raise OperationError,
+            "Failed during Neovim operation: #{e.message}",
+            e.backtrace
+    end
+
+    private
+
+    attr_reader :client, :socket_path
+
+    DEFAULT_SOCKET_PATH = File.expand_path("nvim-control.sock")
+    private_constant :DEFAULT_SOCKET_PATH
+  end
+end

data/lib/nvim_control/controller.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+
+module NvimControl
+  class Controller
+    class << self
+      def run(action:, payload:)
+        return invalid_action_response unless supported_action?(action)
+
+        JSON.generate(action_response(action: action, payload: payload))
+      rescue ConnectionError => e
+        format_error("Connection failed", e.message)
+      rescue OperationError => e
+        format_error("Control action failed", e.message)
+      rescue StandardError => e
+        format_error("Unexpected error", e.message)
+      end
+
+      def supported_action?(action)
+        ACTIONS.key?(action)
+      end
+
+      def supported_actions
+        ACTIONS.keys
+      end
+
+      private
+
+      def action_response(action:, payload:)
+        Connector.new.connect do |client|
+          execute_action(client: client, action: action, payload: payload)
+        end
+      end
+
+      def execute_action(client:, action:, payload:)
+        action_metadata = ACTIONS.fetch(action)
+
+        {
+          ok: true,
+          action: action,
+          action_metadata.fetch(:payload_key) => payload,
+          result: action_metadata.fetch(:runner).call(client, payload),
+          context_after: DataExtractor.context(client: client)
+        }
+      end
+
+      def invalid_action_response
+        JSON.generate(
+          ok: false,
+          error: "Unsupported action",
+          details: "Supported actions: #{supported_actions.join(', ')}"
+        )
+      end
+
+      def format_error(error, details)
+        JSON.generate({ ok: false, error: error, details: details })
+      end
+
+      ACTIONS = {
+        "ex" => {
+          payload_key: :command,
+          runner: ->(client, payload) { client.command(payload) }
+        }.freeze,
+        "keys" => {
+          payload_key: :keys,
+          runner: ->(client, payload) { client.input(payload) }
+        }.freeze
+      }.freeze
+      private_constant :ACTIONS
+    end
+  end
+end

data/lib/nvim_control/data_extractor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module NvimControl
+  class DataExtractor
+    def self.context(client:)
+      {
+        cursor: cursor(client: client),
+        file: file(client: client),
+        selection: visual_selection(client: client),
+        diagnostics: diagnostics(client: client)
+      }
+    end
+
+    def self.cursor(client:)
+      cursor = client.current.window.cursor
+      { line: cursor[0], col: cursor[1] }
+    rescue StandardError => e
+      raise OperationError,
+            "Failed to get cursor info: #{e.message}",
+            e.backtrace
+    end
+
+    def self.file(client:)
+      client.current.buffer.name
+    rescue StandardError => e
+      raise OperationError,
+            "Failed to get file info: #{e.message}",
+            e.backtrace
+    end
+
+    def self.visual_selection(client:)
+      return nil unless visual_mode?(client)
+
+      marks = visual_marks(client)
+      text = selected_text(client, marks)
+      build_selection_info(marks, text)
+    rescue StandardError
+      nil
+    end
+
+    def self.diagnostics(client:)
+      client.eval("vim.diagnostic.get(0)").map do |diagnostic|
+        {
+          line: diagnostic["lnum"] + 1,
+          col: diagnostic["col"] + 1,
+          message: diagnostic["message"],
+          severity: diagnostic["severity"]
+        }
+      end
+    rescue StandardError
+      []
+    end
+
+    class << self
+      private
+
+      VISUAL_BLOCK_MODE = "\x16"
+      private_constant :VISUAL_BLOCK_MODE
+
+      def visual_mode?(client)
+        ["v", "V", VISUAL_BLOCK_MODE].include?(client.eval("mode()"))
+      end
+
+      def visual_marks(client)
+        {
+          start: client.eval("getpos(\"'<\")"),
+          end: client.eval("getpos(\"'>\")")
+        }
+      end
+
+      def selected_text(client, marks)
+        start_line = marks[:start][1]
+        end_line = marks[:end][1]
+        client.current.buffer.get_lines(start_line - 1, end_line, true)
+      end
+
+      def build_selection_info(marks, text)
+        {
+          start: { line: marks[:start][1], col: marks[:start][2] },
+          end: { line: marks[:end][1], col: marks[:end][2] },
+          text: text.join("\n")
+        }
+      end
+    end
+  end
+end

data/lib/nvim_control/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module NvimControl
+  class ConnectionError < StandardError; end
+  class OperationError < StandardError; end
+end

data/lib/nvim_control/fetcher.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module NvimControl
+  class Fetcher
+    class << self
+      def fetch
+        context = build_context
+        JSON.generate(context)
+      rescue ConnectionError => e
+        format_error("Connection failed", e.message)
+      rescue OperationError => e
+        format_error("Context extraction failed", e.message)
+      rescue StandardError => e
+        format_error("Unexpected error", e.message)
+      end
+
+      private
+
+      def build_context
+        Connector.new.connect { |client| DataExtractor.context(client: client) }
+      end
+
+      def format_error(error, details)
+        JSON.generate({ error: error, details: details })
+      end
+    end
+  end
+end

data/lib/nvim_control/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NvimControl
+  VERSION = "1.0.0"
+end

data/lib/nvim_control.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "nvim_control/errors"
+require_relative "nvim_control/connector"
+require_relative "nvim_control/fetcher"
+require_relative "nvim_control/data_extractor"
+require_relative "nvim_control/controller"
+require_relative "nvim_control/cli"
+require_relative "nvim_control/version"
+
+module NvimControl
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: nvim-control
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mathias Jean Johansen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: neovim
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: |
+  `nvim-control` bridges running Neovim instances and agentic coding tools
+  via Unix socket connections. It reads live editor state (cursor position,
+  current file, visual selections, and diagnostics) as JSON and runs explicit
+  control actions such as Ex commands and key input. This lets agents both
+  answer questions like "What does this line do?" and drive the editor on
+  request.
+email: mathias@mjj.io
+executables:
+- nvim-control
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE
+- MIGRATION.md
+- README.md
+- bin/nvim-control
+- lib/nvim_control.rb
+- lib/nvim_control/cli.rb
+- lib/nvim_control/connector.rb
+- lib/nvim_control/controller.rb
+- lib/nvim_control/data_extractor.rb
+- lib/nvim_control/errors.rb
+- lib/nvim_control/fetcher.rb
+- lib/nvim_control/version.rb
+homepage: https://github.com/majjoha/nvim-control
+licenses:
+- ISC
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/majjoha/nvim-control
+  changelog_uri: https://github.com/majjoha/nvim-control/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/majjoha/nvim-control/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Bridge between running Neovim instances and agentic coding tools.
+test_files: []