fix: address terminal focus error when buffer is hidden #43

ThomasK33 · 2025-06-16T13:23:45Z

Summary

Comprehensive fix for issue #42 that implements a unified, connection-aware @ mention system while resolving terminal focus errors.

Closes #42

Key Features Implemented

🚀 Unified @ Mention System

Single send_at_mention() API for all @ mention operations
Intelligent connection detection and handling
Automatic queueing when Claude Code is offline
Smart terminal management based on connection state

🔧 Connection-Aware Behavior

When Claude is connected: Send immediately + ensure terminal visibility
When Claude is disconnected: Queue @ mention + launch terminal automatically
When Claude connects: Process all queued @ mentions with proper delays

⚡ Architecture Improvements

Centralized all @ mention logic from scattered command implementations
Applied DRY principles to eliminate code duplication
Enhanced error handling with proper timeouts and retry logic
Improved terminal visibility detection and management

Technical Changes

Core Implementation:

Added M.send_at_mention() as unified entry point for all @ mention operations
Implemented M.is_claude_connected() for real-time connection detection
Added queue management system with configurable timeouts
Created M._ensure_terminal_visible_if_connected() for smart terminal handling

Commands Updated:

ClaudeCodeSend: Now uses unified system instead of direct terminal opening
ClaudeCodeAdd: Migrated to connection-aware @ mention sending
ClaudeCodeTreeAdd: Enhanced with proper error handling and connection awareness
Selection module: Integrated with centralized @ mention system

Configuration:

Added connection_wait_delay, connection_timeout, queue_timeout options
Enhanced state management with queued_mentions and connection_timer

This provides a much more robust and user-friendly @ mention system that gracefully handles all connection states.

Foundation fix for #42 - removes automatic terminal opening behavior from ClaudeCodeSend command to prevent focus_terminal errors when terminal buffer is hidden. - Remove terminal.open() calls after successful ClaudeCodeSend operations - Update snacks terminal to check window validity before focus - Update tests to reflect new behavior - Update dev-config and documentation This establishes the foundation for the complete fix which will address the core focus_terminal issue in native terminal implementation. Change-Id: Ide3692617e5c6ce721782eab9cf8f2eeeeef3df5 Signed-off-by: Thomas Kosiewski <tk@coder.com>

Introduces a robust, centralized architecture for @ mention functionality that intelligently handles Claude Code connection states and provides seamless UX. Key Features: • Unified API: Single `send_at_mention()` function for all @ mention operations • Smart connection detection: Automatically detects if Claude Code is connected • Intelligent queueing: Queues @ mentions when offline, processes when connected • Automatic terminal management: Launches terminal when needed, shows when connected • Robust error handling: Proper timeouts, error propagation, and retry logic Architecture Improvements: • Centralized all @ mention logic from scattered command implementations • Applied DRY principles to eliminate code duplication • Added connection state management with configurable timeouts • Improved terminal visibility logic with connection awareness • Enhanced queue management for offline @ mentions All commands (ClaudeCodeSend, ClaudeCodeAdd, ClaudeCodeTreeAdd, selection module) now use the unified system, providing consistent behavior and better UX. Includes comprehensive test updates to support the new architecture. Change-Id: Ie4201162be96e066bbe9af4349228ef068f3a963 Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Refactor terminal visibility logic into reusable is_terminal_visible() function - Simplify ensure_visible() logic to use consistent visibility checks - Add oil.nvim support to file tree keybindings in README examples - Update dev-config.lua to include oil.nvim in supported file types - Fix terminal focus handling in send_at_mention to use terminal.ensure_visible() Change-Id: Ia5655ef53139d995330cfaa03ac347195678165f Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Add optional focus parameter to both snacks and native provider open() methods - Extract shared logic into ensure_terminal_visible_no_focus() helper function - Fix ensure_visible() to truly not focus by passing focus=false to providers - Fix toggle_open_no_focus() to use the same consistent no-focus behavior - Maintain backward compatibility by defaulting focus parameter to true - Return to original window in native provider when focus=false Addresses feedback about ensure_visible() contradicting its intent by calling provider.open() which always focused the terminal. Change-Id: I11635699095df7284232b7c959ade1e11c41dbc4 Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Add normalize_focus() helper function in both snacks and native providers - Replace duplicated focus defaulting logic with consistent helper calls - Remove unused normalize_focus() from main terminal.lua file - Maintain backward compatibility by defaulting focus to true - Clean up linting warnings This addresses the Copilot feedback about duplicated focus defaulting logic across both providers and simplifies future maintenance. Change-Id: I8387f264d85a3c097081f7976bc0a34b9b52485c Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Create shared claudecode.utils module with normalize_focus() function - Remove duplicated normalize_focus() from snacks and native providers - Update both providers to use utils.normalize_focus() - Fix queue_timeout inconsistency: update tests to use 5000ms (matching config default) - Maintain backward compatibility and functionality This addresses Copilot feedback about duplicated code and config inconsistencies. Change-Id: I6eb1496e680fb9c6d940d1b8baa62ab2eda9290f Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Update build_opts() documentation to explain focus parameter behavior - Add comprehensive comments explaining window restoration logic in native provider - Clarify that focus=false preserves user context in all terminal scenarios: - Existing terminal: stays in current window - Recovered terminal: stays in current window - New terminal: returns to original window - Improve maintainer understanding of focus control architecture Addresses Copilot feedback about documentation and behavior clarity. Change-Id: I06e785d5e2378b68fce41eb64018067d2754225d Signed-off-by: Thomas Kosiewski <tk@coder.com>

