Repository navigation
API for managing windows / tabs / splits #601
Description
Some inspiration:
- wezterm expose it's api through the cli
- iterm can be controlled through applescript
- warp allows to configure "Launch Configurations" and launch them through protocol handler
- kitty remote control
Activity
[-]API for managing window / tabs / splits[/-][+]API for managing windows / tabs / splits[/+]mitchellh commentedon Nov 6, 2023
Just dropping down some thoughts. I'm leaning towards a single-line text protocol in the format of memcached/redis/etc. This has various benefits:
telnetand just start typing as an interactive repl.mitchellh commentedon Jan 22, 2024
I know GitHub links it, but I want to explicitly note @LordMZTE's proposal for dynamically linked plugins in #1358. See my comment there, I don't think these are mutually exclusive, but I did want to centralize all potential plugin discussion in one place for now until we spin out actual working on some of these. And I'm not ready to commit to working on these yet.
RGBCube commentedon Feb 17, 2024
I'd like to propose another way to interact which are escape sequences, we could make another standard which specifies how it is used.
The way it would work is simple, you just echo stuff in your terminal and Ghostty (and other standard implementors) parse it and apply the settings.
I don't know how the Kitty keyboard protocol works, but it would be similar, just print your desired setting, and it gets applied:
echo $"($escape_start)background($escape_sep)#800000($escape_end)"This would be really useful over SSH, and could prevent you from accidentally deleting the primary database instead of the backup one because you selected the wrong terminal emulator window.
This isn't a replacement for the socket way, btw.
Another idea is that the background-color and other common settings could be documented in the standard, so all terminal emulators that implement the standard work with a single shell command when added to the shellrc.
For emulators that don't support it, the escape sequences could be picked carefully so it doesn't change output and just shows as a normal echo statement. Like
%CFG-START$background%CFG-SEP$#800000%CFG-END$.tale commentedon Apr 16, 2024
Just building on the conversation about making a text protocol. Would it be cursed to do something like
<COMMAND> named_arg1=value1 named_arg2=value2 named_arg3=value3? I'm thinking really far into the future but let's assume I want to implement an API command that opens a new vertical split, something likeRUN action=new_split:rightORRUN action=new_split dir=right. It's very simple and mimics exactly what keybinding syntax looks like in the configuration file.A few problems/questions that this kind of syntax raises:
QUERY(or something similar) is a command.I chose something overly simple because like mentioned above, it can be easily debugged and building an API client with it is as simple as building a parser in the language and moving forward with normal TCP connections.
I think at the very least following the naming scheme of keybinds is the best choice because then you don't need to reinvent the wheel and there's consistency between these two. The one downside is we already run into consistency issues because in a keybind you would do
keybind = super+ctrl+up=resize_split:up,10. Those aren't named arguments so one or the other would need to change to conform.jcollie commentedon Apr 16, 2024
Why invent a new protocol? Why not use HTTP & JSON over Unix sockets? Every language worth mentioning has HTTP & JSON support already (although it may take a bit of work to talk to a Unix socket) and it's basically infinitely extensible. That also means that we don't need to spend weeks bikeshedding a new protocol. Even cURL works over Unix sockets.
curl --unix-socket $GHOSTTY_API_SOCKET http://localhost/v0/keybinds | jqLordMZTE commentedon Apr 16, 2024
I understand the use of JSON here for a uniform and simple standard, but HTTP doesn't seem logical to me, mostly because we could just use a streaming JSON parser (Zig can be made to do this IIRC) to directly transfer JSON over the socket. It would also seem to me that most HTTP clients aren't exactly easy to convince to connect to a Unix socket, as it's simply not something HTTP was ever intended to do, as further made evident by the lack of a way to express this in a URL. Your example could translate to something as simple as:
echo '{"request": "keybinds"}' | socat $GHOSTTY_API_SOCKET - | jq(Note: the JSON here is obviously just a placeholder and isn't meant to suggest a possible way a request could look.)
tale commentedon Apr 16, 2024
JSON makes sense, honestly it wasn't my first choice because I was looking at redis, which is just raw commands. Need to confirm, but is there an overhead to using JSON parsing? Do we need the power of JSON either?
I think following the keybind syntax is a good place to start because it's simple and shares a mental model in 2 different places. Introducing JSON basically opens up the can of worms for super complicated API bodies which I personally think is just a sign of bad design.
jcollie commentedon Apr 16, 2024
Everyone hates JSON, because everyone has had to deal with JSON. It's the LCD for passing data between systems. I think that the overhead of JSON parsing is irrelevant unless you're expecting hundreds of API calls per second. Yeah JSON does open you up to the possibility of some truly horrific data structures, but the same could be said for trying to cram everything into a bespoke REDIS-like API. The point of using HTTP & JSON is that the best code is the code that you don't have to write. Each language's HTTP & JSON code is thoroughly vetted by a large community whereas a bespoke protocol will probably only ever be looked at by a very small number of people.
Plus cURL & wget mean that you can access the API from a simple shell script as well.
tale commentedon Apr 16, 2024
telnetworks on simple shell scripts! You can even test this with redis, if you telnet and just sendPINGit'll respond with pong. I'm not trying to cram everything into a "bespoke REDIS-like API". My suggestion stems from supporting an API that's agnostic so that the OSC way of invoking it is possible too. The keybinding action syntax already exists, we should follow it.jcollie commentedon Apr 16, 2024
The use of HTTP makes things simpler as it's a very common design pattern for such things. I suggested using Unix sockets as a security measure but binding to a random port on localhost is an option as well. On Linux it would theoretically be possible to use CGroups and network namespaces to futher limit access to the localhost port but that might be more complication than necessary.
RGBCube commentedon Apr 17, 2024
Why not use D-Bus?
mitchellh commentedon Apr 17, 2024
This needs to be cross platform. Additionally, Iâve found dbus pretty complicated to use compared to a simple text proto.
jcollie commentedon Apr 17, 2024
Technically, we're already using D-Bus since it's required by GTK. I wouldn't recommend it as the primary API endpoint. At some point we'll need to make more use of D-Bus to achieve deeper integration with Gnome (such as being able to link into the Gnome search interface) so at that point it may make sense to expose the Ghostty API over D-Bus in some way.
cryptocode commentedon Jul 14, 2024
Is the plan also to expose this functionality via Ghostty's cli? I find myself wanting to port stuff like this wezterm/helix integration to Ghostty - i.e. making it easy to use the API from scripts would be great.
hauleth commentedon Aug 6, 2024
I would start with simple text API over Unix socket. Question is whether it should be stream socket or datagram socket. It could also be exposed within Ghostty session itself via environment variable like
$GHOSTTY_SOCKET. With datagrams it make it easy to separate commands from each other, but IIRC it would limit the length of single message.Usage of Unix sockets would also allow us to share extra data via
SCM_RIGHTSand similar, access API from clients, that aren't attached to Ghostty session, etc.tale commentedon Aug 10, 2024
If it's desired, you could resume #1701, I no longer have the time to finish it unfortunately because of work but I'd be more than happy to help pass it on to someone else.
mitchellh commentedon Aug 10, 2024
Thanks @tale âĪïļ