Neovim URL Handler

A macOS URL handler for nvim:// URLs that intelligently opens files in existing Neovim instances running in kitty terminal windows.

Features

• Smart Instance Selection: Automatically finds the best Neovim instance to open files in, based on matching current working directories
• Fallback Strategy: If no matching Neovim instance exists, opens a new tab in an existing kitty terminal, or launches a new kitty instance as a last resort
• Line Number Support: Opens files at specific line numbers using the nvim://file/path/to/file.txt:42 syntax
• URL Decoding: Properly handles URL-encoded paths
• Tilde Expansion: Supports ~ for home directory paths

How It Works

When you click a nvim:// link or open such a URL:

1. The AppleScript handler receives the URL
2. It extracts the file path and optional line number
3. The bash script (nvim_url.sh) analyzes all running kitty terminals and Neovim instances
4. It selects the best match based on:
   • Neovim instances with matching working directories
   • Kitty terminals with matching working directories
   • Falls back to any existing kitty instance
   • Creates a new kitty instance if none exist
5. Opens the file at the specified line number and focuses the window

Installation

Method 1: Download DMG (Recommended)

1. Download the latest .dmg file from the Releases page
2. Open the DMG and drag nvim_url to your Applications folder
3. Right-click the app and select "Open" (required for first launch due to macOS Gatekeeper)
4. The app will now handle all nvim:// URLs

Method 2: Build from Source

1. Clone this repository:

   git clone https://github.com/kelvinst/nvim_url.git
   cd nvim_url

2. Build the app:

   make install

3. Open a nvim:// URL to register the app as a handler:

   open 'nvim://file/~/.zshrc'

Usage

Once installed, you can open files in Neovim by clicking nvim:// URLs or using them in other applications.

URL Format

nvim://file/<path>:<line>

• <path>: Absolute or relative file path (supports ~ for home directory)
• <line>: Optional line number to jump to

Examples

nvim://file/~/.zshrc
nvim://file/~/Developer/myproject/src/main.rs:42
nvim://file//Users/username/Documents/notes.md:10

Testing

You can test the handler from the command line:

open "nvim://file/~/.zshrc:1"

Requirements

• macOS 10.6 or later
• kitty terminal
• Neovim
• jq (for JSON parsing) - install via brew install jq

Neovim Configuration

For the handler to connect to existing Neovim instances, you need to start Neovim listening to a socket:

nvim --listen /tmp/nvim-$(date +%s%N)

Or configure your shell to always start Neovim with a listener. Add to your .zshrc or .bashrc:

alias nvim='nvim --listen /tmp/nvim-$(date +%s%N)'

Troubleshooting

Logs

The handler writes logs to /tmp/nvim_url.log. Check this file if URLs aren't working as expected:

tail -f /tmp/nvim_url.log

Permissions

On first run, macOS may ask for permissions to control other applications. This is required for the handler to focus kitty windows and communicate with Neovim.

URL Handler Not Working

If clicking nvim:// URLs doesn't work:

1. Make sure the app is in your /Applications folder
2. Open the app manually once to register it as a URL handler
3. Restart your browser or application

Development

Project Structure

.
├── Contents/
│   ├── Info.plist              # App metadata and URL scheme registration
│   ├── MacOS/
│   │   └── applet              # AppleScript executable
│   ├── Resources/
│   │   ├── Scripts/
│   │   │   └── main.scpt       # AppleScript URL handler
│   │   └── nvim_url.sh # Bash script for routing logic
│   └── _CodeSignature/
├── build.sh                     # Build script
├── package-dmg.sh              # DMG packaging script
└── README.md

Building

Run the build script to compile the app:

make build

Creating a DMG

To create a distributable DMG:

make dmg

Releasing a New Version

To create and publish a new release:

1. Update the version in Contents/Info.plist:

    <!-- Edit CFBundleShortVersionString -->
    <key>CFBundleShortVersionString</key>
    <string>X.Y.Z</string>

2. Update the version in Makefile:

   # Update the VERSION variable
   VERSION := X.Y.Z

3. Commit the version change:

   git add .
   git commit -m "chore: bump version to X.Y.Z"
   git push origin main

4. Create and push a tag:

   git tag vX.Y.Z
   git push origin main --tags

5. Build the DMG:

   make dmg

6. Create a GitHub release in GitHub with the following format:

   ## [X.Y.Z] - YYYY-MM-DD
   
   <!-- Some short description of the release -->
   
   ### Changelog
   
   <!-- The commits you generated in the previous step -->
   
   **Full Changelog**: https://github.com/kelvinst/nvim_url/compare/vA.B.C...vX.Y.Z

   P.S.: You can generate the Full Changelog using the Generate release notes button on GitHub, you just have to select the current and previous tags.

7. Upload the DMG from dist/nvim_url-X.Y.Z.dmg to the release

8. Publish the release

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgements

Thanks @nickgnd for heavily inspiring this project with his blog post doing the same for TMUX and Allactritty.