feat: add focus_after_send option for terminal behavior (#118)

# Add focus_after_send option to control terminal focus behavior

Added a new configuration option `focus_after_send` that controls whether the Claude terminal should be focused after a successful send when already connected. 

When enabled, the terminal will be focused after sending code to Claude. When disabled (the default), the terminal will only be made visible but not focused.

This provides more control over the workflow when interacting with Claude:
- Default behavior (false): Terminal becomes visible but doesn't steal focus
- Optional behavior (true): Terminal becomes visible and focused after sending

The PR includes:
- Configuration option in the main config structure
- Type definition updates
- Implementation in the send_at_mention function
- Documentation in README.md
- Unit tests to verify both behaviors

Author: ThomasK33

README.md

@@ -249,6 +249,10 @@ For deep technical details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
                         -- For local installations: "~/.claude/local/claude"
                         -- For native binary: use output from 'which claude'
 
+    -- Send/Focus Behavior
+    -- When true, successful sends will focus the Claude terminal if already connected
+    focus_after_send = false,
+
     -- Selection Tracking
     track_selection = true,
     visual_demotion_delay_ms = 50,

dev-config.lua

@@ -48,6 +48,9 @@ return {
     -- log_level = "info", -- "trace", "debug", "info", "warn", "error"
     -- terminal_cmd = nil, -- Custom terminal command (default: "claude")
 
+    -- Send/Focus Behavior
+    focus_after_send = true, -- Focus Claude terminal after successful send while connected
+
     -- Selection Tracking
     -- track_selection = true, -- Enable real-time selection tracking
     -- visual_demotion_delay_ms = 50, -- Delay before demoting visual selection (ms)

lua/claudecode/config.lua

@@ -14,6 +14,8 @@ M.defaults = {
   env = {}, -- Custom environment variables for Claude terminal
   log_level = "info",
   track_selection = true,
+  -- When true, focus Claude terminal after a successful send while connected
+  focus_after_send = false,
   visual_demotion_delay_ms = 50, -- Milliseconds to wait before demoting a visual selection
   connection_wait_delay = 200, -- Milliseconds to wait after connection before sending queued @ mentions
   connection_timeout = 10000, -- Maximum time to wait for Claude Code to connect (milliseconds)
@@ -87,6 +89,7 @@ function M.validate(config)
   assert(is_valid_log_level, "log_level must be one of: " .. table.concat(valid_log_levels, ", "))
 
   assert(type(config.track_selection) == "boolean", "track_selection must be a boolean")
+  assert(type(config.focus_after_send) == "boolean", "focus_after_send must be a boolean")
 
   assert(
     type(config.visual_demotion_delay_ms) == "number" and config.visual_demotion_delay_ms >= 0,

lua/claudecode/init.lua

@@ -269,7 +269,12 @@ function M.send_at_mention(file_path, start_line, end_line, context)
     local success, error_msg = M._broadcast_at_mention(file_path, start_line, end_line)
     if success then
       local terminal = require("claudecode.terminal")
-      terminal.ensure_visible()
+      if M.state.config and M.state.config.focus_after_send then
+        -- Open focuses the terminal without toggling/hiding if already focused
+        terminal.open()
+      else
+        terminal.ensure_visible()
+      end
     end
     return success, error_msg
   else

lua/claudecode/types.lua

@@ -108,6 +108,7 @@
 ---@field env table<string, string>
 ---@field log_level ClaudeCodeLogLevel
 ---@field track_selection boolean
+---@field focus_after_send boolean
 ---@field visual_demotion_delay_ms number
 ---@field connection_wait_delay number
 ---@field connection_timeout number

tests/unit/focus_after_send_spec.lua

@@ -0,0 +1,130 @@
+require("tests.busted_setup")
+require("tests.mocks.vim")
+
+describe("focus_after_send behavior", function()
+  local saved_require
+  local claudecode
+
+  local mock_terminal
+  local mock_logger
+  local mock_server_facade
+
+  local function setup_mocks(focus_after_send)
+    mock_terminal = {
+      setup = function() end,
+      open = spy.new(function() end),
+      ensure_visible = spy.new(function() end),
+    }
+
+    mock_logger = {
+      setup = function() end,
+      debug = function() end,
+      info = function() end,
+      warn = function() end,
+      error = function() end,
+    }
+
+    mock_server_facade = {
+      broadcast = spy.new(function()
+        return true
+      end),
+    }
+
+    local mock_config = {
+      apply = function()
+        -- Return only fields used in this test path
+        return {
+          auto_start = false,
+          terminal_cmd = nil,
+          env = {},
+          log_level = "info",
+          track_selection = false,
+          focus_after_send = focus_after_send,
+          diff_opts = {
+            layout = "vertical",
+            open_in_new_tab = false,
+            keep_terminal_focus = false,
+            on_new_file_reject = "keep_empty",
+          },
+          models = { { name = "Claude Sonnet 4 (Latest)", value = "sonnet" } },
+        }
+      end,
+    }
+
+    saved_require = _G.require
+    _G.require = function(mod)
+      if mod == "claudecode.config" then
+        return mock_config
+      elseif mod == "claudecode.logger" then
+        return mock_logger
+      elseif mod == "claudecode.diff" then
+        return { setup = function() end }
+      elseif mod == "claudecode.terminal" then
+        return mock_terminal
+      elseif mod == "claudecode.server.init" then
+        return {
+          get_status = function()
+            return { running = true, client_count = 1 }
+          end,
+        }
+      else
+        return saved_require(mod)
+      end
+    end
+  end
+
+  local function teardown_mocks()
+    _G.require = saved_require
+    package.loaded["claudecode"] = nil
+    package.loaded["claudecode.config"] = nil
+    package.loaded["claudecode.logger"] = nil
+    package.loaded["claudecode.diff"] = nil
+    package.loaded["claudecode.terminal"] = nil
+    package.loaded["claudecode.server.init"] = nil
+  end
+
+  after_each(function()
+    teardown_mocks()
+  end)
+
+  it("focuses terminal with open() when enabled", function()
+    setup_mocks(true)
+
+    claudecode = require("claudecode")
+    claudecode.setup({})
+
+    -- Mark server as present and stub low-level broadcast to succeed
+    claudecode.state.server = mock_server_facade
+    claudecode._broadcast_at_mention = spy.new(function()
+      return true, nil
+    end)
+
+    -- Act
+    local ok, err = claudecode.send_at_mention("/tmp/file.lua", nil, nil, "test")
+    assert.is_true(ok)
+    assert.is_nil(err)
+
+    -- Assert focus behavior
+    assert.spy(mock_terminal.open).was_called()
+    assert.spy(mock_terminal.ensure_visible).was_not_called()
+  end)
+
+  it("only ensures visibility when disabled (default)", function()
+    setup_mocks(false)
+
+    claudecode = require("claudecode")
+    claudecode.setup({})
+
+    claudecode.state.server = mock_server_facade
+    claudecode._broadcast_at_mention = spy.new(function()
+      return true, nil
+    end)
+
+    local ok, err = claudecode.send_at_mention("/tmp/file.lua", nil, nil, "test")
+    assert.is_true(ok)
+    assert.is_nil(err)
+
+    assert.spy(mock_terminal.ensure_visible).was_called()
+    assert.spy(mock_terminal.open).was_not_called()
+  end)
+end)