[RFC] Drag and drop in TUI applications with new dnd protocol

[kovidgoyal]

Hi all,

After two months of very involved work, I am happy to announce the Drag and drop kitten is ready for testing/comments. It allows you to drag and drop files between your shell and GUI file manager programs/web apps that require you to drag and drop files etc. It even has the bonus feature of working over SSH
so you can actually drag and drop to transfer files between different computers.

To use it install kitty nightly or build from master and::

    kitten dnd file-to-drag.xyz

Then, start dragging with the mouse inside the window, and file-to-drag.xyz will be dragged and you can drop it onto a GUI file manager or another window running this kitten. You can specify directories as well to drag entire trees.

Similarly, dropping works by running the kitten::

    kitten dnd

Then, drag some files from a GUI file manager or another window running the dnd kitten and drop them onto this window. The files will be copied or moved (depending on which area you drop them) into the current working directory.

The best part is this works even over SSH. So if you just want to quickly transfer some files from one computer to another all you need to so is ssh into the remote computer::

    kitten ssh remote-computer-name

Then, run the dnd kitten on the remote computer::

    kitten dnd files-or-dirs-to-drag

This is a large amount of very new code, that has to integrate with very finicky and under specified platform specific drag and drop APIs, so there likely will be bugs, testing is appreciated.

This kitten is based on a new drag and drop protocol which is specified in docs/dnd-protocol.rst

Comments are welcome, in particular if anyone knows of any conflicting uses of the OSC 72 escape code, let me know. While this RFC is open the dnd protocol is considered under development and subject to change. I imagine this protocol will be of interest to developers of TUI file managers, so maintainers of such projects (or any other interested parties) are welcome to raise concerns about the protocol, if they have any.

Pinging a few people I think might be interested, sorry for the noise:
@leiserfg @sxyazi @toonn @Canop @jarun

[leiserfg]

Hi @kovidgoyal, the only issue I spotted is that the list of available mime-types is always empty.

Edit: I see, it only shows mimes if the copy comes from an app that is not my Filemanager 🤦‍♂️, so all good!

[zzhaolei]

I tested kitten dnd on macOS and found that dragging works between two kitten dnd windows, but it does not work correctly with native macOS apps or editors.

What works:

• kitten dnd -> another kitten dnd window
• The target dnd window receives the files correctly

What does not work:

1. Local drag from kitten dnd to Finder does not work correctly

   • Dragging from kitten dnd ~/some-file to Finder does not behave as expected
   • In some cases the source window stays on:
     The dragged data has been dropped, waiting for data transfer requests...
   • Copy/Move semantics are also inconsistent when dragging to Finder

2. Local drag from kitten dnd to native editors does not work

   • I cannot drag files from kitten dnd into apps like Zed or VS Code on macOS

3. Remote drag over SSH to the local host does not work

   • kitten ssh remote-host
   • kitten dnd /remote/path/file
   • Dragging from the remote dnd window to the local macOS host (Finder / editor) does not work
   • This means SSH -> local host drag-and-drop is currently broken for me

Important detail:

• This does not look like a general kitten dnd failure, because dnd -> dnd works
• The problem seems specific to macOS native drag targets such as Finder and editors, and also affects remote-to-local drag over SSH

Minimal repro:

1. Local:
   • run kitten dnd ~/some-file
   • drag to Finder / Zed / VS Code
2. Remote:
   • run kitten ssh remote-host
   • on the remote side run kitten dnd /path/to/file
   • drag to local Finder / Zed / VS Code

Expected:

• Dragging to Finder or editors on macOS should work
• Dragging from a remote SSH session to the local macOS host should also work

Observed:

• Only dragging between two kitten dnd windows works reliably
• Native macOS targets do not accept the dragged files correctly

[kovidgoyal]

Yes, macOS has the worst DnD API they dont even use mime types (using something called UTI instead) and they only implemented support for dragging without having all data up front via something called file promises relatively late which means many macOS native apps dont really support it. In particular many native apps require the data for text/uri-list MIME type to be present when the drag is started, that's why dragging from the kitten to finder wont work. But dragging from finder to the kitten should still work fine. Trying to get kitten->finder working in the remote case would basically require all data for all files being dragged to be sent over before the drag is started, which is too slow. For the local case it may still be doable, with some minor protocol changes.

[zzhaolei]

Yes, that makes sense. It seems this can only really be solved properly by using macOS-specific APIs.

At the moment, what I’m seeing is:

• local kitten dnd -> SSH kitten dnd: works
• SSH kitten dnd -> local kitten dnd: does not work

So even if kitten -> Finder is fundamentally limited by macOS DnD behavior, would it still be possible to support the remote-to-local direction between two kitten dnd windows?

The first direction already works for me, but the second one currently does not. It might be a nice addition if SSH dnd -> local dnd could also be supported.

[kovidgoyal]

That's likely a bug I will look into it when i have a moment. And
actually thinking about it, there may be a way to get the remote to
finder case to work as well, but it would require an entirely separate
macos only code path, sigh.

[leiserfg]

@kovidgoyal I'm still testing and got a random Error: terminal responded with drag source error: EPERM

[kovidgoyal]

On Fri, May 08, 2026 at 02:21:00AM -0700, leiserfg wrote: leiserfg left a comment (kovidgoyal/kitty#9984) @kovidgoyal I'm still testing and got a random `Error: terminal responded with drag source error: EPERM`

That can happen if the drag is ended by lifting the mouse button or the mouse leaving the window in between the mouse down event and the actual start of the drag which involves a couple of roundtrips betwene the client and the terminal.

[kovidgoyal]

@zzhaolei after another week of work and extensive re-writing of the macOS backend and some minor protocol changes dragging from the kitten both local and remote works to finder and the another kitten instance. Note I have only tested with simple drags involving a single file. More comles ones with directories/symlinks etc may or may not work. Phew I think this kitten is now in basically useable shape, rest of the bugs should be edge cases/polish type ones.

[zzhaolei]

I've encountered some edge cases and I've recorded some videos.

finder file -> dnd:

2026-05-16.4.34.07.mov

finder file <--> linux(ssh docker debian) file:

2026-05-16.4.35.51.mov

[zzhaolei]

and linux (ssh docker debian) folder -> finder will panic:

2026-05-16.5.03.04.mov

% file test
test: empty

[kovidgoyal]

@zzhaolei fixed the issue dragging from finder. Apparently Finder uses
"file reference" URLs rather than actual file URLs. Sigh.

[zzhaolei]

Confirmed that dragging from Finder is fixed. However, dragging from an SSH folder still has the issue. I tried to look into the cause, but wasn’t able to find it.

[kovidgoyal]

@zzhaolei What's the exact scenario? I cant tell from the video. You are running the dnd kitten on a linux machine and dragging from it to finder?