Terminal drag-and-drop protocol

[sxyazi]

Hi, I'm working on Yazi (a terminal file manager), many people use it as a replacement for their GUI file manager, and I've gotten a lot of feedback saying the only missing feature is drag-and-drop integration with other apps.

kitty is both something I use personally and the anchor of the terminal community with many protocol extensions drafted up, like the graphics protocol and keyboard protocol that Yazi directly supports, so I thought here might be the right place to propose a drag-and-drop protocol as well.

For Yazi specifically, what I need is:

• Make a specified rectangular area draggable
• Customize the behavior of the drag area (e.g., file paths, plain text)
• Customize the icon while dragging (e.g., file icon, text icon, etc.)

Any input on this idea would be appreciated!

[kovidgoyal]

Sure, this is on my TODO list anyway. Sadly, my TODO list is, as you can imagine, very extensive :) You dont need to designate a rectangular area for this. The application should handle mouse events and start a drag in response to them itself (which reminds me I need to create a proper pointer events protocol, the current nonsense we have inherited from xterm is horrible and insufficient). That way the application is free to use whatever design it likes for dragging, such as using modifiers, or starting in response to some arbitrary action, etc.

You need a few things from the terminal

1. A way to tell the terminal to start a drag and provide it with a list of mime types and associated data along with image data for the icon. The best design here is to make the actual data sending asynchronous. So only when there is a drop the terminal informs the application of the dropped MIME along with the drop operation copy/move/other and the application then starts sending the data to the terminal for that MIME, which in turn forwards it to the OS.

2. Drag enter/move/leave events. The program should be able to subscribe to these events and have the terminal send them to it along with a list of associated mimetypes. The application should be able to respond to the terminal telling it whether it accepts/rejects the drag and the possible actions copy/move/other and the list of acceptable mime types in priority order, from the available mime types.

3. Drop event. When the user drops something on the application, the terminal will send it an event, the application replies with the mime types it wants and the terminal sends them as data to the application encoded in escape codes.

The problem here is that toolkit drag/drop APIs tend not to be asynchronous. One typically needs to respond to a drag enter/move event directly in the event handler indicating whether you accept it or not.

So in kitty's case this would mean refactoring the glfw drag/drop APIs to be asynchronous as a first step, with corresponding async implementations in the cocoa/x11/wayland backends. Once that is done one can design an escape code
protocol for the points above.

[sxyazi]

So happy to know it's on your todo list!

Your design is more elegant - letting the app decide drag-and-drop behavior based on one's final drop is definitely better than pre-configuring behaviors and icons for specific areas. It makes sense since one can only start a drag-and-drop at a time, and treating the whole terminal as the drag/drop carrier feels more logical than splitting it into multiple zones.

There might be a use case though, one-way drag for non-interactive commands like ls or similar apps, i.e. you can drag their output to other apps, but can't drop stuff into them. For example, ls could output file lists with escape codes to mark draggable regions for each filename and define what happens when you drag on them, but personally, I don't really need this and not sure if you're interested in it, especially since OSC 8 can do similar stuff already.

[kovidgoyal]

On Tue, Feb 03, 2026 at 04:01:11AM -0800, 三咲雅 misaki masa wrote: Your design is more elegant - letting the app decide drag-and-drop behavior based on one's final drop is definitely better than pre-configuring behaviors and icons for specific areas. It makes sense since one can only start a drag-and-drop at a time, and treating the whole terminal as the drag/drop carrier feels more logical than splitting it into multiple zones.

Yes this design basically treats terminal applications the same as GUI applications. Putting them in charge to control the drag and drop experience completely. The protocol just becomes a thin abstraction over existing drag and drop protocols provided by most OSes.

There might be a use case though, one-way drag for non-interactive commands like `ls` or similar apps, i.e. you can drag their output to other apps, but can't drop stuff into them. For example, `ls` could output file lists with escape codes to mark draggable regions for each filename and define what happens when you drag on them, but personally, I don't really need this and not sure if you're interested in it, especially since OSC 8 can do similar stuff already.

There are complications to this. Normally drag in a terminal is used for select. So either select stops working in the region or you need to use some kind of modifier, which becomes quite non-intuitive. I am closing this issue as I dont have immediate plans to implement this, if and when I get around to it I will open a RFC issue for it. If you wish to work on it in kitty, let me know.