Merge pull request #21 from kylesnowschwartz/kyle/start-terminal-in-normal-mode

Add option to start terminal in normal mode

Author: greggh

doc/claude-code.txt

@@ -93,6 +93,7 @@ default configuration:
       split_ratio = 0.3,      -- Percentage of screen for the terminal window (height or width)
       position = "botright",  -- Position of the window: "botright", "topleft", "vertical", "vsplit", etc.
       enter_insert = true,    -- Whether to enter insert mode when opening Claude Code
+      start_in_normal_mode = false, -- Whether to start in normal mode instead of insert mode
       hide_numbers = true,    -- Hide line numbers in the terminal window
       hide_signcolumn = true, -- Hide the sign column in the terminal window
     },

lua/claude-code/config.lua

@@ -11,6 +11,7 @@ local M = {}
 -- @field split_ratio number Percentage of screen for the terminal window (height for horizontal, width for vertical splits)
 -- @field position string Position of the window: "botright", "topleft", "vertical", etc.
 -- @field enter_insert boolean Whether to enter insert mode when opening Claude Code
+-- @field start_in_normal_mode boolean Whether to start in normal mode instead of insert mode when opening Claude Code
 -- @field hide_numbers boolean Hide line numbers in the terminal window
 -- @field hide_signcolumn boolean Hide the sign column in the terminal window
 
@@ -63,6 +64,7 @@ M.default_config = {
     height_ratio = 0.3, -- DEPRECATED: Use split_ratio instead
     position = 'botright', -- Position of the window: "botright", "topleft", "vertical", etc.
     enter_insert = true, -- Whether to enter insert mode when opening Claude Code
+    start_in_normal_mode = false, -- Whether to start in normal mode instead of insert mode
     hide_numbers = true, -- Hide line numbers in the terminal window
     hide_signcolumn = true, -- Hide the sign column in the terminal window
   },
@@ -129,6 +131,10 @@ local function validate_config(config)
     return false, 'window.enter_insert must be a boolean'
   end
 
+  if type(config.window.start_in_normal_mode) ~= 'boolean' then
+    return false, 'window.start_in_normal_mode must be a boolean'
+  end
+
   if type(config.window.hide_numbers) ~= 'boolean' then
     return false, 'window.hide_numbers must be a boolean'
   end

lua/claude-code/init.lua

@@ -41,7 +41,7 @@ M.claude_code = terminal.terminal
 --- Force insert mode when entering the Claude Code window
 --- This is a public function used in keymaps
 function M.force_insert_mode()
-  terminal.force_insert_mode(M)
+  terminal.force_insert_mode(M, M.config)
 end
 
 --- Toggle the Claude Code terminal window

lua/claude-code/terminal.lua

@@ -47,10 +47,16 @@ end
 
 --- Set up function to force insert mode when entering the Claude Code window
 --- @param claude_code table The main plugin module
-function M.force_insert_mode(claude_code)
+--- @param config table The plugin configuration
+function M.force_insert_mode(claude_code, config)
   local bufnr = claude_code.claude_code.bufnr
   if bufnr and vim.api.nvim_buf_is_valid(bufnr) and vim.fn.bufnr '%' == bufnr then
     -- Only enter insert mode if we're in the terminal buffer and not already in insert mode
+    -- and not configured to stay in normal mode
+    if config.window.start_in_normal_mode then
+      return
+    end
+
     local mode = vim.api.nvim_get_mode().mode
     if vim.bo.buftype == 'terminal' and mode ~= 't' and mode ~= 'i' then
       vim.cmd 'silent! stopinsert'
@@ -79,10 +85,12 @@ function M.toggle(claude_code, config, git)
     else
       -- Claude Code buffer exists but is not visible, open it in a split
       create_split(config.window.position, config, bufnr)
-      -- Force insert mode more aggressively
-      vim.schedule(function()
-        vim.cmd 'stopinsert | startinsert'
-      end)
+      -- Force insert mode more aggressively unless configured to start in normal mode
+      if not config.window.start_in_normal_mode then
+        vim.schedule(function()
+          vim.cmd 'stopinsert | startinsert'
+        end)
+      end
     end
   else
     -- Claude Code is not running, start it in a new split
@@ -113,8 +121,8 @@ function M.toggle(claude_code, config, git)
     -- Store buffer number for future reference
     claude_code.claude_code.bufnr = vim.fn.bufnr '%'
 
-    -- Automatically enter insert mode in terminal
-    if config.window.enter_insert then
+    -- Automatically enter insert mode in terminal unless configured to start in normal mode
+    if config.window.enter_insert and not config.window.start_in_normal_mode then
       vim.cmd 'startinsert'
     end
   end

tests/spec/terminal_spec.lua

@@ -72,6 +72,7 @@ describe('terminal module', function()
         position = 'botright',
         split_ratio = 0.5,
         enter_insert = true,
+        start_in_normal_mode = false,
         hide_numbers = true,
         hide_signcolumn = true,
       },
@@ -196,6 +197,58 @@ describe('terminal module', function()
     end)
   end)
 
+  describe('start_in_normal_mode option', function()
+    it('should not enter insert mode when start_in_normal_mode is true', function()
+      -- Claude Code is not running (bufnr is nil)
+      claude_code.claude_code.bufnr = nil
+
+      -- Set start_in_normal_mode to true
+      config.window.start_in_normal_mode = true
+
+      -- Call toggle
+      terminal.toggle(claude_code, config, git)
+
+      -- Check if startinsert was NOT called
+      local startinsert_found = false
+      for _, cmd in ipairs(vim_cmd_calls) do
+        if cmd == 'startinsert' then
+          startinsert_found = true
+          break
+        end
+      end
+
+      assert.is_false(
+        startinsert_found,
+        'startinsert should not be called when start_in_normal_mode is true'
+      )
+    end)
+
+    it('should enter insert mode when start_in_normal_mode is false', function()
+      -- Claude Code is not running (bufnr is nil)
+      claude_code.claude_code.bufnr = nil
+
+      -- Set start_in_normal_mode to false
+      config.window.start_in_normal_mode = false
+
+      -- Call toggle
+      terminal.toggle(claude_code, config, git)
+
+      -- Check if startinsert was called
+      local startinsert_found = false
+      for _, cmd in ipairs(vim_cmd_calls) do
+        if cmd == 'startinsert' then
+          startinsert_found = true
+          break
+        end
+      end
+
+      assert.is_true(
+        startinsert_found,
+        'startinsert should be called when start_in_normal_mode is false'
+      )
+    end)
+  end)
+
   describe('force_insert_mode', function()
     it('should check insert mode conditions in terminal buffer', function()
       -- For this test, we'll just verify that the function can be called without error
@@ -206,7 +259,12 @@ describe('terminal module', function()
             bufnr = 1,
           },
         }
-        terminal.force_insert_mode(mock_claude_code)
+        local mock_config = {
+          window = {
+            start_in_normal_mode = false,
+          },
+        }
+        terminal.force_insert_mode(mock_claude_code, mock_config)
       end)
 
       assert.is_true(success, 'Force insert mode function should run without error')
@@ -221,7 +279,12 @@ describe('terminal module', function()
             bufnr = 2,
           },
         }
-        terminal.force_insert_mode(mock_claude_code)
+        local mock_config = {
+          window = {
+            start_in_normal_mode = false,
+          },
+        }
+        terminal.force_insert_mode(mock_claude_code, mock_config)
       end)
 
       assert.is_true(success, 'Force insert mode function should run without error')