Cursorless consists of
- an IDE plugin (eg a VSCode extension), and
- a set of Talon files that define spoken commands
Because of this split, Cursorless has user settings available both on the IDE side, and on the Talon side. The rule of thumb is that anything that changes spoken forms happens Talon-side; everything else is IDE-side.
The IDE settings can be accessed by saying
"cursorless settings" with your IDE (eg VSCode) focused.
Many of the spoken forms used in cursorless can be easily customized without needing to fork cursorless or modify the talon / python files contained therein. If you find that your customization needs cannot be met without making changes to cursorless files, please file an issue so we can improve customization.
The spoken forms for actions, scope types, colors, etc can be customized using the
csvs found in the
cursorless-settings subdirectory of your Talon user folder. On
Linux and Mac, the directory is
Windows, it is
The directory location can be customized using the
user.cursorless_settings_directory Talon setting. If the path is relative, it will be taken relative to your Talon user directory.
Note that these csv's:
- support empty lines,
- support multiple spoken forms for a single identifier using
|as a separator, eg
- support comment lines beginning with
- ignore leading / trailing whitespace on identifiers and spoken forms
If the spoken form begins with a
-, it will be disabled. Please do not remove
any lines, because that will trigger cursorless to add them back on next
reload, as cursorless uses these lines to track disabled spoken forms.
Changing a spoken form
Simply modify the spoken form in the first column of any of the csvs in the directory above to change the spoken you'd like to use. The new spoken form will be usable immediately.
Multiple spoken forms can be used for the same action using the pipe operator
When new actions, scope types, etc are added, Cursorless will detect that they're missing from your csvs and append the default term to the end. You can then feel free to modify the spoken form if you'd like to change it.
Removing a term
If you'd like to remove an action, scope type, etc, you can simply set the
spoken form in the first column to any thing starting with
-. Please don't
delete any lines, as that will trigger cursorless to automatically add the
spoken form back on talon restart.
[Experimental] Cursorless custom IDE actions
You can use Cursorless to run any built-in IDE command on a specific target.
Just add your custom commands to:
experimental/actions_custom.csv. For example, if you wanted to be able to say
"push down <T>" to move the line(s) containing target
<T> downwards, you could do the following:
Spoken form, VSCode command
push down, editor.action.moveLinesDownAction
Now when you say eg "push down air and bat", cursorless will first select the two tokens with a gray hat over the
b, then issue the VSCode command
editor.action.moveLinesDownAction, and then restore your original selection.
Toggling "hat" display
It is possible to show / hide the hats with a command. Keep in mind that many users, often after less than a week using Cursorless, find that their brain starts to tune out the hat display. Some start to miss them when they're gone 🥲
However, should you like to show / hide the hats within your editor, you can use the following approach.
- Bring up the command pallet(
Shift + CMD + Pon Mac;
Shift + Ctrl + Pon Windows / Linux).
Cursorless Toggleto see the command in the dropdown.
You should also be able to find the above command by saying
"please toggle". The same command can be repeated to turn the hats back on.
While the hats are hidden, you will not be able to address any marks, eg
"take air". However, Cursorless will still recognize scopes, eg
If you'd like to map a voice command to toggle the hats, have a look at https://youtu.be/oWUJyDgz63k
Updating word separators
The word separators are characters that defines the boundary between words in a identifier. eg
hello_world is an identifier with two words separated by
_. If you like to support other separators like
hello-world that can be accomplished by changing the
cursorless.wordSeparators setting. This setting is also language overridable.
// Sets the word separator for all languages
// Sets the word separator for css only
"cursorless.wordSeparators": ["_", "-"]
Cursorless public API
Cursorless exposes a couple talon actions and captures that you can use to define your own custom command grammar leveraging cursorless targets.
Public Talon captures
<user.cursorless_target>Represents a cursorless target, such as
"air past bat",
"air and bat",
"funk air past token bat and class cap", etc
Public Talon actions
user.cursorless_command(action_id: str, target: cursorless_target): Perform a Cursorless command on the given target eg:
user.cursorless_command("setSelection", cursorless_target). Note that for
cursorless_targetwill be the source of the bring and the destination will be the current selection(s), as if you had said
user.cursorless_ide_command(command_id: str, target: cursorless_target): Performs a built-in IDE command on the given target eg:
user.cursorless_insert(destination: CursorlessDestination, text: Union[str, List[str]]): Insert text at destination. eg:
See snippets for more information about Cursorless snippets.
user.cursorless_insert_snippet_by_name(name: str): Insert a snippet with the given name, eg
user.cursorless_insert_snippet(body: str, destination: Optional[CursorlessDestination], scope_type: Optional[Union[str, list[str]]]): Insert a snippet with the given body defined using our snippet body syntax (see the snippet format docs). The body should be a single string, which could contain newline
\ncharacters, rather than a list of strings as is expected in our snippet json representation. Destination is where the snippet will be inserted. If omitted will default to current selection. An optional scope type can be provided for the target to expand to.
"snip if after air"for example could be desired to go after the statement containing
airinstead of the token.
user.cursorless_wrap_with_snippet_by_name(name: str, variable_name: str, target: CursorlessTarget): Wrap the given target with a snippet with the given name, eg
functionDeclaration. Note that
variable_nameshould be one of the variables defined in the named snippet. Eg, if the named snippet has a variable
$foo, you can pass in
targetwill be inserted into the position of
$fooin the given named snippet.
user.cursorless_wrap_with_snippet(body, target, variable_name, scope): Wrap the given target with a snippet with the given body defined using our snippet body syntax (see the snippet format docs). The body should be a single string, which could contain newline
\ncharacters, rather than a list of strings as is expected in our snippet json representation. Note that
variable_nameshould be one of the variables defined in
body. Eg, if
bodyhas a variable
$foo, you can pass in
targetwill be inserted into the position of
$fooin the given named snippet. The
scopevariable can be used to automatically expand the target to the given scope type, eg
Example of combining capture and action
add dock string <user.cursorless_target>:
push <user.cursorless_target> down:
Disable legacy destination grammar
The grammar currently supports
paste to before air. This grammar is considered deprecated/legacy and replaced by
paste before air. You can today disable this legacy grammar by enabling the tag