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 → Neovim launcher with GUI terminal focus
   # Usage:
   #   godot-nvr.sh [terminal_name] +{line} {file} [--tab|--vsplit]
   
   # -----------------------------
   # Arguments
   # -----------------------------
   DEFAULT_TERMINAL="ghostty"
   ARG0="$1"
   
   if [[ "$ARG0" == +* || "$ARG0" == --* || -f "$ARG0" ]]; then
      # No terminal argument provided, use default
      GODOT_TERMINAL="$DEFAULT_TERMINAL"
   else
      # First argument is terminal name
      GODOT_TERMINAL="$ARG0"
      shift
   fi
   
   SOCKET="/private/tmp/godot.pipe"   # Neovim socket path
   NVR="/Library/Frameworks/Python.framework/Versions/3.8/bin/nvr"
   
   OPEN_MODE="window"
   LINE=""
   FILE=""
   
   # -----------------------------
   # Parse remaining arguments
   # -----------------------------
   while [[ $# -gt 0 ]]; do
      case "$1" in
        --tab) OPEN_MODE="tab"; shift ;;
        --vsplit) OPEN_MODE="vsplit"; shift ;;
        +[0-9]*) LINE="${1#+}"; shift ;;
        *) FILE="$1"; shift ;;
      esac
   done
   
   [ -z "$FILE" ] && exit 0
   
   # -----------------------------
   # Open file in Neovim or jump to buffer
   # -----------------------------
   if $NVR --servername "$SOCKET" --remote-expr \
     "bufexists(fnamemodify('$FILE', ':p'))" | grep -q 1; then
     CMD=":buffer $(basename "$FILE")"
   else
      case "$OPEN_MODE" in
        window) CMD=":e $FILE" ;;
        tab) CMD=":tabedit $FILE" ;;
        vsplit) CMD=":vsplit $FILE" ;;
      esac
   fi
   
   [ -n "$LINE" ] && CMD="$CMD | call cursor($LINE,1)"
   CMD="$CMD | normal! zz"
   
   $NVR --servername "$SOCKET" --remote-send "<C-\\><C-N>${CMD}<CR>"
   
   # -----------------------------
   # Focus GUI terminal (macOS)
   # -----------------------------
   osascript -e "tell application \"$GODOT_TERMINAL\" to activate"
   
   

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}.