Scripting API for Ghostty

[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

[aehlke]

Please choose an approach which works from inside the macOS sandbox. So that we can ship tools to the App Store which can interact with ghostty (as we can with iTerm2).

[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$.

[akx]

Yeah, iTerm2 has a couple VT sequences for this: #4391

[hartzell]

In iTerm2, I often manually run:

echo -e "\033]1337;SetColors=preset=Grass\a"

(varying the scheme) to make a particular window stand out.

[jakenvac]

I like this approach because it allows any program (even outside of ghostty) to write escape codes to the tty of a given terminal.

I use this feature with wezterm and aerospace to integrate my terminal and window manager keybinds.

Wezterm has a custom escape sequence to set user vars, which you can use to trigger event handlers in the config. If my window manager detects that wezterm is focused, it uses the wezterm cli to query the active tty and then write escape sequences to it.

That said, I think this works nicely alongside a more robust api/cli rather than instead of as it's a bit of a one way system without hacks.

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

[tale]

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]

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]

telnet works on simple shell scripts! You can even test this with redis, if you telnet and just send PING it'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]

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]

Why not use D-Bus?

[mitchellh]

Why not use D-Bus?

This needs to be cross platform. Additionally, I’ve found dbus pretty complicated to use compared to a simple text proto.

[mmlb]

systemd folks are liking https://varlink.org/ over dbus and I believe I've seen some other projects start to use it too. Not sure if it makes sense here but wanted to give a dbus alternative that I think we will see more of in Linux.

[jcollie]

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]

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]

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_RIGHTS and similar, access API from clients, that aren't attached to Ghostty session, etc.

[honeyspoon]

The main use case for me would be to use smart splits in nvim
The alternative would be to use tmux in ghostty and that seems to defeat the purpose since we lose all the things that make it snappy

[pluiedev]

Please keep this on topic about the scripting API only. Session management was previously discussed in #3358, although we had to lock that post because too many people were getting off topic. I don't want to lock this one too.

[fundefineddev]

The main use case for me would be to use smart splits in nvim

The alternative would be to use tmux in ghostty and that seems to defeat the purpose since we lose all the things that make it snappy

Would love to see this implemented. I started working on this feature but hit a wall when I realized a lot of commands aren't available from the CLI.

I can't ditch tmux until I can easily navigate between ghostty and neovim panes seamlessly.

[pluiedev]

To me, a large part of why this issue hasn't seen much progress is because it's too broad. Even after rounds of discussion among maintainers it's unclear how to proceed, because we've been trying to develop one Big solution that's trying to cater to all needs.

Specifically, there are multiple problems that we're trying to solve here:

• TUI apps should be able to control Ghostty for functionality like smart splits
• External apps should be able to control Ghostty for better system integration
• Users should be able to use the CLI to control Ghostty via scripts

These problems all demand somewhat different solutions because of different use cases and different access methods. For the first use case the obvious solution is an escape code sequence — either via OSC sequences like iTerm2's OSC 1337 or DCS sequences like tmux's control mode or Kitty's remote control protocol.

We could use control sequences for all remote control capabilities like Kitty, but then we run into the problem of how we get them into a running Ghostty instance. If the app is running inside Ghostty and wishes to control it, that can be very easily done. But if some other program that isn't attached to Ghostty wants to control it, it would require some external transport in order to speak to it: Kitty solves this by using Unix sockets, which, as the name implies, aren't available on Windows, and I don't think we want to limit ourselves to Unix platforms just for this. Other transports are even more cumbersome — other people have proposed hosting an HTTP server or using telnet, but none of these options are really convenient to use without using specific libraries, which just makes the feature harder to use by downstream consumers.

---

The other main approach is to use platform-native IPC capabilities, such as AppleScript on macOS, D-Bus on Linux, etc. This IMHO is a much better idea for when other desktop apps need to talk to Ghostty, especially since native apps often already have the libraries needed to use these IPC apparatuses — even on Linux, all GTK apps are built with gdbus support by default, and Qt apps can use qdbus as well. What's better is that native IPC is also often used by the desktop environment to communicate to apps: in fact, ever since #7679 we already use D-Bus to start new windows, so there's no reason why we shouldn't lean in on it harder, especially considering our goal to be native.

The caveat of course is that there's no standardized way to talk to Ghostty across all operating systems. I think I would be fine with that drawback, especially since our macOS and GTK apps do have different feature sets, and multiplatform apps aiming to control Ghostty should be aware of those differences. IMHO we would only see whether this is a problem once someone actually writes said multiplatform app. Using D-Bus/AppleScript would also be quite annoying for apps running inside Ghostty or for CLI usage.

---

Given that these two solutions are good for a subset of the use cases proposed here, I would say... ¿por qué no los dos? On the GTK side at least we already use D-Bus, and it's just a matter of making all of our keybind actions available via D-Bus (which GTK already supports via the Action API). Adding a new control sequence would also be enormously simpler than trying to embed a Telnet/HTTP/Varlink/whatever API in Ghostty that terminal consumers would only find hard to use.

Being native for Ghostty doesn't just mean that it should only follow conventions for the OS, it should also mean that it should follow the conventions set out by other terminals. Trying to squash these two different sides of a terminal emulator (which, philosophically, is the connection between the OS world and the terminal world) together into one solution makes neither side happy.

On a community administration side I think it would be much more productive to split this discussion in two: one discussing the design for a control sequence-based API for terminal apps, and one discussing the design for a desktop IPC-based API for desktop apps. The CLI in my mind should be able to intelligently choose between the two depending on whether it's running inside Ghostty (similar to kitten @), or outside of it (like kitten @ --to, but automatic). I think that would be a design that works better than the status quo.

[mitchellh]

I agree with the separation of concerns (the three use cases) you defined.

Re: Escape Sequences

For the escape sequence side, I'd like to add that another issue is security. Escape sequences can be sent by lots of sources (including just... cat-ing a file!) and allowing it do arbitrary things to Ghostty's config or windowing is very, very scary. So, let me add that the escape sequence approach for me personally has always stalled on figuring out the security story. That's a blocker.

I say we shelf this for now. It's a lot of design work. People are free to share ideas, but it's not something I'm ready to work on in earnest.

Re: D-bus

100% on board with exposing an IPC API that is Linux-specific with D-bus. This is similar to what we're already doing with Apple Shortcuts. And this is how we already enable ghostty +new-window on Linux.

For security on this side, the IPC mechanism usually handles that for us, which is nice.

I think the downside as you noted is its platform-specific, and D-bus on its own is pretty nasty to script against the API level (probably easier to shell out to gdbus or some other CLI). So this will limit the utility of plugins such as the Neovim native split plugin. Exact same problem with Apple Shortcuts.

API Surface Area (kind of Re: "broad")

We shouldn't boil the ocean. Maintaining an API that can do anything with Ghostty is a design and maintenance nightmare. I think scoping down to specific use cases and introducing the IPC necessary to do that is the way to go, similar to what we did with ghostty +new-window.

So, I'd say, we should aim future discussions at introducing specific, platform-specific IPC capabilities.

Future Cross-platform API

I'd still like to do a future cross-platform API, likely via something like Unix domain sockets (but who knows). But, there's enough of a barrier to entry there that I'd feel more comfortable addressing this via the platform-specific IPC mechanisms for now.

[pluiedev]

I initially had a whole tirade about security that I cut out for the sake of time, but I think it should be done via both cutting down the exploitable surface (e.g. don't allow apps to send the crash action to the terminal in any circumstance) and also having a much more developed permission model for actions that originated from something that wasn't the result of a user's direct intent (e.g. popping up a dialog asking the user if they truly want to paste rm -rf --no-preserve-root / into their shell). I agree though that the control sequence approach seems like too much of a security nightmare for now — maybe we could revisit it later after implementing tmux control mode first.

For what it's worth I looked at how Kitty did it, and it's simultaneously too over- and underengineered at the same time. It's a bit shocking. I think if we want to do this we want to do this correctly from the outset. (Kitty only introduced granular control permissions after the initial protocol came out IIRC.) Maybe we can experiment with a token-based authentication system where apps can request certain permissions which would be presented to the user, the user could opt out of some or all of them, and then we could return the set of allowed permissions for the app. That seems a bit too involved, though.

[BrendanMesters]

On the "API Surface Area"

You mention that we should not create an API which can do anything, due to the load that puts on maintanance and design.
First off, I wholeheartedly agree with this, but it got me thinking, and would an API really need to be that large to give end users the ability to implement "everything"?

A lot of complex functionality can often be compiled from few simpler interfacing points.
I might be mistaken in the effort needed to create such an API, or the scope that API would need to take, so it might also be useful to compose a list of different potential interface actions and the things you can do with sets of them.

e.g.
If we implemented:

• Reading window&pane info (location and size in the ghostty multiplexer, current run command+PID, potentially logged in user, window name)
• Modifying window&pane info (Change location, size, name, active window)
• Creating new window/pane

It feels like this (relatively small) subset of potential interface options would already open up a large amount of scripting potential.

[Qyriad]

Kitty solves this by using Unix sockets, which, as the name implies, aren't available on Windows

Windows actually supports AF_UNIX sockets, now, though there's not much documentation for it.

[dlants]

So, I'd say, we should aim future discussions at introducing specific, platform-specific IPC capabilities.

So I'm trying to stop using tmux and use native ghostty stuff to support my existing tmux workflow.

I have something like this:

• a script that fetches all my open tmux sessions, the tabs inside of them, and the processes running in each tab
• it shoves them all into fzf, and gives me fuzzy matching over them
• when fzf returns, it gives me a selected line. I then use the tmux cli to switch over to that session/tab

I'd really love to be able to do something like this with native ghostty (I've had trouble with running inside of tmux for a while and I find the idea of removing this middle layer compelling).

guess that means that I should look into AppleScript? (If I want to do this in macOS?) Would the equivalent be enabling something like querying for open windows / tabs, and enabling the selection of a particular window/tab via something that can take advantage of applescript ... like spotlight / alfred / raycast?

I think I find the CLI approach that tmux takes really appealing here, because it allows for really easy composition with other tools like fzf... though I understand that this is really because tmux is a shell application, so it is quite different than running natively - we would need to tell the OS to focus the thing, rather than merely changing the program that the shell is running in this case.

[dlants]

Actually I ended up looking into this a bit, and you can do this without AppleScript, by just using the standard OSX window controls and the accessibility stuff that ghostty exposes.

I ended up using hammerspoon https://github.com/dlants/dotfiles/blob/main/hammerspoon/init.lua

This:

• on shift+cmd+t, uses hs to launch a new ghostty terminal which runs this script https://github.com/dlants/dotfiles/blob/main/scripts/ghostty-tab-switcher
• that script pulls all ghostty windows and tabs into a text file using hs, with one line per tab, then feeds it into fzf
• when fzf returns, we invoke https://github.com/dlants/dotfiles/blob/main/hammerspoon/init.lua#L187 to get hammerspoon to select that tab

So now you can have several windows open, one per project, and switch between the various tabs.

hammerspoon_ghostty_switcher.mov

I think in macOS it's a bit difficult to set up since you can only set tab titles and not window titles #1026 (comment) so this becomes a lot more useful when you configure the title to always contain the cwd. I ended up spending a lot of time being confused about this, since several places were trying to control the terminal title. I had two zsh plugins trying to control it, and ghostty itself https://github.com/dlants/dotfiles/blob/main/ghostty/config#L20 Once I disabled all of those, my manual title controls worked (and eventually I ended up swapping to fish's default title behavior which includes an abbreviated cwd in the title for both directories and commands).

For folks running into trouble controlling ghostty's title from zsh (like here #4113), look into which plugins you have installed and look into precmd_functions, as it's likely overriding whatever title setting you're trying to do.

[megalithic]

Bless you for breaking this down and creating a usable and elegant solution given the constraints between the various tools invoked. Another plus one for hammerspoon and shell scripting to create something useful and repeatable rather quickly.

[megalithic]

Thinking more on this, you can also use hammerspoon's built in fuzzy picker to do it all within the hammerspoon context; could also go so far as to create a seal plugin for it to be used with the Seal spoon.

[rushter]

Scripting is a complex task. Perhaps development towards scripting could start with smaller improvements?

For example, we can add a new action that would allow changing settings by pressing shortcuts. This is one of the use cases for scripting. For me, that's the only thing I'm missing right now.

keybind = super+shift+e=change-setting:cursor-invert-fg-bg:true

[calebhearth]

Just to chime in with my use case, I'm looking for a way to set up a vim-dispatch

1. Launch a new split or tab (surface in ghostty parlance)
2. with the current ENV copied
3. specify whether the new surface should be focused or not
4. set the title of the new surface
5. set the cwd of the new surface
6. pass it a command to execute

I do this currently with Kitty with the launch kitten in a vim function (simplified):

let kitty = 'kitty @ launch --copy-env --keep-focus --title='.shellescape(a:request.title).' '.'--cwd='.shellescape(a:request.directory)
call system(kitty.' zsh -c '.shellescape(command).redir)

Having something similar for ghostty(1) would be great.

[HealsCodes]

Having something like Kitty's kitten to remote control the active ghostty window would be amazing - especially for editors like kakoune that have no native windowing support and rely on integrations with the hosting terminal or tmux and friends.

[00-kat]

