Troubleshooting

Here are a list of common issues you might encounter, along with possible solutions:

Typing a letter after a cursorless command

Scopes without a mark

Due to the way that cursorless allows you to omit marks (eg "take funk" instead of "take funk this"), the grammar can be slightly ambiguous to parse. The most common example will be if you omit the mark (eg "clear funk"), and then try to type a letter ("air"). In that case, when you say "clear funk air", talon will parse it as a single command to clear the function with a gray hat over an a, which is usually what you mean. However, if you did want to clear the function containing the cursor, and then type "a", then the parse will be incorrect. To work around this limitation, there are a few options:

• Option 1: pause after "clear funk" so that it is broken into two separate command phrases "clear funk", then "air"
• Option 2: say "clear funk this air" instead, so that you make the mark explicit
• Option 3: add the command then: skip() to a talon file, which makes a command called "then" that does nothing, but can be used to break up the command phrase. Then you can say "clear funk then air"

"red"

A similar ambiguity can arise if you use the default color name for red and the default letter name for r mapped in knausj, both of which are "red". In this case, if you say "clear red air", it could be interpreted as either of the following:

• "clear red" (referring to token with a gray hat over r), followed by "air" (to type the letter a), or
• "clear red air" (referring to the red hat over an a).

Most of the time you’ll mean the latter, and that is how talon will interpret the command. But occasionally you’ll want the former. As above, you have a few options:

• Option 1: pause after "clear red" so that it is broken into two separate command phrases "clear red", then "air"
• Option 2: change r to be eg "risk" or "ram" in your talon alphabet to avoid the conflict
• Option 3: map a then: skip() command as above. Then when you actually want the first behaviour, you’ll say "clear red then air"

When a variable is grayed out, the red hat looks pink

When you have an unused variable, VSCode will make it semi-transparent. Unfortunately, this transparency also applies to any cursorless hats over the variable, so if you are using a light background, then any red hat on the variable will be blended with the light background and look pink. We have filed an issue with VSCode to fix this one, but it might be a while.

In the meantime, your best bet is probably to disable the pink hat and instead enable userColor1, which has a default voice command of "navy". To do so, search for cursorless.hatEnablement.colors in your VSCode settings, and uncheck the box next to pink and check the one next to userColor1. Then when you pull up the cheatsheet you should see that "pink" has been replaced by "navy", and a new navy hat color should show up in your editor instead of pink.

Decorations don't scale with editor zoom

If you're seeing something like https://github.com/cursorless-dev/cursorless-vscode/issues/78, see https://github.com/cursorless-dev/cursorless-vscode/issues/78#issuecomment-1050052641

Custom <number_small> capture is not being used by Cursorless

If you have a custom <number_small> capture, and you'd like Cursorless to use it for eg "row" commands and ordinals, you can enable the user.cursorless_custom_number_small tag. See https://github.com/cursorless-dev/cursorless/issues/1021 for why we override <number_small> by default.