feat(terminal): add native terminal fallback and improve configuration

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

Author: ThomasK33

CLAUDE.md

@@ -12,12 +12,8 @@ Claude Code Neovim Integration is a Neovim plugin that enables bidirectional com
 # Format code with StyLua
 make format
 
-# Check code for errors
 make check  # Runs luacheck
-
-# Run all tests
 make test   # Runs all tests with busted
-
 # Run specific test file
 nvim --headless -u tests/minimal_init.lua -c "lua require('tests.unit.config_spec')"
 ```
@@ -133,7 +129,7 @@ require("claudecode").setup({
   port_range = { min = 10000, max = 65535 },
 
   -- Auto-start WebSocket server on Neovim startup
-  auto_start = false,
+  auto_start = true,
 
   -- Custom terminal command to use when launching Claude
   terminal_cmd = nil, -- e.g., "toggleterm"

README.md

@@ -12,18 +12,18 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
 - 🔍 Selection tracking to provide context to Claude
 - 🛠️ Integration with Neovim's buffer and window management
 - 📝 Support for file operations and diagnostics
-- 🖥️ Interactive vertical split terminal for Claude sessions (via `folke/snacks.nvim`)
+- 🖥️ Interactive vertical split terminal for Claude sessions (supports `folke/snacks.nvim` or native Neovim terminal)
 - 🔒 Automatic cleanup on exit - server shutdown and lockfile removal
 
 ## Requirements
 
 - Neovim >= 0.8.0
 - Claude Code CLI installed and in your PATH
 - Lua >= 5.1
-- **Required for terminal integration:** [folke/snacks.nvim](https://github.com/folke/snacks.nvim) - Terminal management plugin
+- **Optional for terminal integration:** [folke/snacks.nvim](https://github.com/folke/snacks.nvim) - Terminal management plugin (can use native Neovim terminal as an alternative).
 - Optional: plenary.nvim for additional utilities
 
-Note: The terminal feature requires Snacks.nvim to be installed and available. If not available, the terminal commands will display an error message, but the core Claude Code integration will still function.
+Note: The terminal feature can use `Snacks.nvim` or the native Neovim terminal. If `Snacks.nvim` is configured as the provider but is not available, it will fall back to the native terminal.
 
 ## Installation
 
@@ -84,15 +84,16 @@ return {
       terminal = {
         split_side = "left",            -- "left" or "right"
         split_width_percentage = 0.4, -- 0.0 to 1.0
+        provider = "snacks",          -- "snacks" or "native" (defaults to "snacks")
+        show_native_term_exit_tip = true, -- Show tip for Ctrl-\\ Ctrl-N (defaults to true)
       },
     },
     -- The main require("claudecode").setup(opts) will handle passing
     -- opts.terminal to the terminal module's setup.
     config = true, -- or function(_, opts) require("claudecode").setup(opts) end
     keys = {
-      { "<leader>cc", "<cmd>ClaudeCodeStart<cr>", desc = "Start Claude Code" },
+      { "<leader>cc", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
       { "<leader>cs", "<cmd>ClaudeCodeSend<cr>", desc = "Send to Claude Code" },
-      { "<leader>ct", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
       { "<leader>co", "<cmd>ClaudeCodeOpen<cr>", desc = "Open Claude Terminal" },
       { "<leader>cx", "<cmd>ClaudeCodeClose<cr>", desc = "Close Claude Terminal" },
     },
@@ -117,19 +118,20 @@ return {
     opts = {
       -- Development configuration for claudecode main
       log_level = "debug",
-      auto_start = true,  -- Optional: auto-start the server
+      auto_start = true,
 
       -- Example terminal configuration for dev:
       terminal = {
         split_side = "right",
         split_width_percentage = 0.25,
+        provider = "native",
+        show_native_term_exit_tip = false,
       },
     },
     config = true,
     keys = {
-      { "<leader>cc", "<cmd>ClaudeCodeStart<cr>", desc = "Start Claude Code" },
+      { "<leader>cc", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
       { "<leader>cs", "<cmd>ClaudeCodeSend<cr>", desc = "Send to Claude Code" },
-      { "<leader>ct", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Terminal" },
       { "<leader>co", "<cmd>ClaudeCodeOpen<cr>", desc = "Open Claude Terminal" },
       { "<leader>cx", "<cmd>ClaudeCodeClose<cr>", desc = "Close Claude Terminal" },
     },
@@ -151,8 +153,9 @@ require("claudecode").setup({
   -- Port range for WebSocket server (default: 10000-65535)
   port_range = { min = 10000, max = 65535 },
 
-  -- Auto-start WebSocket server on Neovim startup
-  auto_start = false,
+  -- Auto-start WebSocket server when the plugin is loaded.
+  -- Note: With lazy-loading (e.g., LazyVim), this means the server starts when a plugin command is first used.
+  auto_start = true,
 
   -- Custom terminal command to use when launching Claude
   -- This command is used by the new interactive terminal feature.
@@ -172,6 +175,13 @@ require("claudecode").setup({
 
     -- Width of the terminal as a percentage of total editor width (0.0 to 1.0)
     split_width_percentage = 0.30, -- Default
+
+    -- Terminal provider ('snacks' or 'native')
+    -- If 'snacks' is chosen but not available, it will fall back to 'native'.
+    provider = "snacks", -- Default
+
+    -- Whether to show a one-time tip about exiting native terminal mode (Ctrl-\\ Ctrl-N)
+    show_native_term_exit_tip = true -- Default
   }
 })
 ```
