API for managing windows / tabs / splits

[pomdtr]

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

[mitchellh]

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:

• Easy to debug. You can telnet and just start typing as an interactive repl.
• Easy to build API clients for
• Easy to implement and fast to parse
• Can run over a variety of transports
• Can be easily secured via TLS (on TCP)
• Can be password-protected or if we ever want to go big we can support TLS client certificates

[mitchellh]

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]

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]

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 like RUN action=new_split:right OR RUN 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:

• How do we support advanced parameters like maps (or is that even a good API decision)?
• Should API control be stateless or does it make sense to return data to track the ID of a surface?
  • This could also tie into some very far-future idea where QUERY (or something similar) is a command.
  • What would a response format even look like if this is desired?
• Should multiple commands at once be supported just delimited by newlines?

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]

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 | jq

[LordMZTE]

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 | jq

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