feat(terminal): add integrated Claude terminal support

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

Author: ThomasK33

.github/workflows/claude-review.yaml

@@ -0,0 +1,38 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize] # Runs on new PRs and updates
+
+permissions:
+  contents: read
+
+jobs:
+  code-review:
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the code to allow git diff operations
+      - name: Checkout code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          fetch-depth: 0 # Fetch full history for accurate diffs
+          persist-credentials: false
+
+      - name: Run Code Review with Claude
+        id: code-review
+        uses: anthropics/claude-code-action@8b9d5bb25a638c9aa5103496c0139d99b4936d42 # beta
+        with:
+          # Define the review focus areas
+          prompt: "Review the PR changes. Focus on code quality, potential bugs, and performance issues. Suggest improvements where appropriate."
+
+          # Limited tools for safer review operations
+          allowed_tools: >-
+            [
+              "Bash(git diff --name-only HEAD~1)", 
+              "Bash(git diff HEAD~1)", 
+              "View", 
+              "GlobTool", 
+              "GrepTool"
+            ]
+
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/claude.yml

@@ -10,6 +10,9 @@ on:
   pull_request_review:
     types: [submitted]
 
+permissions:
+  contents: read
+
 jobs:
   claude:
     if: |
@@ -23,12 +26,13 @@ jobs:
       id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
         with:
           fetch-depth: 1
+          persist-credentials: false
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@8b9d5bb25a638c9aa5103496c0139d99b4936d42 # beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/test.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   unit-tests:
     runs-on: ubuntu-latest
