{
  "markdown": "# kitty-action-menu\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)\n![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg)\n![kitty](https://img.shields.io/badge/kitty-terminal-black.svg)\n![Python](https://img.shields.io/badge/python-3.x-3776ab.svg)\n[![GitHub stars](https://img.shields.io/github/stars/olispeedy/kitty-action-menu?style=flat)](https://github.com/olispeedy/kitty-action-menu/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/olispeedy/kitty-action-menu)](https://github.com/olispeedy/kitty-action-menu/issues)\n[![Last commit](https://img.shields.io/github/last-commit/olispeedy/kitty-action-menu)](https://github.com/olispeedy/kitty-action-menu/commits/main)\n\nA pop-up action menu kitten for the [kitty terminal emulator](https://github.com/kovidgoyal/kitty).\nIt shows an overlay list of handy actions — copy selection, copy link/path,\npaste, new tab, split, close — driven entirely by kitty's kitten API. It can be\nopened by a right-click, but just as well by a keyboard shortcut or any other\nkitty mapping.\n\n<img src=\"assets/action_menu.png\" alt=\"The action menu rendered in kitty\" width=\"420\">\n\n## Motivation\n\nOther graphical terminals — [Konsole](https://konsole.kde.org/),\n[GNOME Terminal](https://help.gnome.org/users/gnome-terminal/stable/), and\n[Windows Terminal](https://github.com/microsoft/terminal), etc. — pop up a\ncontext menu on right-click. Coming to kitty, that familiar gesture was\nmissing. A _true_ context-sensitive menu (entries that change depending on what\nis under the cursor) turns out to be tricky in kitty, but having a small set of\nuseful default actions one click (or keypress) away is already a nice\nquality-of-life win.\n\nSo this kitten is deliberately **not** dynamic: it isn't a real context menu, it\njust _looks_ a bit like one. The entries are a fixed list of the actions I found\nuseful for myself. It's easy to edit that list (see the `MENU` table in\n`config/user/action_menu.py`) to fit your own workflow.\n\n## Install\n\nCopy the kitten into your kitty config directory:\n\n```sh\ncp config/user/action_menu.py ~/.config/kitty/action_menu.py\n```\n\nThen bind right-click in `~/.config/kitty/kitty.conf`:\n\n```conf\nmouse_map right press ungrabbed kitten action_menu.py\n```\n\nReload the config (`ctrl+shift+f5` on Linux, `cmd+ctrl+,` on macOS) and\nright-click in a window.\n\nTo troubleshoot, append the optional `--debug-action-menu` flag to the binding\n(see [Testing & debugging](#testing--debugging)).\n\n## Requirements\n\n- [kitty](https://github.com/kovidgoyal/kitty) (uses its bundled Python and kitten API)\n\n## Testing & debugging\n\nThe kitten accepts an optional `--debug-action-menu` flag that makes it emit\ntrace output. Add it to your binding while troubleshooting:\n\n```conf\nmouse_map right press ungrabbed kitten action_menu.py --debug-action-menu\n```\n\nTo see that output you have to launch kitty **from another terminal**, so its\nstdout/stderr is visible:\n\n```sh\n# from any other terminal (e.g. macOS Terminal.app, or another kitty window)\nkitty\n```\n\nThen right-click in the new kitty window and pick menu entries. You'll see\nlines like:\n\n```\ndebug[actionmenu]: --- Kitten action_menu started ---\ndebug[actionmenu]: Args: ['action_menu.py', '--debug-action-menu']\ndebug[actionmenu]: on_mouse_event(): type=EventType.PRESS buttons=1 cell=(13,4) pixel=(109,77)\ndebug[actionmenu]: on_mouse_event(): type=EventType.RELEASE buttons=1 cell=(13,4) pixel=(109,77)\nprint[actionmenu]: handle_result: answer=3 target=1, dbg_enabled: False, forced: True\nprint[actionmenu]: menu entry: Paste from Clipboard (paste_clip), dbg_enabled: False, forced: True\nprint[actionmenu]: sel_before='' selection_nonempty=False, dbg_enabled: False, forced: True\nprint[actionmenu]: schedule_remote(): called ('action', '--match=id:1', 'paste_from_clipboard'), dbg_enabled: False, forced: True\n```\n\nReading the output:\n\n- `debug[actionmenu]:` — messages routed through kitty's `debug()` (UI/event\n  logic inside the overlay).\n- `print[actionmenu]:` — messages forced to stdout (`force_print=True`), used in\n  `handle_result` and scheduled callbacks so they show up even when a launcher\n  swallows `debug()`.\n- `on_mouse_event()` lines show the raw event `type`, `buttons` bitmask, and the\n  `cell`/`pixel` coordinates of the click — useful for diagnosing hit-testing.\n- `handle_result: answer=N` is the 0-based index of the chosen `MENU` entry;\n  `answer=8` here is _Cancel_.\n- `sel_before=` / `selection_nonempty=` shows the active selection captured\n  before the action ran (relevant for _Copy Selection_).\n- `schedule_remote(): called (...)` / `combined action:` shows the actual kitty\n  remote-control call or `boss.combine(...)` invocation dispatched for the entry.\n\nTips:\n\n- If nothing appears, confirm the binding actually passes `--debug-action-menu`\n  and that you launched kitty from a terminal (not via the app icon).\n- A `WARNING: ... glCopyImageSubData` line from kitty is unrelated to this\n  kitten — it's a GPU/OpenGL notice and can be ignored.\n- `tests/test_mouse.py` is a standalone kitten that just echoes raw mouse/key\n  events — handy for checking coordinates and event types in isolation. Bind it\n  to a key in `kitty.conf` to run it (it can't be launched from a `mouse_map`),\n  then press the key and click around; Esc quits:\n\n  ```conf\n  map kitty_mod+t kitten tests/test_mouse.py\n  ```\n\n  (`kitty_mod` defaults to `ctrl+shift` unless you've changed it.)\n\n## Documentation\n\nIn-depth design notes, kitty-API gotchas, and how-tos live in the\n[**`llm-wiki/`**](llm-wiki/index.md) knowledge bundle — an\n[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\ncorpus written to be useful to both humans and coding agents. It renders here on\nGitHub (mermaid diagrams included).\n\n## Repository layout\n\n| Path                         | Purpose                                               |\n| ---------------------------- | ----------------------------------------------------- |\n| `config/user/action_menu.py` | The kitten (mirrors the `~/.config/kitty/` layout)    |\n| `llm-wiki/`                  | OKF knowledge bundle: design, gotchas, how-tos        |\n| `tests/`                     | Standalone kittens for probing mouse/key events       |\n| `assets/`                    | Screenshots and other media                           |\n| `.archive/`                  | Earlier AI-generated code/doc variants, for reference |\n| `AGENTS.md`                  | Instructions for AI agents working on this repo       |\n\n## Ideas / roadmap\n\n- **User-configurable menu entries.** Right now the `MENU` list is hard-coded in\n  `action_menu.py`. It would be nicer to define entries in a config file (or in\n  `kitty.conf`) so users don't have to edit the source. A more ambitious version\n  would let you _build_ the menu interactively — pick which actions to include\n  from a chooser, similar to kitty's built-in **command palette** kitten\n  (`kitten @ ...` / the `show_command_palette` action) — and persist the\n  selection.\n- **Per-entry enable/disable based on state** (e.g. grey out _Copy Selection_\n  when there is no selection). This was attempted but **doesn't work reliably**:\n  the menu is drawn in a separate overlay process before an action is chosen, and\n  trustworthy selection / link / path state is only available later in\n  `handle_result()`. The renderer supports a `disabled` flag, but there's no\n  dependable way to compute it at draw time — see\n  [the llm-wiki gotcha](llm-wiki/gotchas/state-at-draw-time.md) for the details. It would likely need upstream kitty support to pass the\n  click-target window state into the kitten.\n\n## A note on AI assistance\n\nThis kitten was developed with the help of AI coding assistants, but every\nfeature was **tested by hand** in a real kitty session before being committed.\nThe AI-generated variants that didn't make the cut are kept in\n[`.archive/`](.archive/) for reference.\n\n## License\n\nGPL v3. See [LICENSE](LICENSE).\n",
  "bytes": 8030,
  "sha": "6c40c430974920494c45aeca2b2185df1247feaf472535a98a954d4cac82a8c8",
  "repo_slug": "olispeedy/kitty-action-menu",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_olispeedy_kitty_action_menu_llm_wiki_ind_06ed1334/readme"
}