@@ -209,12 +219,12 @@ require("claudecode").setup({
 No default keymaps are provided. Add your own in your configuration:
 
 ```lua
-vim.keymap.set("n", "<leader>cc", "<cmd>ClaudeCodeStart<cr>", { desc = "Start Claude Code" })
+vim.keymap.set("n", "<leader>cc", "<cmd>ClaudeCode<cr>", { desc = "Toggle Claude Terminal" })
 vim.keymap.set({"n", "v"}, "<leader>cs", "<cmd>ClaudeCodeSend<cr>", { desc = "Send to Claude Code" })
-+vim.keymap.set("n", "<leader>ct", "<cmd>ClaudeCode<cr>", { desc = "Toggle Claude Terminal" })
-+-- Or more specific maps:
-+-- vim.keymap.set("n", "<leader>co", "<cmd>ClaudeCodeOpen<cr>", { desc = "Open Claude Terminal" })
-+-- vim.keymap.set("n", "<leader>cx", "<cmd>ClaudeCodeClose<cr>", { desc = "Close Claude Terminal" })
+
+-- Or more specific maps:
+vim.keymap.set("n", "<leader>co", "<cmd>ClaudeCodeOpen<cr>", { desc = "Open Claude Terminal" })
+vim.keymap.set("n", "<leader>cx", "<cmd>ClaudeCodeClose<cr>", { desc = "Close Claude Terminal" })
 ```
 
 ## Architecture

lua/claudecode/config.lua

@@ -1,27 +1,21 @@
--- Configuration management for Claude Code Neovim integration
+--- Manages configuration for the Claude Code Neovim integration.
+-- Provides default settings, validation, and application of user-defined configurations.
 local M = {}
 
--- Default configuration
 M.defaults = {
-  -- Port range for WebSocket server
   port_range = { min = 10000, max = 65535 },
-
-  -- Auto-start WebSocket server on Neovim startup
-  auto_start = false,
-
-  -- Custom terminal command to use when launching Claude
+  auto_start = true,
   terminal_cmd = nil,
-
-  -- Log level (trace, debug, info, warn, error)
   log_level = "info",
-
-  -- Enable sending selection updates to Claude
   track_selection = true,
 }
 
--- Validate configuration
+--- Validates the provided configuration table.
+-- Ensures that all configuration options are of the correct type and within valid ranges.
+-- @param config table The configuration table to validate.
+-- @return boolean true if the configuration is valid.
+-- @error string if any configuration option is invalid.
 function M.validate(config)
-  -- Validate port range
   assert(
     type(config.port_range) == "table"
       and type(config.port_range.min) == "number"
@@ -32,13 +26,10 @@ function M.validate(config)
     "Invalid port range"
   )
 
-  -- Validate auto_start
   assert(type(config.auto_start) == "boolean", "auto_start must be a boolean")
 
-  -- Validate terminal_cmd
   assert(config.terminal_cmd == nil or type(config.terminal_cmd) == "string", "terminal_cmd must be nil or a string")
 
-  -- Validate log_level
   local valid_log_levels = { "trace", "debug", "info", "warn", "error" }
   local is_valid_log_level = false
   for _, level in ipairs(valid_log_levels) do
@@ -49,21 +40,23 @@ function M.validate(config)
   end
   assert(is_valid_log_level, "log_level must be one of: " .. table.concat(valid_log_levels, ", "))
 
-  -- Validate track_selection
   assert(type(config.track_selection) == "boolean", "track_selection must be a boolean")
 
   return true
 end
 
--- Apply configuration with validation
+--- Applies user configuration on top of default settings and validates the result.
+-- Merges the user-provided configuration with the default configuration,
+-- then validates the merged configuration.
+-- @param user_config table|nil The user-provided configuration table.
+-- @return table The final, validated configuration table.
 function M.apply(user_config)
   local config = vim.deepcopy(M.defaults)
 
   if user_config then
     config = vim.tbl_deep_extend("force", config, user_config)
   end
 
-  -- Validate the merged configuration
   M.validate(config)
 
   return config

lua/claudecode/init.lua

@@ -37,11 +37,10 @@ M.version = {
 --- @field log_level "trace"|"debug"|"info"|"warn"|"error" Log level.
 --- @field track_selection boolean Enable sending selection updates to Claude.
 
--- Default configuration
 --- @type ClaudeCode.Config
 local default_config = {
   port_range = { min = 10000, max = 65535 },
-  auto_start = false,
+  auto_start = true,
   terminal_cmd = nil,
   log_level = "info",
   track_selection = true,
@@ -53,7 +52,6 @@ local default_config = {
 --- @field port number|nil The port the server is running on.
 --- @field initialized boolean Whether the plugin has been initialized.
 
--- Plugin state
 --- @type ClaudeCode.State
 M.state = {
   config = vim.deepcopy(default_config),
@@ -63,7 +61,12 @@ M.state = {
 }
 
 --- Set up the plugin with user configuration
----@param opts table|nil Optional configuration table to override defaults
+---@param opts table|nil Optional configuration table to override defaults.
+---@field opts.terminal table|nil Configuration for the terminal module.
+---@field opts.terminal.split_side string|nil 'left' or 'right'.
+---@field opts.terminal.split_width_percentage number|nil Percentage of screen width (0.0 to 1.0).
+---@field opts.terminal.provider string|nil 'snacks' or 'native'.
+---@field opts.terminal.show_native_term_exit_tip boolean|nil Show tip for exiting native terminal (default: true).
 ---@return table The plugin module
 function M.setup(opts)
   opts = opts or {}