feat(at-mention): implement :ClaudeCodeSend command for visual selection notifications

Change-Id: Ibb3d887ee78fc63ed851ecfcf1ef0ad49bbda532
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

ARCHITECTURE.md

@@ -103,6 +103,7 @@ The plugin monitors text selections in Neovim:
 - Debounces updates to avoid flooding Claude
 - Formats selection data according to MCP protocol
 - Sends updates to Claude via WebSocket
+- Supports sending `at_mentioned` notifications for visual selections using the `:ClaudeCodeSend` command, providing focused context to Claude.
 
 ### 5. Terminal Integration
 
@@ -166,7 +167,7 @@ The plugin manages the environment for Claude CLI:
    User           ──► Make Selection in Neovim
    Neovim Plugin  ──► Detect Selection Change
                   ──► Format Selection Data
-                  ──► Send Update to Claude
+                  ──► Send Update to Claude (e.g., `selection_changed` or `at_mentioned` via `:ClaudeCodeSend`)
    ```
 
 ## Module Structure

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Development environment with Nix flakes
 - Comprehensive luacheck linting with zero warnings
 - **Selection Tracking**: Added a configurable delay (`visual_demotion_delay_ms`) before a visual selection is "demoted" after exiting visual mode. This helps preserve visual context when quickly switching to the Claude terminal.
+- **At-Mention Feature**: Implemented the `:ClaudeCodeSend` command to send visual selections as `at_mentioned` notifications to Claude, providing focused code context. This includes updates to selection tracking and server broadcasting logic.
 
 ### Changed
 

README.md

@@ -15,6 +15,7 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
 - 📝 Support for file operations and diagnostics
 - 🖥️ Interactive vertical split terminal for Claude sessions (supports `folke/snacks.nvim` or native Neovim terminal)
 - 🔒 Automatic cleanup on exit - server shutdown and lockfile removal
+- 💬 **At-Mentions**: Send visual selections as `at_mentioned` context to Claude using `:'<,'>ClaudeCodeSend`.
 
 ## Requirements
 
@@ -201,13 +202,14 @@ require("claudecode").setup({
 
 2. You can now interact with Claude in the terminal window. To provide code context, you can:
 
-   - Make a selection in visual mode (`v` key), then run:
+   - **Send Visual Selection as At-Mention**: Make a selection in visual mode (`v`, `V`, or `Ctrl-V`), then run:
 
-     ```
-     :ClaudeCodeSend
+     ```vim
+     :'<,'>ClaudeCodeSend
      ```
 
-   - This sends the selected lines with file references to Claude
+     This sends the selected file path and line range as an `at_mentioned` notification to Claude,
+     allowing Claude to focus on that specific part of your code.
 
 3. Switch between your code and the Claude terminal:
 

lua/claudecode/init.lua

@@ -228,16 +228,20 @@ function M._create_commands()
     desc = "Show Claude Code integration status",
   })
 