on macOS the ghostty command can't open new terminals and doesn't interact with an already open terminal either :(

You can create a new instance with open -na Ghostty.app --args --title=example --working-directory=/path -e zsh or whatever. You currently can't create a new window in the existing Ghostty instance from the ghostty command though.

[BrendanMesters]

sadly not cross-platform though - on macOS the ghostty command can't open new terminals and doesn't interact with an already open terminal either :(

Do you know if this is possible with other terminals on macos?

[aehlke]

sadly not cross-platform though - on macOS the ghostty command can't open new terminals and doesn't interact with an already open terminal either :(

Do you know if this is possible with other terminals on macos?

Iterm2 with osascript yes

[adamshand]

Also Wezterm can do this.

[dlamblin]

I saw a digression from the starting premise of a single line text protocol, and I wondered if its worth pointing out that sending text over tcp/udp with netcat is pretty useable. Here's a case where it would seem more complicated if it was all http and json (or control sequences) : https://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_zkCommands

[jnstq]

I'm interested in this for project-specific terminal layouts - similar to what Zellij provides with its layout files.

My current setup defines tabs for a Rails development environment: shell, console, web server, background jobs, and a split pane for asset watchers. Each tab has its own command. Being able to launch this with a single command is incredibly useful.

The appeal of having this natively in Ghostty is twofold:

1. One less layer - terminal multiplexers sit between the terminal and shell, which can cause friction with keyboard shortcuts and escape sequences
2. Native splits/tabs - Ghostty already has excellent split/tab support, so the building blocks exist

[hyperb1iss]

I built a working version of this, and added support for IPC over a unix socket which works nicely on my Mac. I also made an MCP server so Claude Code can test my TUI apps for me! I'm interested in upstreaming the implementation for sure and would love feedback on the approach. I used a pretty simple JSON-RPC protocol for the IPC socket. It's still mostly AI and I've got a bunch to do before submitting.

My branch: https://github.com/hyperb1iss/ghostty/tree/stef/remote-control

ghostty-automation-2x.mov

[rhodes-b]

I took a quick glance at this and there is definitely required feedback.

for example the list surfaces includes the title, this is a security concern as programs are generally not allowed to get the terminal title
https://ghostty.org/docs/config/reference#title-report

You also have the ability to read the entire scrollback and read the current screen. I would never let any program do this there is no reason those are considered in the same category of security as some of the less invasive options, I also think every program should request access to each individual action (it can request access to multiple actions on startup) with some sort of authorization token or something (this is a pretty common mechanism although probably not super secure over plain text)

If at any point something can read/write the contents of your screen remotely there needs to be considerable thought of the security before that is implemented. If the initial implementation supported stuff like new window / new split etc that isn't really dangerous besides something spamming new windows so there is much less concern for security

I understand the AI lovers want something like that but I don't think the scripting API is the correct place to just let anything read your entire terminal something like a session manager is probably a slightly better place for that. (im pretty sure ghostty already exposes stuff to accessibility API on macos so if AI tools use that they can already read ghostty contents, or at least plans to)

I also don't see anywhere the security stuff is actually implemented.
I also don't see any need for the screenshot capture that should be handled by external screen capture software

The PR will also be 100% rejected if you don't split it up into core components like just opening and maintaining a socket (using libxev to handle it as its own task is likely the best idea I didn't see how its running besides there is a 100ms poll somewhere, zig 0.16 is also doing a massive rework to how IO works in general so that should also highly be considered). Each IPC handler should also be its own PR (ie list_surfaces is 1 PR, focus_surface is 1 PR etc. That way each individual type is accepted)

Your video shows you use a mac machine if you don't own a linux machine dont touch the GTK runtime at all, many AI submissions do this and never check that it even compiles it shouldn't be on the burden of the maintainers to even review a PR that has compile errors.

I also don't understand why you have the version already at 2 (because of existing dbus stuff etc? that doesn't seem right to me)

[kkilchrist]

This is also macOS only, but I added AppleScript wrappers around the existing App Intents framework so that you can open new window / tab / split any direction / send text / get contents / send command. It also can maintain a persistent link between Ghostty Terminal and the automation sender via UUID. I will probably end up building some SwiftUI menubar app so that I can search all open Ghostty terminals for the content I'm looking for then switch to it. I always end up with way too many windows. Anyway, I digress.

I know there's hesitancy to build out an automation API w/o a "unified" scripting API, but since the App Intents are already there, and this is literally what AppleScript is made for, this is a dead simple addition

branch: https://github.com/kkilchrist/ghostty-applescript
discussion here: #10201

(idea is mine after significant digging; Claude did the implementation while referring to another app of mine that had working AppleScript support)

[ryanlewis]

For what it's worth, I just want a TERM_SESSION_ID (or equivalent) and a means for a long-running process to grab it and then call an API to focus that specific pane.