@@ -14,21 +17,23 @@ jobs:
         neovim-version: ["stable", "nightly"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          persist-credentials: false
 
       - name: Setup Neovim
-        uses: rhysd/action-setup-vim@v1
+        uses: rhysd/action-setup-vim@8e931b9954b19d4203d5caa5ff5521f3bc21dcc7 # v1.4.2
         with:
           neovim: true
           version: ${{ matrix.neovim-version }}
 
       - name: Setup Lua
-        uses: leafo/gh-actions-lua@v10
+        uses: leafo/gh-actions-lua@8aace3457a2fcf3f3c4e9007ecc6b869ff6d74d6 # v11
         with:
           luaVersion: "5.1"
 
       - name: Setup Luarocks
-        uses: leafo/gh-actions-luarocks@v4
+        uses: leafo/gh-actions-luarocks@4c082a5fad45388feaeb0798dbd82dbd7dc65bca # v5
 
       - name: Install dependencies
         run: |
@@ -52,7 +57,7 @@ jobs:
           luacov-console -r lcov > lcov.info
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8 # v4
         with:
           files: ./tests/lcov.info
           fail_ci_if_error: false
@@ -65,18 +70,20 @@ jobs:
         neovim-version: ["stable"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+        with:
+          persist-credentials: false
 
       - name: Setup Neovim
-        uses: rhysd/action-setup-vim@v1
+        uses: rhysd/action-setup-vim@8e931b9954b19d4203d5caa5ff5521f3bc21dcc7 # v1.4.2
         with:
           neovim: true
           version: ${{ matrix.neovim-version }}
 
       - name: Install test dependencies
         run: |
           git clone --depth 1 https://github.com/nvim-lua/plenary.nvim ~/.local/share/nvim/site/pack/vendor/start/plenary.nvim
-          ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start/claudecode.nvim
+          ln -s "$(pwd)" ~/.local/share/nvim/site/pack/vendor/start/claudecode.nvim
 
       - name: Run integration tests
         run: |

ARCHITECTURE.md

@@ -77,14 +77,32 @@ The plugin monitors text selections in Neovim:
 - Formats selection data according to MCP protocol
 - Sends updates to Claude via WebSocket
 
-### 5. Environment Integration
+### 5. Terminal Integration
+
+The plugin provides a dedicated terminal interface for Claude Code CLI:
+
+- Uses [folke/snacks.nvim](https://github.com/folke/snacks.nvim) for terminal management
+- Creates a vertical split terminal with customizable size and position
+- Supports focus, toggle, and close operations
+- Maintains terminal state across operations
+- Automatically cleans up on window close
+
+```
+┌─────────────┐    ┌─────────────────┐    ┌─────────────┐
+│             │    │                 │    │             │
+│  Neovim     │◄───┤ Claude Terminal │◄───┤  Claude CLI │
+│  Buffers    │    │ (Snacks.nvim)   │    │             │
+└─────────────┘    └─────────────────┘    └─────────────┘
+```
+
+### 6. Environment Integration
 
 The plugin manages the environment for Claude CLI:
 
 - Sets required environment variables:
   - `CLAUDE_CODE_SSE_PORT`: The WebSocket server port
   - `ENABLE_IDE_INTEGRATION`: Enabled flag
-- Provides terminal integration for launching Claude
+- Provides configuration for the terminal command
 
 ## Message Flow
 
@@ -141,6 +159,7 @@ lua/claudecode/
 │   ├── editor.lua        # Editor information tools
 │   └── selection.lua     # Selection management tools
 ├── selection.lua         # Selection tracking
+├── terminal.lua          # Terminal management (uses Snacks.nvim)
 ├── environment.lua       # Environment variable management
 └── util.lua              # Utility functions
 ```
@@ -170,6 +189,7 @@ tests/
 ├── unit/
 │   ├── config_spec.lua
 │   ├── server_spec.lua
+│   ├── terminal_spec.lua
 │   └── tools_spec.lua
 ├── component/
 │   ├── server_spec.lua

Makefile

@@ -8,7 +8,7 @@ check:
 	@echo "Checking Lua files for syntax errors..."
 	@find lua -name "*.lua" -type f -exec lua -e "assert(loadfile('{}'))" \;
 	@echo "Running luacheck..."
-	@luacheck lua/ --no-unused-args --no-max-line-length || echo "⚠️  Luacheck warnings - continuing anyway"
+	@luacheck lua/ tests/ --no-unused-args --no-max-line-length
 
 # Format all files
 format:

README.md

@@ -12,16 +12,19 @@ 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
-- 🖥️ Terminal integration for launching Claude with proper environment
+- 🖥️ Interactive vertical split terminal for Claude sessions (via `folke/snacks.nvim`)
 - 🔒 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: 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.
+
 ## Installation
 
 ### Using [lazy.nvim](https://github.com/folke/lazy.nvim)
@@ -31,8 +34,11 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
   "ThomasK33/claudecode.nvim",
   dependencies = {
     "nvim-lua/plenary.nvim",
+    "folke/snacks.nvim", -- Added dependency
   },
   config = function()
+    -- Ensure snacks is loaded if you want to use the terminal immediately
+    -- require("snacks") -- Or handle this in your init.lua
     require("claudecode").setup({
       -- Optional configuration
     })
@@ -45,7 +51,10 @@ A Neovim plugin that integrates with Claude Code CLI to provide a seamless AI co
 ```lua
 use {
   "ThomasK33/claudecode.nvim",
-  requires = { "nvim-lua/plenary.nvim" },
+  requires = {
+    "nvim-lua/plenary.nvim",
+    "folke/snacks.nvim", -- Added dependency
+  },
   config = function()
     require("claudecode").setup({
       -- Optional configuration
@@ -64,13 +73,28 @@ return {
     "ThomasK33/claudecode.nvim",
     dependencies = {
       "nvim-lua/plenary.nvim",
+      "folke/snacks.nvim", -- Added dependency
     },
     opts = {
-      -- Optional configuration
+      -- Optional configuration for claudecode main
+      -- Example:
+      -- terminal_cmd = "claude --magic-flag",
+
+      -- Configuration for the interactive terminal can also be nested here:
+      terminal = {
+        split_side = "left",            -- "left" or "right"
+        split_width_percentage = 0.4, -- 0.0 to 1.0
+      },
     },
+    -- 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>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" },
     },
   },
 }
@@ -87,16 +111,27 @@ return {
     name = "claudecode.nvim",
     dependencies = {
       "nvim-lua/plenary.nvim",
+      "folke/snacks.nvim", -- Added dependency
     },
     dev = true,
     opts = {
-      -- Development configuration
+      -- Development configuration for claudecode main
       log_level = "debug",
       auto_start = true,  -- Optional: auto-start the server
+
+      -- Example terminal configuration for dev:
+      terminal = {
+        split_side = "right",
+        split_width_percentage = 0.25,
+      },
     },
+    config = true,
     keys = {
       { "<leader>cc", "<cmd>ClaudeCodeStart<cr>", desc = "Start Claude Code" },
       { "<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" },
     },
   },
 }
@@ -120,13 +155,24 @@ require("claudecode").setup({
   auto_start = false,
 
   -- Custom terminal command to use when launching Claude
-  terminal_cmd = nil, -- e.g., "toggleterm"
+  -- This command is used by the new interactive terminal feature.
+  -- If nil or empty, it defaults to "claude".
+  terminal_cmd = nil, -- e.g., "my_claude_wrapper_script" or "claude --project-foo"
 
   -- Log level (trace, debug, info, warn, error)
   log_level = "info",
 
   -- Enable sending selection updates to Claude
   track_selection = true,
+
+  -- Configuration for the interactive terminal (passed to claudecode.terminal.setup by the main setup function)
+  terminal = {
+    -- Side for the vertical split ('left' or 'right')
+    split_side = "right", -- Default
+
+    -- Width of the terminal as a percentage of total editor width (0.0 to 1.0)
+    split_width_percentage = 0.30, -- Default
+  }
 })
 ```
 
@@ -154,6 +200,9 @@ require("claudecode").setup({
 - `:ClaudeCodeStop` - Stop the server
 - `:ClaudeCodeStatus` - Show connection status
 - `:ClaudeCodeSend` - Send current selection to Claude
+- `:ClaudeCode` - Toggle the Claude Code interactive terminal window
+- `:ClaudeCodeOpen` - Open (or focus) the Claude Code terminal window
+- `:ClaudeCodeClose` - Close the Claude Code terminal window
 
 ## Keymaps
 
@@ -162,6 +211,10 @@ 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", "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" })
 ```
 
 ## Architecture

flake.nix

@@ -21,7 +21,11 @@
             nixpkgs-fmt.enable = true; # Nix formatter
             prettier.enable = true; # Markdown/YAML/JSON formatter
             shfmt.enable = true; # Shell formatter
+            actionlint.enable = true; # GitHub Actions linter
+            zizmor.enable = true; # GitHub Actions security analyzer
+            shellcheck.enable = true; # Shell script analyzer
           };
+          settings.formatter.shellcheck.options = [ "--exclude=SC1091,SC2016" ];
         };
       in
       {