code-preview.nvim

A Neovim plugin that shows a diff preview before your AI coding agent applies any file change — letting you review exactly what's changing before accepting.

Supports Claude Code, OpenCode, GitHub Copilot CLI, and OpenAI Codex CLI as backends.

Demo

Claude Code

OpenCode

GitHub Copilot CLI

OpenAI Codex CLI

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
  • Claude Code
  • OpenCode
  • GitHub Copilot CLI
  • OpenAI Codex CLI
• How it works
• Configuration
• Commands
• Keymaps
• Diff Layouts
• Neo-tree Integration
• Testing
• Troubleshooting

Features

• Diff preview — side-by-side or inline diff opens in Neovim before any file is written
• Multiple layouts — tab, vsplit, or GitHub-style inline diff with syntax highlighting
• Neo-tree integration — file tree indicators show which files are being modified, created, or deleted
• Multi-backend — works with Claude Code, OpenCode, GitHub Copilot CLI, and OpenAI Codex CLI
• No Python dependency — file transformations use nvim --headless -l

Requirements

• Neovim >= 0.10

For Claude Code backend:

• Claude Code CLI with hooks support
• jq — for JSON parsing in hook scripts

For OpenCode backend:

• OpenCode >= 1.3.0

For GitHub Copilot CLI backend:

• GitHub Copilot CLI (generally available since Feb 2026)

For OpenAI Codex CLI backend:

• OpenAI Codex CLI (recent enough to support apply_patch PreToolUse hooks; older builds only fired hooks for Bash)
• jq — for hook payload translation

Installation

lazy.nvim

{
  "Cannon07/code-preview.nvim",
  config = function()
    require("code-preview").setup()
  end,
}

Manual (path-based)

vim.opt.rtp:prepend("/path/to/code-preview.nvim")
require("code-preview").setup()

Quick Start

Claude Code

1. Install the plugin and call setup()
2. Open a project in Neovim
3. Run :CodePreviewInstallClaudeCodeHooks — writes hooks to .claude/settings.local.json
4. Restart Claude Code CLI in the project directory
5. Ask Claude to edit a file — a diff opens automatically in Neovim
6. Accept/reject in the CLI; the diff closes automatically on accept
7. If rejected, press <leader>dq to close the diff manually

OpenCode

1. Install the plugin and call setup()
2. Open a project in Neovim
3. Run :CodePreviewInstallOpenCodeHooks — copies the plugin to .opencode/plugins/
4. Ensure your OpenCode config (~/.config/opencode/opencode.json) has permission prompts enabled:

   {
     "permission": {
       "edit": "ask",
       "bash": "ask"
     }
   }
   

5. Start OpenCode in the project directory
6. Ask OpenCode to edit a file — a diff opens automatically in Neovim
7. Accept/reject in OpenCode; the diff closes automatically on accept
8. If rejected, press <leader>dq to close the diff manually

GitHub Copilot CLI

1. Install the plugin and call setup()
2. Open a project in Neovim
3. Run :CodePreviewInstallCopilotCliHooks — writes .github/hooks/code-preview.json
4. Start Copilot CLI in the project directory
5. Ask Copilot to edit a file — a diff opens automatically in Neovim
6. Accept/reject in the CLI; the diff closes automatically on accept
7. If rejected, press <leader>dq to close the diff manually

Note: Copilot CLI does not fire post-tool hooks on rejection, so rejected diffs remain open until you dismiss them (same as Claude Code).

OpenAI Codex CLI

1. Install the plugin and call setup()

2. Open a project in Neovim

3. Run :CodePreviewInstallCodexCliHooks — writes .codex/hooks.json

4. The diff-preview workflow only makes sense when Codex asks before applying edits. Create or edit .codex/config.toml (project-local) or ~/.codex/config.toml (global) and add:

   approval_policy = "on-request"
   sandbox_mode    = "read-only"
   

   approval_policy = "on-request" and sandbox_mode = "read-only" ensure Codex prompts you before every edit, so the diff preview has time to open and you have time to review. Without them, Codex may apply changes without prompting and the preview window will never block on your decision.

   Note on the hooks feature flag: Modern Codex enables hooks by default — no [features] entry is required. If you previously disabled them with [features] hooks = false (or the legacy codex_hooks = false), remove that line. :CodePreviewStatus and :checkhealth code-preview will warn if hooks are explicitly disabled.

5. Start Codex CLI in the project directory