- Fix snacks provider to detect and show hidden terminals when focus=false - Add hidden terminal logic to native provider using show_hidden_terminal() - Both providers now properly handle the case where terminal buffer exists but has no window - Clean up debug logging after identifying and resolving the issue - Preserve user window context when focus=false in both providers This resolves the issue where @ mentions wouldn't show the terminal when it was hidden in the background. Change-Id: Ibdd884ce9f6b7b0b72d2a04fba611db2b8ff52e7 Signed-off-by: Thomas Kosiewski <tk@coder.com>

Copilot

Pull Request Overview

A fix for terminal focus issues when the terminal buffer is hidden, coupled with the rollout of a unified, connection-aware @ mention system.

Introduced normalize_focus utility and propagated a focus flag through both snacks and native terminal providers
Enhanced terminal providers (snacks.lua and native.lua) to correctly show or hide the terminal and respect the focus=false case
Updated configuration defaults/validation for connection management and adjusted tests/docs to align with the new behavior

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lua/claudecode/utils.lua	Added `normalize_focus` helper to default and validate focus
lua/claudecode/terminal/snacks.lua	Extended `open` to accept a focus flag and handle hidden terminals
lua/claudecode/terminal/native.lua	Added focus parameter to `open`, `show_hidden_terminal`, and related helpers
lua/claudecode/config.lua	Added `connection_wait_delay`, `connection_timeout`, `queue_timeout` defaults and validation
README.md	Updated Quick Setup example to reflect new config keys

Comments suppressed due to low confidence (2)

tests/unit/config_spec.lua:35

Add unit tests for the new config.validate rules on connection_wait_delay, connection_timeout, and queue_timeout to ensure invalid values are rejected.

      connection_wait_delay = 200,

README.md:229

In the Quick Setup example, the key config is used but the plugin expects opts. Update this to opts or clarify the correct field.

  config = true,

Copilot · 2025-06-17T14:54:16Z

lua/claudecode/utils.lua

+--- Normalizes focus parameter to default to true for backward compatibility
+--- @param focus boolean|nil The focus parameter
+--- @return boolean Normalized focus value
+function M.normalize_focus(focus)


[nitpick] Consider validating that focus is a boolean when provided; if callers pass a non-boolean, downstream logic may behave unexpectedly.

Suggested change

function M.normalize_focus(focus)

function M.normalize_focus(focus)

if focus ~= nil and type(focus) ~= "boolean" then

focus = true

end

Copilot · 2025-06-17T14:54:17Z

lua/claudecode/terminal/snacks.lua

  if not is_available() then
    vim.notify("Snacks.nvim terminal provider selected but Snacks.terminal not available.", vim.log.levels.ERROR)
    return
  end

+  focus = utils.normalize_focus(focus)
+
  if terminal and terminal:buf_valid() then


[nitpick] This nested if block is quite deep. Consider extracting sub-branches into helper functions or flattening the logic for better readability.

This release includes significant feature additions and bug fixes: **Version Updates:** - Updated main version table in lua/claudecode/init.lua (0.1.0-alpha → 0.2.0) - Updated client versions in scripts/claude_interactive.sh (3 locations) - Updated ClaudeCodeNvim version in scripts/lib_claude.sh - Removed prerelease flag for stable release **Documentation:** - Added comprehensive CHANGELOG.md with v0.2.0 release notes - Documented all merged PRs since v0.1.0 with proper references - Updated CLAUDE.md with detailed release process documentation - Fixed diff keymap references in README.md (<leader>da → <leader>aa) **Features Added (since v0.1.0):** - Diagnostics integration (#34) - File explorer support for oil.nvim, nvim-tree, neotree (#27, #22) - Enhanced terminal management with ClaudeCodeFocus command (#40) - Auto terminal provider detection (#36) - Customizable diff keymaps via LazyVim spec (#47) **Bug Fixes:** - Terminal focus errors when buffer hidden (#43) - Improved diff acceptance behavior (#41) - Fixed syntax highlighting in proposed diff view (#32) - Visual selection range handling improvements (#26) - Native terminal bufhidden behavior (#39) All code quality checks pass and documentation is updated for maintainability. Change-Id: I0e4e7c9bae98df922356dc8b8aa0acd7e8293a48 Signed-off-by: Thomas Kosiewski <tk@coder.com>

ThomasK33 changed the title ~~fix: address terminal focus error when buffer is hidden (#42)~~ fix: address terminal focus error when buffer is hidden Jun 17, 2025

ThomasK33 added 2 commits June 17, 2025 13:54

ThomasK33 marked this pull request as ready for review June 17, 2025 11:56

ThomasK33 requested a review from Copilot June 17, 2025 12:03

ThomasK33 force-pushed the fix/issue-42-terminal-focus-error branch from 81faf4d to dd81f17 Compare June 17, 2025 12:05