{"id":13495347,"url":"https://github.com/charlespascoe/vim-serenade","last_synced_at":"2025-04-13T06:50:41.966Z","repository":{"id":49804897,"uuid":"475514392","full_name":"charlespascoe/vim-serenade","owner":"charlespascoe","description":"Vim Plugin for Serenade.ai","archived":false,"fork":false,"pushed_at":"2022-10-25T22:22:02.000Z","size":47,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T22:45:57.426Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charlespascoe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-29T15:51:22.000Z","updated_at":"2023-09-29T19:15:18.000Z","dependencies_parsed_at":"2023-01-20T09:43:23.441Z","dependency_job_id":null,"html_url":"https://github.com/charlespascoe/vim-serenade","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charlespascoe%2Fvim-serenade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charlespascoe%2Fvim-serenade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charlespascoe%2Fvim-serenade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charlespascoe%2Fvim-serenade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charlespascoe","download_url":"https://codeload.github.com/charlespascoe/vim-serenade/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675458,"owners_count":21143766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:33.810Z","updated_at":"2025-04-13T06:50:41.940Z","avatar_url":"https://github.com/charlespascoe.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Vim Plugin for Serenade.ai\n\nWrite code with your voice in Vim with [Serenade](https://serenade.ai).\n\nFeatures:\n\n- Supports multiple instances of Vim running simultaneously, switching focus as\n  needed\n- Supports integration with third-party plugins for language-specific features\n  (e.g. jumping to definitions or debugging)\n- Custom Serenade commands to do anything you want inside Vim (e.g. split view,\n  buffer management, running arbitrary vimscript)\n\n- [Requirements](#requirements)\n- [Installation and Usage](#installation-and-usage)\n    - [Tmux](#tmux)\n- [Configuration](#configuration)\n    - [Serenade Command Configuration](#serenade-command-configuration)\n- [Custom Commands](#custom-commands)\n- [Known Issues](#known-issues)\n- [Troubleshooting](#troubleshooting)\n\n## Requirements\n\n- [Serenade](https://serenade.ai/download)\n- Python 3\n- Python `websockets` module (`pip3 install websockets`)\n- Vim 8\n\nDeveloped and tested on MacOS, should work on Linux.\n\n## Installation and Usage\n\nUsing the built-in package management:\n\n```\ngit clone https://github.com/charlespascoe/vim-serenade.git ~/.vim/pack/vim-serenade/start/vim-serenade/\n```\n\nBy default, `vim-serenade` will start automatically when Vim opens, or you can\nuse the `SerenadeStart` command.\n\n**Note:** You may need to set the `g:serenade_match_re` config option depending\non how you're running Vim (see below). When you focus on Vim (or the terminal\nthat's running Vim), Serenade should say \"Vim\" in the bottom-left corner.\n\n### Tmux\n\nIf you're using tmux with multiple Vim instances, you'll need to add the\nfollowing to your tmux config:\n\n`set -g focus-events on`\n\nThis will ensure the currently-focused Vim instance receives the Serenade\ncommands.\n\n## Configuration\n\nFor Serenade to detect when Vim is focused, it uses a regular expression to\ncheck the name of the foreground process. In `vim-serenade`, this regular\nexpression is configurable using the `g:serenade_match_re` in your `vimrc`, which\ndefaults to `term` (i.e. 'term' must be present somewhere in the process name,\ne.g. 'iterm2' or 'terminal'). If you're using another terminal or are using\ngvim, you'll need to change it to something that will match the process name:\n\n```\nlet g:serenade_match_re = 'alacritty'\n```\n\nNon-command options are listed below; these options should be in your `vimrc`\nso that they are set before the plugin is loaded.\n\n\n| Config Option | Default Value | Description |\n|---------------|---------------|-------------|\n| `g:serenade_autostart` | `1` | Automatically runs `SerenadeStart` command on start. |\n| `g:serenade_app_name` | `'Vim'` | The application name that is displayed in Serenade. |\n| `g:serenade_match_re` | `'term'` | The regular expression that Serenade uses to determine whether the focused application is associated with this plugin. |\n| `g:serenade_websocket_address` | `'ws://localhost:17373'` | The Serenade WebSocket address to connect to, mostly intended for testing purposes. |\n| `g:serenade_enable_logging` | `0` | Turns on logging (`~/.vim-serenade.log`). |\n\n### Serenade Command Configuration\n\nMost Serenade commands are mapped to simple Vim commands, which can be\noverridden globally or on a per-buffer basis (e.g. to have different commands\nfor different file types). Per-buffer options are preferred over global\noptions, global options are preferred over the default options.\n\nTo set an option globally, use the global scope (`g:`) in your `vimrc`:\n\n```\nlet g:serenade_save_command = 'wa'\n```\n\nTo set an option for a particular file type, use the buffer scope (`b:`) in the\nappropriate `ftplugin` file. For example, to set the \"go to definition\" command\nto use the [`vim-go`](https://github.com/fatih/vim-go) plugin for Go files, add\nthe following line to `~/.vim/ftplugin/go.vim`:\n\n```\nlet b:serenade_go_to_definition_command = 'GoDef'\n```\n\nThe following command options are available; they can be set or changed at any\ntime.\n\n\n| Config Option | Default Value |\n|---------------|-----------------|\n| `serenade_create_tab_command` | `'tabnew'` |\n| `serenade_close_tab_command` | `'tabclose'` |\n| `serenade_next_tab_command` | `'normal gt'` |\n| `serenade_previous_tab_command` | `'normal gT'` |\n| `serenade_undo_command` | `'normal u'` |\n| `serenade_redo_command` | `'exec \"normal \\\u003cC-r\u003e\"'` |\n| `serenade_save_command` | `'w'` |\n| `serenade_back_command` | `'exec \"normal \\\u003cC-o\u003e\"'` |\n| `serenade_forward_command` | `'exec \"normal \\\u003cC-i\u003e\"'` |\n| `serenade_style_command` | None |\n| `serenade_go_to_definition_command` | None |\n| `serenade_debugger_toggle_breakpoint_command` | None |\n| `serenade_debugger_start_command` | None |\n| `serenade_debugger_pause_command` | None |\n| `serenade_debugger_stop_command` | None |\n| `serenade_debugger_show_hover_command` | None |\n| `serenade_debugger_continue_command` | None |\n| `serenade_debugger_step_into_command` | None |\n| `serenade_debugger_step_out_command` | None |\n| `serenade_debugger_step_over_command` | None |\n| `serenade_debugger_inline_breakpoint_command` | None |\n| `serenade_reload_command` | None |\n| `serenade_pause_command` | `''` (No-op) |\n\n## Custom Commands\n\nSerenade allows you to define custom commands to perform arbitrary actions.\nUsing the `evaluateInPlugin()` method, you can run arbitrary Vim commands from\ncustom Serenade voice commands; for example, add the following to\n`~/.serenade/scripts/custom.js` to add some simple commands to control things\nlike splits:\n\n```js\nconst vim = serenade.app('Vim');\n\nvim.command(\n  'split',\n  (api) =\u003e api.evaluateInPlugin('vsplit'),\n);\n\nvim.command(\n  'horizontal split',\n  (api) =\u003e api.evaluateInPlugin('split'),\n);\n\nvim.command(\n  'center',\n  (api) =\u003e api.evaluateInPlugin('normal zz'),\n);\n\nvim.command(\n  'close',\n  (api) =\u003e api.evaluateInPlugin('q'),\n  {autoExecute: false},\n);\n```\n\nYou can run anything that is a valid Vim command, including running vimscript\nfunctions (e.g. `call MyFunction()`), which you can use to pass data extracted\nfrom voice commands. For more examples, see the `serenade-custom-commands.js` in\nthis project or take a look at [my list of custom\ncommands](https://github.com/charlespascoe/dotfiles/blob/master/serenade/custom.js).\n\n## Known Issues\n\n- Back/Forward commands don't seem to be passed to the plugin at the moment; see\n  `serenade-custom-commands.js` for a work-around.\n- Select isn't implemented yet.\n\n## Troubleshooting\n\n**Serenade doesn't detect when I switch to a different instance of Vim**\n\nAdd the following to your `vimrc`, open multiple instances of Vim, then switch\nbetween vim instances to see if it logs a message:\n\n`au FocusGained * echom \"Focus Gained\"`\n\nThis event is used to determine which instance of Vim is currently focused, and\nto send a message to Serenade so that control commands are sent to the correct\ninstance of Vim.\n\nIf you are using tmux and nothing is logging when you switch between Vim\ninstances, then try installing\n[vim-tmux-focus-events](https://github.com/tmux-plugins/vim-tmux-focus-events),\nand be sure to set any necessary tmux config options.\n\nIf you are using some other terminal or terminal multiplexer, then you may wish\nto search for \"\\\u003cname of terminal/multiplexer\u003e vim FocusGained\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharlespascoe%2Fvim-serenade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharlespascoe%2Fvim-serenade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharlespascoe%2Fvim-serenade/lists"}