6. Ask Codex to edit a file — a diff opens automatically in Neovim

7. Accept/reject in the CLI; the diff closes automatically on accept

8. If rejected, press <leader>dq to close the diff manually

Note: Today's Codex models route all file edits through the apply_patch tool. New file creation that Codex performs via shell redirection (e.g. printf … > foo.txt) is not previewed — only apply_patch and edits via the dedicated Edit/Write tools (when emitted) are.

How it works

AI Agent (terminal)                              Neovim
        |                                          |
   Proposes an Edit                                |
        |                                          |
   Hook/plugin fires ──→ compute diff ──→ RPC → show_diff()
        |                                          | (side-by-side or inline)
   CLI: "Accept? (y/n)"                            |
        |                                     User reviews diff
   User accepts/rejects                            |
        |                                          |
   Post hook fires ────→ cleanup ─────→ RPC → close_diff()

Claude Code uses shell-based hooks (PreToolUse/PostToolUse) configured in .claude/settings.local.json.

OpenCode uses a TypeScript plugin (tool.execute.before/tool.execute.after) loaded from .opencode/plugins/.

GitHub Copilot CLI uses shell-based hooks (preToolUse/postToolUse) configured in .github/hooks/code-preview.json. The adapter translates Copilot's tool vocabulary (apply_patch, edit, create, bash) into the same normalized format used by the other backends.

OpenAI Codex CLI uses shell-based hooks (PreToolUse/PostToolUse) configured in .codex/hooks.json. Hooks are enabled by default in modern Codex; the only way to silence them is [features] hooks = false (or the legacy codex_hooks = false) in .codex/config.toml. The adapter passes Bash through and rewrites apply_patch (whose patch text lives in tool_input.command) into the canonical ApplyPatch shape with tool_input.patch_text.

All backends communicate with Neovim via RPC (nvim --server <socket> --remote-send).

Configuration

All options with defaults:

require("code-preview").setup({
  debug = false,         -- enable debug logging to stdpath("log")/code-preview.log
  diff = {
    layout   = "tab",    -- "tab" (new tab) | "vsplit" (current tab) | "inline" (GitHub-style)
    labels   = { current = "CURRENT", proposed = "PROPOSED" },
    equalize   = true,   -- 50/50 split widths (tab/vsplit only)
    full_file  = true,   -- show full file, not just diff hunks (tab/vsplit only)
    visible_only = false, -- skip diffs for files not open in any Neovim buffer
    defer_claude_permissions = false, -- for Claude Code: let its own settings decide, don't prompt
  },
  highlights = {
    current = {          -- CURRENT (original) side — tab/vsplit layouts
      DiffAdd    = { bg = "#4c2e2e" },
      DiffDelete = { bg = "#4c2e2e" },
      DiffChange = { bg = "#4c3a2e" },
      DiffText   = { bg = "#5c3030" },
    },
    proposed = {         -- PROPOSED side — tab/vsplit layouts
      DiffAdd    = { bg = "#2e4c2e" },
      DiffDelete = { bg = "#4c2e2e" },
      DiffChange = { bg = "#2e3c4c" },
      DiffText   = { bg = "#3e5c3e" },
    },
    inline = {           -- inline layout
      added        = { bg = "#2e4c2e" },          -- added line background
      removed      = { bg = "#4c2e2e" },          -- removed line background
      added_text   = { bg = "#3a6e3a" },          -- changed characters (added)
      removed_text = { bg = "#6e3a3a" },          -- changed characters (removed)
    },
  },
})

Commands

| Command | Description | |---------|-------------| | :CodePreviewInstallClaudeCodeHooks | Install Claude Code hooks to .claude/settings.local.json | | :CodePreviewUninstallClaudeCodeHooks | Remove Claude Code hooks (leaves other hooks intact) | | :CodePreviewInstallOpenCodeHooks | Install OpenCode plugin to .opencode/plugins/ | | :CodePreviewUninstallOpenCodeHooks | Remove OpenCode plugin | | :CodePreviewInstallCopilotCliHooks | Install Copilot CLI hooks to .github/hooks/code-preview.json | | :CodePreviewUninstallCopilotCliHooks | Remove Copilot CLI hooks | | :CodePreviewInstallCodexCliHooks | Install Codex CLI hooks to .codex/hooks.json | | :CodePreviewUninstallCodexCliHooks | Remove Codex CLI hooks | | :CodePreviewCloseDiff | Manually close the diff (use a