nvim-context 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 854123562b94edd4488ded7a4f3614643ce7d850d87d7b9d40f0a4b98ae6a3b2
+  data.tar.gz: b4e831ff07e923e76657f89ac80e5fd81832260d7a677564f1f48210134cafee
+SHA512:
+  metadata.gz: 2f15ad5f0c76d4f62216b66e6e9153e53816288abd33016d9b5dbf6be0e3218a4fef3708a66f2027cc10c6148cd99bc9b84d61e2fb9572e371563adf4417d59d
+  data.tar.gz: e73ce86f7c1aef21dc030b4346483953d63fa240f5c8ff6a199ac32e0e5660764819d14b12a9ef29f4eaf338ae07ed1164f017045520bc9c3faf293b31d126af

data/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## 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`
+- **Ruby version**: 3.4.7
+
+## Code Style
+- Target Ruby 3.4, line length max 80 chars
+- Use double quotes for strings, frozen string literals
+- Classes in `NvimContext` 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 attributes
+- RSpec with expect syntax, disable monkey patching

data/CHANGELOG.md

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

data/CLAUDE.md

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## 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-context`
+
+## Architecture
+This gem extracts context from a running Neovim instance via Unix socket
+connection. It outputs JSON with cursor position, current file, visual
+selection, and LSP diagnostics.
+
+### Core Components
+- `Connector` - Manages Neovim socket connection using the `neovim` gem. Uses
+  `NVIM_CONTEXT_SOCKET` env var or defaults to `nvim-context.sock`
+- `Fetcher` - Entry point that orchestrates data extraction and returns JSON.
+  Handles all error types and formats error responses
+- `DataExtractor` - Static methods to extract cursor, file, selection, and
+  diagnostics from Neovim client
+
+### Error Handling
+Custom errors in `errors.rb`: `ConnectionError` (socket failures) and
+`ContextError` (Neovim operation failures). Fetcher catches all errors and
+returns JSON error objects.
+
+## Code Style
+- Ruby 3.4, line length max 80 chars
+- Double quotes for strings, frozen string literals not enforced by Rubocop
+- Classes in `NvimContext` module
+- Private constants at class bottom with `private_constant`
+- Use `attr_reader` for private attributes
+- RSpec with expect syntax, monkey patching disabled

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2025 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/README.md

@@ -0,0 +1,170 @@
+# `nvim-context`
+![CI](https://github.com/majjoha/nvim-context/workflows/CI/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/nvim-context.svg)](https://badge.fury.io/rb/nvim-context)
+`nvim-context` is a bridge between running Neovim instances and agentic coding
+tools. 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 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?
+- 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 in an agnostic manner.
+
+The goal with `nvim-context` is to separate concerns, so OpenCode, Claude Code,
+Codex, Gemini, etc., can query the current state of a Neovim session by calling
+this tool. 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-context
+```
+
+## 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-context.sock
+```
+
+Alternatively, you can set the `NVIM_CONTEXT_SOCKET` environment variable to
+specify the socket path:
+
+```sh
+export NVIM_CONTEXT_SOCKET=/tmp/nvim-context.sock
+nvim --listen $NVIM_CONTEXT_SOCKET
+```
+
+If no environment variable is set, the tool defaults to `nvim-context.sock` in
+the current directory.
+
+> [!NOTE]  
+> To avoid cluttering your Git repository, consider adding `nvim-context.sock`
+> to your `.gitignore` file.
+
+## Usage
+Once Neovim is running, you can retrieve the current context by running
+`nvim-context`.
+
+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": []
+}
+```
+```
+
+### Integration with agentic tools
+#### Amp Code
+
+#### Claude Code
+<details>
+<summary>`~/.claude/skills/nvim-context/SKILL.md`</summary>
+```md
+---
+name: nvim-context
+description: Get the current Neovim context as JSON (cursor position, current
+file, visual selection and diagnostics) to help answer questions about code at
+the current cursor position, visual selections and diagnostics. Use when users
+ask about "this line", "current file", "selection" or need context about their
+Neovim editor state.
+---
+
+# Neovim context provider
+## Purpose
+Provides live context from the user's Neovim editor session to help answer
+context-aware questions about code.
+
+## How it works
+1. Executes the `nvim-context` tool to get the current editor state.
+2. Returns JSON data including cursor position, open file, visual selection and
+   diagnostics.
+3. Use this information to understand references like "this line", "the
+   selection", "current file", etc.
+
+## Usage examples
+- "What's wrong with this line?" → Check diagnostics at cursor
+- "Explain the selected code" → Analyze visual selection
+- "What file am I in?" → Return current file path
+- "Show me all errors" → List all LSP diagnostics
+
+## Technical Details
+The skill runs: `/Users/mathias/Dropbox/Kode/Ruby/nvim-context/bin/nvim-context`
+
+This provides JSON output like:
+```json
+{
+  "cursor": {
+    "line": 43,
+    "col": 3
+  },
+  "file": "/path/to/current/file.rb",
+  "selection": null,
+  "diagnostics": []
+}
+```
+```
+</details>
+
+### Codex
+TBD.
+
+#### Gemini
+TBD.
+
+#### OpenCode
+
+<details>
+<summary>`~/.config/opencode/tool/nvim-context.ts`</summary>
+```typescript
+// 
+import { execSync } from "child_process";
+
+export default {
+  description:
+    "Get the current Neovim context as JSON (cursor position, current file, visual selection and diagnostics)",
+  args: {},
+  async execute(args) {
+    try {
+      const output = execSync(
+        "/Users/mathias/Dropbox/Kode/Ruby/nvim-context/bin/nvim-context",
+        {
+          encoding: "utf8",
+          timeout: 5000,
+        },
+      );
+      return output.trim();
+    } catch (error) {
+      return `nvim-context unavailable: ${error.message}`;
+    }
+  },
+};
+```
+</details>
+
+## Disclaimer
+Since building software with AI can still be divisive, it might be worth
+pointing out here that `nvim-context` 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-context/blob/main/LICENSE).

