feat: external and TMUX Terminal Provider Support

[gaborkajtar]

External and TMUX Terminal Provider Support

This PR introduces two new terminal providers, expanding claudecode.nvim's flexibility for different development environments.

🚀 New Features

1. External Terminal Provider

What: Added a no-op terminal provider for users who prefer running Claude Code in external terminals.

Key capabilities:

• Zero terminal management: All terminal operations are no-ops that log debug messages
• Always available: No dependency checks, works in any environment
• Server-only mode: Focuses purely on MCP server functionality
• Auto-start support: When configured with event = "VeryLazy", starts MCP server automatically

Use cases:

• Users with custom terminal setups (tmux, kitty, separate windows)
• Server-only deployments where terminal management isn't needed
• Complex workflows requiring external terminal control

Configuration:

{
  "coder/claudecode.nvim", 
  event = "VeryLazy",  -- Auto-start the MCP server
  opts = {
    terminal = {
      provider = "external",  -- No internal terminal management
    },
  },
}

2. Tmux Terminal Provider

What: Added native tmux integration that creates and manages tmux panes for Claude Code sessions.

Key capabilities:

• Smart pane creation: Creates tmux panes with configurable positioning and sizing
• Width calculation: Dynamically calculates split sizes based on current window width
• Environment isolation: Properly sets environment variables for Claude discovery
• Session persistence: Tmux panes survive across Neovim restarts
• Flexible configuration: Supports left/right positioning and percentage-based sizing

Technical details:

• Uses tmux split-window with calculated dimensions
• Supports split_side ("left"/"right") and split_width_percentage (0.0-1.0)
• Implements full terminal provider interface with proper cleanup
• Includes comprehensive error handling and logging

Configuration:

opts = {
  terminal = {
    provider = "tmux",               -- Use tmux panes
    split_side = "right",            -- Position panes to the right  
    split_width_percentage = 0.4,    -- 40% of window width
  },
}

🔧 Technical Implementation

Provider Architecture

Both providers implement the standardized TerminalProvider interface:

• setup(), open(), close(), toggle() functions
• is_available() capability detection
• get_active_bufnr() for buffer management

Integration Changes

• Main logic (init.lua): Enhanced @mention handling to skip terminal visibility checks for external provider
• Terminal module (terminal.lua): Added provider validation and selection logic
• Status command: Updated to provide specific guidance for external connections

Testing

• Added comprehensive unit tests for tmux provider (tmux_terminal_provider_spec.lua)
• Enhanced existing test suites with new provider support
• All tests maintain 100% coverage requirements

🎯 Provider Selection Logic

The provider = "auto" setting now follows this priority:

1. tmux - If running in tmux session
2. snacks - If folke/snacks.nvim is available
3. native - Neovim's built-in terminal
4. external - Must be explicitly configured

💡 Use Case Examples

Tmux Users:

# Auto-detected when in tmux
:ClaudeCode  # Creates tmux pane automatically

# Manual tmux command (works regardless of provider setting)
:ClaudeCodeTmux

External Terminal Workflows:

1. Configure with event = "VeryLazy" and provider = "external"
2. Neovim auto-starts MCP server on startup
3. Run claude in your preferred external terminal
4. Use :ClaudeCodeStatus for connection guidance

🧪 Testing Coverage

• Unit tests: Complete coverage for tmux provider functionality
• Component tests: Integration with terminal selection logic
• Mock testing: Tmux command execution and environment handling
• Error scenarios: Network failures, tmux unavailability, invalid configurations