Activating a kitten via remote control

[CGamesPlay]

I've been evaluating Kitty as an alternative to iTerm 2. I have made some custom escape codes in iTerm 2, which I want to re-implement using Kittens. This discussion is half "experience report" and half request for help on the parts I got stuck on. So, I have 3 target use cases:

• sounds.py I use a custom escape code to play a sound on my local computer. The system bell is insufficient; I use different sounds for different purposes (automatic sound on shell command failed; manual sound on shell command succeeded; sound when Claude is waiting for input).
• open_url.py I want programs like vite dev that automatically open a browser to work over SSH. I do not want this to happen in response to me pressing a key; I want it to happen automatically at the request of the remote program.
• neovide.py I have a custom wrapper for neovide that will trigger it to open over SSH. This is like kitten @ launch, but uses an allowlist to prevent arbitrary code execution.

Creating sounds.py kitten

This is the simplest Kitten as it has no UI. Here's the gist:

sounds.py

import subprocess
from kitty.boss import Boss
from kittens.tui.handler import result_handler

def main(args: list[str]):
    pass

@result_handler(no_ui=True)
def handle_result(
    args: list[str], answer: str, target_window_id: int, boss: Boss
) -> None:
    filename = locate_sound(args[1])
    subprocess.Popen(["afplay", "-v", "0.5", filename])

def is_cmd_allowed(pcmd, window, from_socket, extra_data):
    if pcmd["cmd"] == "kitten" and pcmd["payload"]["kitten"] == "sounds.py":
        return True

def locate_sound(name):
    return f"/path/to/sound_#{name}.wav"

Add the line remote_control_password "" "sounds.py" to kitty.conf, invoke using:

# If kitten is installed:
kitten @ kitten sounds.py name
# If not:
printf '\eP@kitty-cmd{"cmd":"kitten","version":[0, 14, 2],"no_response":true,"payload":{"kitten":"sounds.py","args":["%s"]}}\e\\' name

OK, so this works, but it's janky. Problems I see:

• My is_cmd_allowed function has to understand the implementation details of Kitten's remote protocol.
• I need a main function, but it's unused. I guess if I wanted to add support for invoking this kitten from a binding I would use it. Would be nice if this were not required.
• handle_result is not handling any result, because the main function is never called, but it's the only way to do anything with the invocation.

Questions:

• Is it possible to define a custom command instead? Ideally I could run the kitten at startup via my config, without needing to specify a remote_control_password, and my existing is_cmd_allowed would continue to work, but the cmd would be my command instead of "kitten".

Creating open_url.py kitten

This kitten is a bit more complicated because I do want UI... sometimes. I want this to work like a browser's URL handling: for "safe" http and https URLs, it just works, but for "unsafe" URLs it requests permission. I was able to get this working, mostly:

open_url.py

import subprocess
from kitty.boss import Boss

def main(args: list[str]):
    url = args[1]
    if url.startswith("http://") or url.startswith("https://"):
        return True

    print(f"Open URL: {url}")
    try:
        response = input("Do you want to open this URL? [Y/n] ")
        return response.lower() in ("y", "yes", "")
    except KeyboardInterrupt:
        return False

def handle_result(
    args: list[str], answer: bool, target_window_id: int, boss: Boss
) -> None:
    if answer:
        url = args[1]
        subprocess.Popen(["open", "-u", url])

def is_cmd_allowed(pcmd, window, from_socket, extra_data):
    if pcmd["cmd"] == "kitten" and pcmd["payload"]["kitten"] == "open_url.py":
        return True

Add the line remote_control_password "" "open_url.py" to kitty.conf, invoke using:

# If kitten is installed:
kitten @ kitten open_url.py http://www.example.org/
# If not:
printf '\eP@kitty-cmd{"cmd":"kitten","version":[0, 14, 2],"no_response":true,"payload":{"kitten":"open_url.py","args":["%s"]}}\e\\' http://www.example.org/

This follows the same basic outline as before but it uses a UI this time. It has one minor flaw:

• The screen blinks when opening a "safe" URL, because the UI unconditionally starts (I believe this is creating an overlay window and immediately closing it).

If it were possible to define a custom command, I could resolve the shortcoming by defining two commands: open_url and open_unsafe_url, the former conditionally invoking the second when necessary. I can do this now, of course, but it is inconvenient enough that it's not worth it.

Creating neovide.py kitten

I haven't written this one yet, but here's how it should work:

kitten @ neovide.py named-env /path/within/env [--filename SPECIFIC_FILENAME]

There is a doc section called Adding options to kittens but it doesn't work (ImportError for kitten_options_definition when running kitty.conf.generate.main), and the docs refer to the diff kitten which doesn't look anything like the documentation. I tried copying it, invoking it as kitten neovide.py fails due to the raise in main, and kitten @ kitten neovide.py just blinks my screen and returns. Unclear how to access any of the options.

Questions:

• How do I add options to my kitten? My workaround will be to just call argparse on my args array, but I won't get completion.
• Do I need to deal with __name__ == "__main__" in my kitten?
  • If so, why do my other kittens not have this line but fail if they don't define empty main functions?
• Do I need to deal with __name__ == '__doc__' or __name__ == '__conf__'? When/where are they invoked?

Conclusion

One thing that took me some time to wrap my head around is exactly where kittens get executed. Here's what I've figured out:

• When you run kitten @ kitten my_kitten.py
  • If that kitten is allowed behind a remote_control_password, then is_cmd_allowed is run in the kitty host process. Changing the implementation requires restarting kitty.
  • If the kitten has UI, then main is invoked in a new process on the kitty host machine using an overlay window (and a separate tty?).
  • The handle_result function is invoked in the kitty host process, but the python module is reloaded each time the kitten is invoked.
• When you run kitten my_kitten.py
  • The main function is invoked in the remote kitten process, without an overlay window.
  • The handle_result function is not called.
  • There does not appear to be any reason to invoke a custom kitten this way (except maybe to run in a known Python environment).

Overall I think the extensibility kitten model for extensibility looks exciting, particularly for my target use case (which primarily involves developing in containers, sometimes over SSH). I know that the direct feature request of custom escape codes has been dismissed in the past, but invoking kittens using escape codes is established and doesn't seem to be explored as an alternative to custom escape codes yet.

[kovidgoyal]

I didnt read all that, but I'll just point you to kitten @ run which will work for playing sounds and opening browsers using arbitrary commands, and launch neovide. Though if I were you I'd ditch neovide in favor of nvim and use the edit-in-kitty command that the ssh kitten makes for you.

[CGamesPlay]

Hey, thanks for the reply. You appear to have gotten my goals backwards. I'm not trying to add arbitrary commands, I'm trying to add specifically very limited commands. I was able to do it, but the DX was bad.

Also, the example in the docs for adding options to kittens is wrong, and I haven't been able to figure that out at all. I have a workaround, but I wanted to do things in the "recommended" way as much as possible.

[kovidgoyal]

I dont follow at all. a) You dont need kittens for what you want to do, only remote control. b) You have available to you the exact payload of every remote control command and you can choose to allow/disallow them based on arbitrary code written in an easy to use and widely known language, so I dont know how the "DX" can be made any better. If you have some suggestions to improve the docs, feel free to send a PR.

[CGamesPlay]

I thought about your suggestion to use "kitten @ run" a bit more. Unfortunately, it's worse than what I've built. The command for playing a sound / opening a browser is different between macOS and Linux. If I were to proceed down the "just use kitten @ run" path, each remote machine needs to understand the possible kitty host machines and their implementations, and the kitty host has to to validate the effectively arbitrary shell script (to prevent arbitrary code execution), or more realistically it hav to hard code the same script into the is_cmd_allowed script. What I have is a custom kitten where the implementation can be swapped on my Linux and macOS machines, so the remote machine doesn't need to know how to play a sound, it just calls the "play sound" kitten.

Which brings me back to the DX:

• I don't like the fact that I have to use is_cmd_allowed to validate the payload of a command that I didn't write. The docs don't specify the payload fields used for cmd: "kitten", so they are free to change at any time. If Kitty allowed me to make my own command, I would have full confidence that the payload object wouldn't change out from under me.
• If I could define custom commands, I could put two custom commands into one python file. This would fix the minor annoyance that I talked about in my open_url command.
• The docs for Adding options to kittens are outdated/wrong; the linked example is a Go kitten which doesn't really help me implement my Python kitten. It looks like this whole section is intended to only cover Go kittens, since all the usages I see in the kitty repo are for Go kittens, so maybe it's not something I should be looking at at all.

[rivenirvana]

For #1, I think setting a watcher should cover the usecases? Though I don't really understand all of it (a manual sound on succeed?) https://sw.kovidgoyal.net/kitty/launch/#watchers

For #2, can't you just modify open actions to get different behavior per protocol? https://sw.kovidgoyal.net/kitty/open_actions/

For #3, can't confirm if the docs are incorrect or not

[CGamesPlay]

I think setting a watcher should cover the usecases? Though I don't really understand all of it (a manual sound on succeed?)

I would love to use watchers for this, it feels right, but they don't appear to have the methods I need. on_cmd_startstop doesn't seem to get the exit code of the command, so it can't differentiate between success / failure. on_set_user_var could potentially work. It looks like you have to include $KITTY_WINDOW_ID in the call to kitten, which makes it less convenient to use than the simple printf that my current custom kitten has. I'll play with this approach some more though; I may have missed something.

can't you just modify open actions to get different behavior per protocol?

Well, early on in this page it says "You can tell kitty to take arbitrarily many, complex actions when a link is clicked.". I don't want to click the link; that's what this is about. It would actually be nice to use these protocol handlers to do the behavior I want (just like a browser: http links are opened on click, other links are confirmed), but I still want my non-interactive open to have the same behavior.

[kovidgoyal]

On Sun, Oct 05, 2025 at 05:46:09AM -0700, Ryan Patterson wrote: I thought about your suggestion to use "kitten @ run" a bit more. Unfortunately, it's worse than what I've built. The command for playing a sound / opening a browser is different between macOS and Linux. If I were to proceed down the "just use kitten @ run" path, each remote machine needs to understand the possible kitty host machines and their implementations, and the kitty host has to to validate the effectively arbitrary shell script (to prevent arbitrary code execution), or more realistically it hav to hard code the same script into the `is_cmd_allowed` script. What I have is a custom kitten where the implementation can be swapped on my Linux and macOS machines, so the remote machine doesn't need to know how to play a sound, it just calls the "play sound" kitten.

So create a "play sound" script in ~/.config/kitty/play_sound.sh (or some other stable location) and run that and it can do per platform dispatching as needed. No need for a kitten at all.

Which brings me back to the DX: - I don't like the fact that I have to use `is_cmd_allowed` to validate the payload of a command that I didn't write. The docs don't specify the payload fields used for `cmd: "kitten"`, so they are free to change at any time. If Kitty allowed me to make my own command, I would have full confidence that the payload object wouldn't change out from under me.

So check all the fields in cmd_payload (it is a dict and you can enumerate them) and if they are different from exactly what you expect, deny permission. And the docs do specify them, for example, for @ run: https://sw.kovidgoyal.net/kitty/rc_protocol/#run Though there is no guarantee the fields will never be added to, of course. Hence check the totality of the payload.

- If I could define custom commands, I could put two custom commands into one python file. This would fix the minor annoyance that I talked about in my open_url command.

Like I said above use @ run and run your own script taking whatever command parameters you like and combining whatever functionality you like.

- The docs for [Adding options to kittens](https://sw.kovidgoyal.net/kitty/kittens/custom/#adding-options-to-kittens) are outdated/wrong; the [linked example](https://github.com/kovidgoyal/kitty/blob/master/kittens/diff/main.py) is a Go kitten which doesn't really help me implement my Python kitten. It looks like this whole section is intended to only cover Go kittens, since all the usages I see in the kitty repo are for Go kittens, so maybe it's not something I should be looking at at all.

Only builtin kitten are in Go, custom kittens are written in Python. The syntax for adding options is the same between python and Go, and it is done in main.py, a Python file. You would do exactly what is shown in the example (which is in python) or you would read main.py from the diff kitten to see how to add options from it. I should probably change the link in the docs to link to main.py directly instead of the diff folder. Not to mention that entire section is optional, it's needed only if you want to use kitty's own config handling infrastructure. Frankly it's overkill for you as it brings niceties like static type checking, includes, shortcut parsing etc which you dont need. You can use any config framework you like, for example tomllib or configparser from the python stdlib instead. Though given you are writing a one use kitten for yourself only not sure why you need config at all?

[CGamesPlay]

So create a "play sound" script in ~/.config/kitty/play_sound.sh (or some other stable location) and run that and it can do per platform dispatching as needed. No need for a kitten at all.

Hmm, this is a good idea. Unfortunately "~" and "$HOME" aren't interpolated by "kitten @ run", but I can do kitten @ run sh -c '...'.

And the docs do specify them, for example, for @ run: https://sw.kovidgoyal.net/kitty/rc_protocol/#run

I missed this section of the docs! This actually puts a lot of my fears at rest for doing the invoke.

Taking a step back, given that I thought what I wanted is exactly the scope for a custom kitten, and you repeatedly say that it is not, can you explain what exactly is the use case for custom kittens? I have a few more advanced customizations I want to attempt and would love to do it in the most idiomatic way for Kitten (two examples are: use/modify the ssh kitten to work with containers as well as remote machines, overlay the terminal / scrollback with timestamps of when the lines were modified).

You would do exactly what is shown in the example (which is in python)

I mentioned this in my original post, but doing exactly what is shown in the example gives an ImportError. You're telling me that it's not worth me pursuing this, so I'll follow your advice, but I just want to reiterate what I said before, that what's in the example is outdated/wrong.

$ kitty +runpy 'from kitty.conf.generate import main; main()' (pwd)/kitten_options_definition.py
Traceback (most recent call last):
  File "lib/python3.12/runpy.py", line 198, in _run_module_as_main
  File "lib/python3.12/runpy.py", line 88, in _run_code
  File "lib/python3.12/kitty_main.py", line 7, in <module>
  File "lib/python3.12/kitty/entry_points.py", line 142, in main
  File "lib/python3.12/kitty/entry_points.py", line 100, in namespaced
  File "lib/python3.12/kitty/entry_points.py", line 23, in runpy
  File "<string>", line 1, in <module>
  File "lib/python3.12/kitty/conf/generate.py", line 704, in main
  File "lib/python3.12/importlib/__init__.py", line 90, in import_module
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 999, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/Users/rpatterson/Downloads/kitty/kitten_options_definition.py", line 3, in <module>
    definition = Definition(
                 ^^^^^^^^^^^
  File "lib/python3.12/kitty/conf/types.py", line 652, in __init__
  File "lib/python3.12/importlib/__init__.py", line 90, in import_module
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 999, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/Users/rpatterson/Downloads/kitty/kitten_options_utils.py", line 1, in <module>
    from kitty.conf.utils import KittensKeyDefinition, key_func, parse_kittens_key
ImportError: cannot import name 'key_func' from 'kitty.conf.utils' (/Applications/kitty.app/Contents/Resources/Python/lib/kitty-extensions/python-lib.bypy.frozen/kitty/conf/utils.pyc). Did you mean: 'KeyFunc'?

$ kitty --version
kitty 0.43.1 created by Kovid Goyal

The docs say we should define a function load_config, but don't say how to call it. Searching the built-in kittens, none of them define a load_config function except in Go, so there isn't anything for me to go off of.

[kovidgoyal]

On Sun, Oct 05, 2025 at 08:57:47PM -0700, Ryan Patterson wrote: Taking a step back, given that I thought what I wanted is exactly the scope for a custom kitten, and you repeatedly say that it is not, can you explain what exactly *is* the use case for custom kittens? I have a few more advanced customizations I want to attempt and would love to do it in the most idiomatic way for Kitten (two examples are: use/modify the ssh kitten to work with containers as well as remote machines, overlay the terminal / scrollback with timestamps of when the lines were modified).

kittens are useful when you have something you want to do in response to a mapping that typically involves showing some UI (drawn as a TUI) to the user and then the user interacts with the UI and then the kitten does something with the result of those interactions. The other use case of kittens is when you want to do something that isnt covered by the remote control API by directly manipulating internal kitty data structures, but this has the downside that those data structures are not stable. And finally kittens serve as a nice integration point for creating pure TUI interfaces to enhance functionality, the diff kitten and ssh kitten are good examples of this, they are meant to be run from the command line not via a mapping and there is no "do something with the result of user interactions" step after they are run. You wont be able to do either of those two things using kittens alone, they will both require changes to actual kitty code. Indeed, the second is likely to be impossible since kitty does not store modification times for lines, it would be a performance/memory cost and not something I am likely to accept. As for containers, you could do most of it with a kitten but the "create new window with the same cwd as the current" part would need changes to kitty itself.

> You would do exactly what is shown in the example (which is in python) I mentioned this in my original post, but doing exactly what is shown in the example gives an ImportError. You're telling me that it's not worth me pursuing this, so I'll follow your advice, but I just want to reiterate what I said before, that what's in the example is outdated/wrong.

OK, like I said, I didn't actually read your full post, too much text :) The example may indeed need to be updated a bit.

[CGamesPlay]

Thanks for the detailed explanation. I kinda assumed that the timestamp thing wouldn't be doable without a core change, but I use that feature often enough in iTerm2 that I wanted to investigate how I could get something like it. I cannot fathom how storing a timestamp for each scrollback line could be an unacceptable performance/memory cost (8 bytes per line), but I haven't looked into it in detail, yet.

As for containers, you could do most of it with a kitten but the "create new window with the same cwd as the current" part would need changes to kitty itself.

I really hope this is wrong. I am hoping to hack the ssh kitten to be able to accomplish it, but honestly I don't need a bunch of its functionality (e.g. I'll never use the bundled file transfer feature). I haven't explored the ssh kitten's ins and outs yet, but looking at it from the outside it seems reasonable that it doesn't actually need to be the "ssh" kitten as much as the "remote environment" kitten, and ssh is just a configuration of that. At least, that's my hope.

[kovidgoyal]

There's a reason iTerm is dog slow, it's because it is full of stupid design decisions like that. Tracking modify timestamps per line means that all escape codes that can affect any line on the screen including things like erase region, fill region, deccara, multiline characters, images, etc etc all gain new branches and all of them are in the hot path for performance, not to mention that currently all per line data is tracked in 8 bits you are proposing ballooning that to 16 bytes per line. kitty does insane things like decode UTF-8 in branchless SIMD just to eke out the last bits of performance, there is no way tracking per line modified timestamps would not affect performance. Feel free to try if you want, but you would almost certainly be wasting your time.