-  vim.api.nvim_create_user_command("ClaudeCodeSend", function()
+  vim.api.nvim_create_user_command("ClaudeCodeSend", function(opts)
     if not M.state.server then
       vim.notify("Claude Code integration is not running", vim.log.levels.ERROR)
       return
     end
 
-    local selection = require("claudecode.selection")
-    selection.send_current_selection()
+    -- The selection.send_at_mention_for_visual_selection() function itself
+    -- will check for a valid visual selection and show an error if none exists.
+    -- This simplifies handling calls from keymaps vs. direct :'<,'>Cmd invocations.
+    local selection_module = require("claudecode.selection")
+    selection_module.send_at_mention_for_visual_selection()
   end, {
-    desc = "Send current selection to Claude Code",
+    desc = "Send current visual selection as an at_mention to Claude Code",
+    range = true, -- Important: This makes the command expect a range (visual selection)
   })
 end
 

lua/claudecode/meta/vim.lua

@@ -30,7 +30,7 @@
 ---@class vim_buffer_options_table: table<string, any>
 
 ---@class vim_bo_proxy: vim_buffer_options_table
----@operator index (key: number): vim_buffer_options_table # Allows vim.bo[bufnr]
+---@operator #index(bufnr: number): vim_buffer_options_table Allows vim.bo[bufnr]
 
 ---@class vim_diagnostic_info
 ---@field bufnr number
@@ -50,12 +50,13 @@
 ---@class vim_global_api
 ---@field notify fun(msg: string | string[], level?: number, opts?: vim_notify_opts):nil
 ---@field log vim_log
----@field _last_echo table[]? # table of tables, e.g. { {"message", "HighlightGroup"} }
+---@field _last_echo table[]? table of tables, e.g. { {"message", "HighlightGroup"} }
 ---@field _last_error string?
----@field o vim_options_table # For vim.o.option_name
----@field bo vim_bo_proxy      # For vim.bo.option_name and vim.bo[bufnr].option_name
----@field diagnostic vim_diagnostic_module # For vim.diagnostic.*
----@field empty_dict fun(): table # For vim.empty_dict()
+---@field o vim_options_table For vim.o.option_name
+---@field bo vim_bo_proxy      For vim.bo.option_name and vim.bo[bufnr].option_name
+---@field diagnostic vim_diagnostic_module For vim.diagnostic.*
+---@field empty_dict fun(): table For vim.empty_dict()
+---@field schedule_wrap fun(fn: function): function For vim.schedule_wrap()
 -- Add other vim object definitions here if they cause linting issues
 -- e.g. vim.fn, vim.api, vim.loop, vim.deepcopy, etc.
 

lua/claudecode/selection.lua

@@ -14,11 +14,11 @@ M.state = {
   latest_selection = nil,
   tracking_enabled = false,
   debounce_timer = nil,
-  debounce_ms = 300, -- Default debounce time in milliseconds
+  debounce_ms = 300,
 
   -- New state for delayed visual demotion
   last_active_visual_selection = nil, -- Stores { bufnr, selection_data, timestamp }
-  demotion_timer = nil, -- Timer object for visual demotion delay
+  demotion_timer = nil,
   visual_demotion_delay_ms = 50, -- Default, will be overridden by config in M.enable
 }
 
@@ -157,7 +157,7 @@ function M.update_selection()
   local current_mode = current_mode_info.mode
   local current_selection -- This will be the candidate for M.state.latest_selection
 
-  if current_mode == "v" or current_mode == "V" or current_mode == "\022" then -- Visual modes
+  if current_mode == "v" or current_mode == "V" or current_mode == "\022" then
     -- If a new visual selection is made, cancel any pending demotion
     if M.state.demotion_timer then
       M.state.demotion_timer:stop()
@@ -180,7 +180,7 @@ function M.update_selection()
         M.state.last_active_visual_selection = nil
       end
     end
-  else -- Not in visual mode
+  else
     local last_visual = M.state.last_active_visual_selection
 
     if M.state.demotion_timer then
@@ -307,12 +307,10 @@ local function validate_visual_mode()
   local current_nvim_mode = vim.api.nvim_get_mode().mode
   local fixed_anchor_pos_raw = vim.fn.getpos("v")
 
-  -- Must be in a visual mode
   if not (current_nvim_mode == "v" or current_nvim_mode == "V" or current_nvim_mode == "\22") then
     return false, "not in visual mode"
   end
 
-  -- The 'v' mark must have a non-zero line number
   if fixed_anchor_pos_raw[2] == 0 then
     return false, "no visual selection mark"
   end
@@ -388,13 +386,10 @@ local function extract_characterwise_text(lines_content, start_coords, end_coord
     end
 
     local text_parts = {}
-    -- First line: from start_coords.col to end of line
     table.insert(text_parts, string.sub(lines_content[1], start_coords.col))
-    -- Middle lines (if any)
     for i = 2, #lines_content - 1 do
       table.insert(text_parts, lines_content[i])
     end
-    -- Last line: from beginning to end_coords.col
     table.insert(text_parts, string.sub(lines_content[#lines_content], 1, end_coords.col))
     return table.concat(text_parts, "\n")
   end
@@ -420,7 +415,6 @@ local function calculate_lsp_positions(start_coords, end_coords, visual_mode, li
       lsp_end_char = 0
     end
   else
-    -- For characterwise/blockwise
     lsp_start_char = start_coords.col - 1
     lsp_end_char = end_coords.col
   end
@@ -435,26 +429,21 @@ end
 -- @return table|nil A table containing selection text, file path, URL, and
 --                   start/end positions, or nil if no visual selection exists.
 function M.get_visual_selection()
-  -- Validate visual mode
   local valid = validate_visual_mode()
   if not valid then
     return nil
   end
 
-  -- Get effective visual mode
   local visual_mode = get_effective_visual_mode()
   if not visual_mode then
     return nil
   end
 
-  -- Get selection coordinates
   local start_coords, end_coords = get_selection_coordinates()
 
-  -- Get buffer information
   local current_buf = vim.api.nvim_get_current_buf()
   local file_path = vim.api.nvim_buf_get_name(current_buf)
 
-  -- Fetch lines content
   local lines_content = vim.api.nvim_buf_get_lines(
     current_buf,
     start_coords.lnum - 1, -- Convert to 0-indexed
@@ -466,7 +455,6 @@ function M.get_visual_selection()
     return nil
   end
 
-  -- Extract text based on visual mode
   local final_text
   if visual_mode == "V" then
     final_text = extract_linewise_text(lines_content, start_coords)
@@ -479,7 +467,6 @@ function M.get_visual_selection()
     return nil
   end
 
-  -- Calculate LSP positions
   local lsp_positions = calculate_lsp_positions(start_coords, end_coords, visual_mode, lines_content)
 
   return {
@@ -584,4 +571,45 @@ function M.send_current_selection()
   vim.api.nvim_echo({ { "Selection sent to Claude", "Normal" } }, false, {})
 end
 
+--- Sends an at_mentioned notification for the current visual selection.
+function M.send_at_mention_for_visual_selection()
+  if not M.state.tracking_enabled or not M.server then
+    vim.api.nvim_err_writeln("Claude Code is not running or server not available.")
+    return
+  end
+
+  local visual_sel = M.get_visual_selection()
+
+  if not visual_sel or visual_sel.selection.isEmpty then
+    vim.api.nvim_err_writeln("No visual selection to send as at-mention.")
+    return
+  end
+
+  -- Pre-calculate line numbers, breaking down access for the linter
+  local current_selection = visual_sel["selection"]
+  local start_pos = current_selection["start"]
+  local end_pos = current_selection["end"]
+  -- Send 0-indexed LSP line numbers directly, assuming the at_mentioned protocol expects this.
+  local start_line_val = start_pos["line"]
+  local end_line_val = end_pos["line"]
+
+  local params = {}
+  params["filePath"] = visual_sel["filePath"]
+  params["lineStart"] = start_line_val
+  params["lineEnd"] = end_line_val
+
+  -- M.server is set in M.enable() and used by M.send_selection_update()
+  -- It refers to the server instance from lua/claudecode/server/init.lua
+  local success = M.server.broadcast("at_mentioned", params)
+
+  if success then
+    vim.api.nvim_echo(
+      { { "At-mention sent to Claude for " .. vim.fn.fnamemodify(params.filePath, ":t"), "Normal" } },
+      false,
+      {}
+    )
+  else
+    vim.api.nvim_err_writeln("Failed to send at-mention.")
+  end
+end
 return M

plugin/claudecode.lua

@@ -8,29 +8,31 @@ if vim.g.loaded_claudecode then
 end
 vim.g.loaded_claudecode = 1
 
--- Example in init.lua: vim.g.claudecode_auto_setup = { auto_start = true }
+--- Example: In your `init.lua`, you can set `vim.g.claudecode_auto_setup = { auto_start = true }`
+--- to automatically start ClaudeCode when Neovim loads.
 if vim.g.claudecode_auto_setup then
   vim.defer_fn(function()
     require("claudecode").setup(vim.g.claudecode_auto_setup)
   end, 0)
 end
 
 local terminal_ok, terminal = pcall(require, "claudecode.terminal")
+local selection_module_ok, selection = pcall(require, "claudecode.selection")
 
 if terminal_ok then
   vim.api.nvim_create_user_command("ClaudeCode", function(_opts)
     local current_mode = vim.fn.mode()
-    if current_mode == "v" or current_mode == "V" or current_mode == "\22" then -- \22 is CTRL-V for blockwise visual
+    if current_mode == "v" or current_mode == "V" or current_mode == "\22" then -- \22 is CTRL-V (blockwise visual mode)
       vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes("<Esc>", true, false, true), "n", false)
     end
-    terminal.toggle({}) -- opts.fargs could be used for future enhancements
+    terminal.toggle({}) -- `opts.fargs` can be used for future enhancements, e.g., passing initial prompts.
   end, {
-    nargs = "?", -- Allow optional arguments for future enhancements
+    nargs = "?", -- Allows optional arguments, useful for future command enhancements.
     desc = "Toggle the Claude Code terminal window",
   })
 
   vim.api.nvim_create_user_command("ClaudeCodeOpen", function(_opts)
-    terminal.open({}) -- opts.fargs could be used for future enhancements
+    terminal.open({}) -- `opts.fargs` can be used for future enhancements.
   end, {
     nargs = "?",
     desc = "Open the Claude Code terminal window",
@@ -44,3 +46,19 @@ if terminal_ok then
 else
   vim.notify("ClaudeCode Terminal module not found. Commands not registered.", vim.log.levels.ERROR)
 end
+if selection_module_ok then
+  vim.api.nvim_create_user_command("ClaudeCodeSend", function(opts)
+    if opts.range == 0 then
+      vim.api.nvim_err_writeln("ClaudeCodeSend requires a visual selection.")
+      return
+    end
+    -- While `opts.line1` and `opts.line2` provide the selected line range,
+    -- the `selection` module is preferred for obtaining precise character data if needed.
+    selection.send_at_mention_for_visual_selection()
+  end, {
+    desc = "Send the current visual selection as an at_mention to Claude",
+    range = true, -- This is crucial for commands that operate on a visual selection (e.g., :'&lt;,'&gt;Cmd).
+  })
+else
+  vim.notify("ClaudeCode Selection module not found. ClaudeCodeSend command not registered.", vim.log.levels.ERROR)
+end

tests/config_test.lua

@@ -1,9 +1,8 @@
 -- Simple config module tests that don't rely on the vim API
 
--- Create minimal vim mock
 _G.vim = { ---@type vim_global_api
   deepcopy = function(t)
-    -- Basic deepcopy for testing
+    -- Basic deepcopy implementation for testing purposes
     local copy = {}
     for k, v in pairs(t) do
       if type(v) == "table" then
@@ -29,27 +28,21 @@ _G.vim = { ---@type vim_global_api
   bo = setmetatable({}, { -- Mock for vim.bo and vim.bo[bufnr]
     __index = function(t, k)
       if type(k) == "number" then
-        -- vim.bo[bufnr] accessed, return a new proxy table for this buffer
         if not t[k] then
           t[k] = {} ---@type vim_buffer_options_table
         end
         return t[k]
       end
-      -- vim.bo.option_name (global buffer option)
-      -- Return nil or a default mock value if needed
       return nil
     end,
     __newindex = function(t, k, v)
       if type(k) == "number" then
-        -- vim.bo[bufnr] = val (should not happen for options table itself)
-        -- or vim.bo[bufnr].opt = val
-        -- For simplicity, allow setting on the dynamic buffer table
+        -- For mock simplicity, allows direct setting for vim.bo[bufnr].opt = val or similar assignments.
         if not t[k] then
           t[k] = {}
         end
         rawset(t[k], v) -- Assuming v is the option name if k is bufnr, this is simplified
       else
-        -- vim.bo.option_name = val
         rawset(t, k, v)
       end
     end,
@@ -58,7 +51,7 @@ _G.vim = { ---@type vim_global_api
     get = function()
       return {}
     end,
-    -- Add other vim.diagnostic functions as needed for tests
+    -- Add other vim.diagnostic functions as needed for these tests
   },
   empty_dict = function()
     return {}
@@ -85,12 +78,10 @@ _G.vim = { ---@type vim_global_api
 describe("Config module", function()
   local config
 
-  -- Set up before each test
   setup(function()
-    -- Reset the module
+    -- Reset the module to ensure a clean state for each test
     package.loaded["claudecode.config"] = nil
 
-    -- Load module
     config = require("claudecode.config")
   end)
 
@@ -111,6 +102,7 @@ describe("Config module", function()
       terminal_cmd = "toggleterm",
       log_level = "debug",
       track_selection = false,
+      visual_demotion_delay_ms = 50,
     }
 
     local success, _ = pcall(function()