merge: Integrate PR coder#117 with add-unsafe-command branch features

- Merged external terminal provider support from PR coder#117
- Preserved add-unsafe-command branch features (monitoring, notifications, anti-flicker)
- Combined terminal integration improvements from both branches
- Maintained backward compatibility with existing configurations
- Added mini.files integration support
- Enhanced documentation with new terminal providers and integration fixtures
- Resolved conflicts by keeping the best features from both branches

Author: pittcat

.claude/hooks/format.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# Claude Code Hook: Format Files
+# Triggers after Claude edits/writes files and runs nix fmt
+#
+# Environment variables provided by Claude Code:
+# - CLAUDE_PROJECT_DIR: Path to the project directory
+# - CLAUDE_TOOL_NAME: Name of the tool that was executed
+# - CLAUDE_TOOL_ARGS: JSON string containing tool arguments
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Log function
+log() {
+  echo -e "[$(date '+%H:%M:%S')] $1" >&2
+}
+
+# Parse tool arguments to get the file path
+get_file_path() {
+  # Read hook input from stdin
+  local hook_input
+  if [ -t 0 ]; then
+    # No stdin input available
+    log "DEBUG: No stdin input available"
+    return
+  fi
+
+  hook_input=$(cat)
+  log "DEBUG: Hook input = $hook_input"
+
+  # Try to extract file_path from tool_input
+  local file_path
+  file_path=$(echo "$hook_input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+  if [ -n "$file_path" ]; then
+    echo "$file_path"
+    return
+  fi
+
+  # Try extracting any file path from the input
+  local any_file_path
+  any_file_path=$(echo "$hook_input" | grep -o '"[^"]*\.[^"]*"' | sed 's/"//g' | head -1)
+
+  if [ -n "$any_file_path" ]; then
+    echo "$any_file_path"
+    return
+  fi
+
+  log "DEBUG: Could not extract file path from hook input"
+}
+
+# Main logic
+main() {
+  log "${YELLOW}Claude Code Hook: File Formatter${NC}"
+
+  # Get the file path from tool arguments
+  FILE_PATH=$(get_file_path)
+
+  if [ -z "$FILE_PATH" ]; then
+    log "${RED}Error: Could not determine file path from tool arguments${NC}"
+    exit 1
+  fi
+
+  log "Tool: ${CLAUDE_TOOL_NAME:-unknown}, File: $FILE_PATH"
+
+  # Check if file exists
+  if [ ! -f "$FILE_PATH" ]; then
+    log "${RED}Error: File does not exist: $FILE_PATH${NC}"
+    exit 1
+  fi
+
+  log "${YELLOW}Formatting file with nix fmt...${NC}"
+
+  # Change to project directory
+  cd "${CLAUDE_PROJECT_DIR}"
+
+  # Run nix fmt on the file
+  if nix fmt "$FILE_PATH" 2>/dev/null; then
+    log "${GREEN}✓ Successfully formatted: $FILE_PATH${NC}"
+    exit 0
+  else
+    EXIT_CODE=$?
+    log "${RED}✗ nix fmt failed with exit code $EXIT_CODE${NC}"
+    log "${RED}This indicates the file has formatting issues that need manual attention${NC}"
+
+    # Don't fail the hook - just warn about formatting issues
+    # This allows Claude's operation to continue while alerting about format problems
+    log "${YELLOW}Continuing with Claude's operation, but please fix formatting issues${NC}"
+    exit 0
+  fi
+}
+
+# Run main function
+main "$@"

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.devcontainer/Dockerfile

@@ -0,0 +1,29 @@
+FROM mcr.microsoft.com/devcontainers/base:ubuntu
+
+# Install Nix
+RUN apt-get update && apt-get install -y \
+  curl \
+  xz-utils \
+  sudo \
+  && rm -rf /var/lib/apt/lists/*
+
+# Create vscode user if it doesn't exist
+RUN if ! id -u vscode > /dev/null 2>&1; then \
+  useradd -m -s /bin/bash vscode && \
+  echo "vscode ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers; \
+  fi
+
+# Switch to vscode user for Nix installation
+USER vscode
+WORKDIR /home/vscode
+
+# Install Nix in single-user mode
+RUN curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
+
+# Add Nix to PATH and configure for the shell
+RUN echo '. /home/vscode/.nix-profile/etc/profile.d/nix.sh' >> /home/vscode/.bashrc && \
+  mkdir -p /home/vscode/.config/nix && \
+  echo 'experimental-features = nix-command flakes' >> /home/vscode/.config/nix/nix.conf
+
+# Keep container running
+CMD ["sleep", "infinity"]

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "claudecode.nvim Development",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+      },
+      "extensions": ["jnoortheen.nix-ide"]
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "remoteUser": "vscode"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Source Nix environment
+. /home/vscode/.nix-profile/etc/profile.d/nix.sh
+
+# Verify Nix is available
+if ! command -v nix &>/dev/null; then
+  echo "Error: Nix is not installed properly"
+  exit 1
+fi
+
+echo "✅ Nix is installed and available"
+echo ""
+echo "📦 claudecode.nvim Development Container Ready!"
+echo ""
+echo "To enter the development shell with all dependencies, run:"
+echo "  nix develop"
+echo ""
+echo "This will provide:"
+echo "  - Neovim"
+echo "  - Lua and LuaJIT"
+echo "  - busted (test framework)"
+echo "  - luacheck (linter)"
+echo "  - stylua (formatter)"
+echo "  - All other development tools"
+echo ""
+echo "You can also run development commands directly:"
+echo "  - make        # Run full validation (format, lint, test)"
+echo "  - make test   # Run tests"
+echo "  - make check  # Run linter"
+echo "  - make format # Format code"

.envrc

@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 
-if ! has nix_direnv_version || ! nix_direnv_version 3.0.6; then
-  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.6/direnvrc" "sha256-RYcUJaRMf8oF5LznDrlCXbkOQrywm0HDv1VjYGaJGdM="
+if ! has nix_direnv_version || ! nix_direnv_version 3.0.7; then
+  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.7/direnvrc" "sha256-RYcUJaRMf8oF5LznDrlCXbkOQrywm0HDv1VjYGaJGdM="
 fi
 
 nix_direnv_manual_reload
 
 use flake .
+
+# Add fixtures/bin to PATH for nvim config aliases
+PATH_add fixtures/bin

.gitignore

@@ -61,4 +61,6 @@ luacov.stats.out
 # direnv
 .direnv
 
-.claude
+.claude/*
+!.claude/settings.json
+!.claude/hooks/

.luarc.json

@@ -57,6 +57,24 @@ Is it about viewing CODE with syntax? use 'bat'
 - `nix develop` - Enter development shell with all dependencies
 - `nix fmt` - Format all files using nix formatter
 
+### Integration Testing with Fixtures
+
+The `fixtures/` directory contains test Neovim configurations for verifying plugin integrations:
+
+- `vv <config>` - Start Neovim with a specific fixture configuration
+- `vve <config>` - Start Neovim with a fixture config in edit mode
+- `list-configs` - Show available fixture configurations
+- Source `fixtures/nvim-aliases.sh` to enable these commands
+
+**Available Fixtures**:
+
+- `netrw` - Tests with Neovim's built-in file explorer
+- `nvim-tree` - Tests with nvim-tree.lua file explorer
+- `oil` - Tests with oil.nvim file explorer
+- `mini-files` - Tests with mini.files file explorer
+
+**Usage**: `source fixtures/nvim-aliases.sh && vv oil` starts Neovim with oil.nvim configuration
+
 ## Architecture Overview
 
 ### Core Components
@@ -66,7 +84,7 @@ Is it about viewing CODE with syntax? use 'bat'
 3. **Lock File System** (`lua/claudecode/lockfile.lua`) - Creates discovery files for Claude CLI at `~/.claude/ide/`
 4. **Selection Tracking** (`lua/claudecode/selection.lua`) - Monitors text selections and sends updates to Claude
 5. **Diff Integration** (`lua/claudecode/diff.lua`) - Native Neovim diff support for Claude's file comparisons
-6. **Terminal Integration** (`lua/claudecode/terminal.lua`) - Manages Claude CLI terminal sessions
+6. **Terminal Integration** (`lua/claudecode/terminal.lua`) - Manages Claude CLI terminal sessions with support for internal Neovim terminals and external terminal applications
 7. **Session Management** (`lua/claudecode/session_manager.lua`) - Parses and manages Claude CLI session files for resume functionality
 
 ### WebSocket Server Implementation
@@ -138,6 +156,28 @@ The WebSocket server implements secure authentication using:
 <leader>ax               " Default key mapping for session selection
 ```
 
+### Terminal Integration Options
+
+**Internal Terminals** (within Neovim):
+
+- **Snacks.nvim**: `terminal/snacks.lua` - Advanced terminal with floating windows
+- **Native**: `terminal/native.lua` - Built-in Neovim terminal as fallback
+
+**External Terminals** (separate applications):
+
+- **External Provider**: `terminal/external.lua` - Launches Claude in external terminal apps
+
+**Configuration Example**:
+
+```lua
+opts = {
+  terminal = {
+    provider = "external",  -- "auto", "snacks", "native", or "external"
+    external_terminal_cmd = "alacritty -e %s"  -- Required for external provider
+  }
+}
+```
+
 ### Key File Locations
 
 - `lua/claudecode/init.lua` - Main entry point and setup
@@ -286,7 +326,36 @@ Enable detailed authentication logging by setting:
 
 ```lua
 require("claudecode").setup({
-  log_level = "debug"  -- Shows auth token generation, validation, and failures
+  log_level = "debug",  -- Shows auth token generation, validation, and failures
+  diff_opts = {
+    keep_terminal_focus = true,  -- If true, moves focus back to terminal after diff opens
+  },
+})
+```
+
+### Configuration Options
+
+#### Diff Options
+
+The `diff_opts` configuration allows you to customize diff behavior:
+
+- `keep_terminal_focus` (boolean, default: `false`) - When enabled, keeps focus in the Claude Code terminal when a diff opens instead of moving focus to the diff buffer. This allows you to continue using terminal keybindings like `<CR>` for accepting/rejecting diffs without accidentally triggering other mappings.
+- `open_in_new_tab` (boolean, default: `false`) - Open diffs in a new tab instead of the current tab.
+- `hide_terminal_in_new_tab` (boolean, default: `false`) - When opening diffs in a new tab, do not show the Claude terminal split in that new tab. The terminal remains in the original tab, giving maximum screen estate for reviewing the diff.
+
+**Example use case**: If you frequently use `<CR>` or arrow keys in the Claude Code terminal to accept/reject diffs, enable this option to prevent focus from moving to the diff buffer where `<CR>` might trigger unintended actions.
+
+```lua
+require("claudecode").setup({
+  diff_opts = {
+    keep_terminal_focus = true,  -- If true, moves focus back to terminal after diff opens
+    open_in_new_tab = true,      -- Open diff in a separate tab
+    hide_terminal_in_new_tab = true, -- In the new tab, do not show Claude terminal
+    auto_close_on_accept = true,
+    show_diff_stats = true,
+    vertical_split = true,
+    open_in_current_tab = true,
+  },
 })
 ```
 
@@ -351,7 +420,7 @@ Key configuration options available in `require("claudecode").setup({})`:
 ### Integration Support
 
 - Terminal integration supports both snacks.nvim and native Neovim terminal
-- Compatible with popular file explorers (nvim-tree, oil.nvim, neo-tree)
+- Compatible with popular file explorers (nvim-tree, oil.nvim, neo-tree, mini.files)
 - Visual selection tracking across different selection modes
 
 ### Common Troubleshooting
@@ -425,6 +494,23 @@ rg "0\.1\.0" .  # Should only show CHANGELOG.md historical entries
 4. **Document Changes**: Update relevant documentation (this file, PROTOCOL.md, etc.)
 5. **Commit**: Only commit after successful `make` execution
 
+### Integration Development Guidelines
+
+**Adding New Integrations** (file explorers, terminals, etc.):
+
+1. **Implement Integration**: Add support in relevant modules (e.g., `lua/claudecode/tools/`)
+2. **Create Fixture Configuration**: **REQUIRED** - Add a complete Neovim config in `fixtures/[integration-name]/`
+3. **Test Integration**: Use fixture to verify functionality with `vv [integration-name]`
+4. **Update Documentation**: Add integration to fixtures list and relevant tool documentation
+5. **Run Full Test Suite**: Ensure `make` passes with new integration
+
+**Fixture Requirements**:
+
+- Complete Neovim configuration with plugin dependencies
+- Include `dev-claudecode.lua` with development keybindings
+- Test all relevant claudecode.nvim features with the integration
+- Document any integration-specific behaviors or limitations
+
 ### MCP Tool Development Guidelines
 
 **Adding New Tools**: