godotdev.nvim/doc/neovim-external-editor-setup.md

Godot → Neovim External Editor Setup

This setup allows you to click on a script in Godot and open it directly in Neovim running in a GUI terminal (e.g., Ghostty), with the buffer focused and optional tab or vertical split support.

Features

• Open files in Neovim from Godot with the same window (default)
• Focus the file buffer automatically
• Bring your GUI terminal (Ghostty, Alacritty, Kitty, Wezterm, etc.) to the front
• Optional --tab or --vsplit mode
• Terminal name can be passed as an argument; defaults to ghostty

Workflow Diagram

+----------------+      clicks script       +-------------------------+
|                | ---------------------->  |                         |
|     Godot      |                          |    godot-nvr.sh script  |
|  (Editor UI)   |                          |  (external launcher)    |
+----------------+                          +-------------------------+
                                                    |
                                                    | opens/jumps file
                                                    v
                                            +-------------------------+
                                            |                         |
                                            |      Neovim             |
                                            |  (remote buffer via     |
                                            |     nvr socket)         |
                                            +-------------------------+
                                                    |
                                                    | brings terminal to front
                                                    v
                                            +-------------------------+
                                            |                         |
                                            |   GUI Terminal          |
                                            |   (Ghostty, Alacritty)  |
                                            +-------------------------+

• Step 1: Click a script in Godot
• Step 2: godot-nvr.sh is called
• Step 3: File opens in Neovim via nvr
• Step 4: GUI terminal is brought to the front

Requirements

• macOS (tested)
• Neovim with nvr installed
• A GUI terminal (e.g., Ghostty, Alacritty, iTerm)
• Optional: tmux (pane switching inside tmux is not fully supported)

Installation

1. Install nvr if not already installed:

   pip3 install neovim-remote
   

2. Save the launcher script:

   mkdir -p ~/.local/bin
   touch ~/.local/bin/godot-nvr.sh
   

3. Create the script: Save this as ~/.local/bin/godot-nvr.sh

   #!/usr/bin/env bash
   #
   # godot-nvr.sh
   #
   # Usage:
   #   godot-nvr.sh [TERMINAL_NAME] [--tab|--vsplit] <file>[:line[:col]]
   #
   # Example:
   #   godot-nvr.sh ghostty --tab ~/project/main.gd:10
   
   TERMINAL_APP="${1:-ghostty}" # default: ghostty
   shift
   
   MODE=""
   FILE=""
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --tab)
         MODE="--remote-tab"
         shift
         ;;
       --vsplit)
         MODE="--remote-send '<C-w>v:edit '"
         shift
         ;;
       *)
         FILE="$1"
         shift
         ;;
     esac
   done
   
   # Open file in Neovim
   if [[ -n "$MODE" && "$MODE" == *remote-send* ]]; then
     nvr --remote-send "<C-\\><C-n><C-w>v:edit ${FILE}<CR>"
   elif [[ -n "$MODE" ]]; then
     nvr $MODE "$FILE"
   else
     nvr --remote "$FILE"
   fi
   
   # Bring terminal GUI to front
   if command -v osascript &>/dev/null; then
     osascript -e "tell application \"$TERMINAL_APP\" to activate"
   fi
   
   

4. And make it executable:

   chmod +x ~/.local/bin/godot-nvr.sh
   

Setup in Godot

1. Go to Editor Settings → External Editor

2. Set Exec Path:

    /Users/YOUR_USERNAME/.local/bin/godot-nvr.sh
   

3. Set Exec Flags:

   • Default (same window):

     +{line} {file}
     
     

   • Open in a tab:

     --tab +{line} {file}
     
     

   • Open in vertical split:

     --vsplit +{line} {file}
     
     

   • Specify terminal explicitly:

     alacritty +{line} {file}
     
     

Usage

• Click a script in Godot → opens in Neovim
• Neovim buffer is focused
• GUI terminal comes to front
• Optional tab/vsplit works
• Terminal argument overrides default "ghostty"

Notes

• tmux pane switching is not supported reliably from Godot
• Ensure the Neovim socket path (/private/tmp/nvim.pipe) matches your setup
• Tested with Ghostty, should work with other GUI terminals
• This README now provides clear instructions and a visual workflow so other users can reproduce your Godot → Neovim + Ghostty setup easily.

Troubleshooting

Quick Test (outside Godot)

Before testing inside Godot, confirm the script works standalone:

~/.local/bin/godot-nvr.sh /path/to/file.gd:10

Expected:

• The file opens in your running Neovim instance.
• The buffer is focused.
• Your terminal (e.g. Ghostty) comes to the front. If this fails, fix the setup before trying again in Godot.

command not found: nvr

• Make sure nvr is installed and in your $PATH:

  pip install neovim-remote
  which nvr
  

• If it’s not found, add ~/.local/bin to your $PATH.

Godot shows "Cannot execute"

• Check the Exec Path in Godot points to the script and is executable:

  chmod +x ~/.local/bin/godot-nvr.sh
  

• Use the absolute path (e.g. /Users/you/.local/bin/godot-nvr.sh).

Terminal doesn’t come to the front (macOS)

• Ensure you set the correct terminal app name (case-sensitive!):
  • ghostty → "Ghostty"
  • Terminal → "Terminal"
  • alacritty → "Alacritty"
  • kitty -> "Kitty"
• To check the exact name macOS expects, run:

  osascript -e 'name of every application process'
  

• Test manually (from another terminal app):

  osascript -e 'tell application "ghostty" to activate'
  

Wrong file/line opens

• Make sure you’re using {file}:{line} in Godot’s Exec Flags.
• For column support, you can use {file}:{line}:{col}.