Document shell integration running on SSH host

[nihaals]

Something that changed when updating from NixOS 25.05 to 25.11 on a SSH host was my fish prompt cursor not changing with the Ghostty shell integration.

Relevant Nix snippet:

programs.fish = {
  enable = true;
  interactiveShellInit = ''
    if test "$TERM" = "xterm-ghostty"
      set -gx COLORTERM truecolor
      source ${pkgs.ghostty.shell_integration}/fish/vendor_conf.d/ghostty-shell-integration.fish
    end
  '';
};

Ghostty is on v1.1.3 on 25.05 and (currently) v1.2.3 on 25.11. After diffing the shell integrations I noticed that it went from not using the cursor feature only if GHOSTTY_SHELL_INTEGRATION_NO_CURSOR is set to only enabling it if GHOSTTY_SHELL_FEATURES includes cursor. Since this is a headless server, I wasn't running Ghostty on it, so GHOSTTY_SHELL_FEATURES wasn't being set. For context, to fix the issue I added set -g GHOSTTY_SHELL_FEATURES cursor,... (has to be global since the env var isn't read at source time).

I assumed Ghostty's shell integrations were officially supported on servers, especially as it ran fine previously, but I realised from this experience that this doesn't seem to be documented in either direction. Are users using Ghostty's shell integration "wrong" if they're running it on SSH hosts?

If yes, it might be worth adding this to the docs (currently it's assumed that you're getting the shell integration from your GUI Ghostty install but for example nixpkgs exposes it without needing to install the Ghostty GUI so you could still unknowingly do this). Since some of the features like the prompt cursor make sense and work well over SSH, maybe a more minimal shell integration could be made for servers that people can install separately?

If not, GHOSTTY_SHELL_FEATURES should be documented and the shell integration scripts might need to be aware of breaking changes like this one (this also wasn't mentioned in the changelog outside of "shell-integration: now uses a single GHOSTTY_SHELL_INTEGRATION_FEATURES env var to specify enabled features instead of multiple env vars" in the full changelog). Maybe it could just be made clear that it's the user's responsibility to not use a shell integration that is significantly older/newer than the active GUI version? GHOSTTY_SHELL_FEATURES could also be passed with ssh-env as some kind of way to keep them in sync (although I personally didn't include path on my server despite having it set locally).

[pluiedev]

GHOSTTY_SHELL_FEATURES (and likewise GHOSTTY_SHELL_INTEGRATION_*) is technically an implementation detail and we didn't expect anyone to depend on it, so yes, I would consider your use case as something that is at least unexpected. However, I don't really expect this feature to change much anymore in the future, so I think you can depend on GHOSTTY_SHELL_FEATURES at least for the foreseeable future.

[nihaals]

What do you think of the "minimal server-only shell integration" idea? This could be a place to limit avoiding breaking changes (so the GUI ones can be changed more freely), make installation easier for non-Nix users and I think it makes sense to support the cursor feature on servers as well as local. That would also make this use case easier to document.

[nihaals]

I also just learnt about jump_to_prompt and now I more confidently think having a shell integration for servers would be helpful for people.