data/bin/nvim-context

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require_relative "../lib/nvim_context"
+
+puts NvimContext::Fetcher.fetch

data/lib/nvim_context/connector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "neovim"
+
+module NvimContext
+  class Connector
+    def initialize(client: nil)
+      @socket_path = ENV["NVIM_CONTEXT_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 ContextError,
+            "Failed during Neovim operation: #{e.message}",
+            e.backtrace
+    end
+
+    private
+
+    attr_reader :client, :socket_path
+
+    DEFAULT_SOCKET_PATH = File.expand_path("nvim-context.sock")
+    private_constant :DEFAULT_SOCKET_PATH
+  end
+end

data/lib/nvim_context/data_extractor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module NvimContext
+  class DataExtractor
+    def self.cursor(client:)
+      cursor = client.current.window.cursor
+      { line: cursor[0], col: cursor[1] }
+    rescue StandardError => e
+      raise ContextError,
+            "Failed to get cursor info: #{e.message}",
+            e.backtrace
+    end
+
+    def self.file(client:)
+      client.current.buffer.name
+    rescue StandardError => e
+      raise ContextError,
+            "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.eval("getline(#{start_line}, #{end_line})")
+      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_context/errors.rb

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

data/lib/nvim_context/fetcher.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module NvimContext
+  class Fetcher
+    class << self
+      def fetch
+        context = build_context
+        JSON.generate(context)
+      rescue ConnectionError => e
+        format_error("Connection failed", e.message)
+      rescue ContextError => 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 do |client|
+          {
+            cursor: DataExtractor.cursor(client: client),
+            file: DataExtractor.file(client: client),
+            selection: DataExtractor.visual_selection(client: client),
+            diagnostics: DataExtractor.diagnostics(client: client)
+          }
+        end
+      end
+
+      def format_error(error, details)
+        JSON.generate({ error: error, details: details })
+      end
+    end
+  end
+end

data/lib/nvim_context/version.rb

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

data/lib/nvim_context.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "nvim_context/errors"
+require_relative "nvim_context/connector"
+require_relative "nvim_context/fetcher"
+require_relative "nvim_context/data_extractor"
+require_relative "nvim_context/version"
+
+module NvimContext
+  class NvimContext
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: nvim-context
+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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.81.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.81.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.26.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.26.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+description: |
+  `nvim-context` extracts live context from running Neovim instances via Unix
+  socket connections, providing AI coding tools with cursor position, current
+  file, visual selections, and diagnostics as JSON. It enables context-aware
+  assistance by giving agents awareness of your current Neovim editor state,
+  supporting questions like "What does this line do?" or analysis of selected
+  code.
+email: mathias@mjj.io
+executables:
+- nvim-context
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE
+- README.md
+- bin/nvim-context
+- lib/nvim_context.rb
+- lib/nvim_context/connector.rb
+- lib/nvim_context/data_extractor.rb
+- lib/nvim_context/errors.rb
+- lib/nvim_context/fetcher.rb
+- lib/nvim_context/version.rb
+homepage: https://github.com/majjoha/nvim-context
+licenses:
+- ISC
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/majjoha/nvim-context
+  changelog_uri: https://github.com/majjoha/nvim-context/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/majjoha/nvim-context/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Bridge between running Neovim instances and agentic coding tools.
+test_files: []