raw notes from learning to use cursorless keyboard

[josharian]

Grabbed the sample config from the repo.
Ran it through ChatGPT to make a printable spreadsheet / cheatsheet.
Plan is to start with just navigation: Identify a hat, do pre/post.
Once I have muscle memory with that, add stuff.

First impression: It's a lot of keystrokes!

ctrl-c to enter cursorless mode
d for default
u for urge
a for action
h for pre

and then i'm out of cursorless mode again.

I definitely wish (right now) that I could cut "a" for action, but "h" has a top level meaning.

"l" for post doesn't have a top level meaning, so ctrl-c,d,u,l should work, but I get that "l" is an invalid key. Bug?

Seems like staying in cursorless mode longer might be important.

When I type f,x,b,z (combine, blue, bolt), the status bar says "What hat?" I think it means "which glyph/char", which is a bit confusing.

Wanted to use paint. Tried to use just "p" instead of "sp", but "p" competes with "pink". Starting to think that unless the top level key sets shrink dramatically, I'm going to always type "sX" for scopes and "aX" for actions, because the shorter version works so rarely, and I want muscle memory.

Used move. The mechanics (identify target, select target, identify source, move to target) feel clunky and like a lot of keystrokes, but that might just require getting used to. 13 keystrokes to move one bit of text to another:

ctrl-c,d,a,ss,at,d,3,sp,am,escape

Weird that change (clearAndSetSelection) is just "c", not "ac". I think for learnability having the "a" prefix be universal might be important.

"change" drops you out of cursorless mode. Which makes sense, I guess? I'll just have to learn which actions do that.

No userColor1 or userColor2 yet in the configs, need to add those. Can't find chuck either. It's striking how missing any little part makes the whole thing feel less useful.

Screwed up pre vs post. Being dropped out of cursorless mode was annoying, because I had to re-enter it to fix. I think I never want to be automatically dropped out of cursorless mode (?).

I want an in-cursorless-mode undo button. Time to make my first config edit.

    "vz": {
      "commandId": "undo"
    }

Works great. The line between action and vscode command is blurry. "vz" for undo but not "vc" for copy because copy is "ac". Hmmm.

My cheatsheet would be easier to use if I had spoken forms instead of internal identifiers. Less mental translation. It took a couple of back-and-forths, but ChatGPT is pretty good at making cheatsheets. The annoying part was gathering all the data (e.g. the spoken form csvs, the vscode configs). I wonder whether in the future a standard thing will be the ability to download a blob of text that is geared for feeding into a chatbot, with all the relevant data and some plain language description of what it is. I think this might be relatively easy to do for Cursorless right now...

Adding userColor1 or userColor2 to the config is annoying, because it is hard to find what letters are still available at the top level. ChatGPT to the rescue...still, this will be an ongoing challenge. (Ended up with "w" for white and "q" for black...because blaQ. I know. The top level space is pretty crowded.)

Can't figure out how to do "three tokens air". I can get third next token air (3nst) and next three tokens air (n3st). Maybe it's just not implemented yet. The railroad diagram was instrumental to figuring out even those two that do work.

The highlighting when I identify a mark blends in and can be hard to see. See screenshot. believe it or not, in that screenshot, the highlighted thing is "white dot".

Oh, backspace is "chuck". I think it should have its own key? Maybe? Maybe not.

Pour should definitely not exit cursorless mode; I just used it for the first time to make space for another line that I brought over using "bring".

Need some reset button? If I make a mistake, I have no idea what state things are in and wild things happen. I can press escape then ctrl-c, but that feels heavy.

[pokey]

😂 love the stream of consciousness format. Not too many surprises there tbh. Let's discuss

[pokey]

Also just a note for people seeing this: @josharian is using the very experimental new commands which aren't really ready for public consumption. If you're interested in experimenting with something that will break soon, feel free to try it out, but do leave a message here so we can let you know when we break something 😊

[pokey]

Also, note that I have spent essentially zero time on the key mappings themselves, so don't make any effort to preserve them. My thinking was that we would keep track of token frequencies and use that to construct a Huffman coding

[josharian]

So far they're pretty efficient, and mainly home row.

One win might be requiring an action to terminate every command (and providing a no-op action for use in typos). This would cut one keypress from most things.

[pokey]

One win might be requiring an action to terminate every command (and providing a no-op action for use in typos). This would cut one keypress from most things.

Sorry not sure I follow. How would that cut one keypress? At any point, another modifier could come, so you'd still need to avoid conflicts with those. I guess we could exclude the marks?

[pokey]

Re dropping out of Cursorless mode, that's easy enough to change. Curious what you're using "pre" and "post" for where you want to remain in Cursorless mode?

[josharian]

Re dropping out of Cursorless mode, that's easy enough to change.

Yeah. And maybe the config could support overriding the default, similar to the vscode action configs.

Curious what you're using "pre" and "post" for where you want to remain in Cursorless mode?

• Mistakes
• Better hats (if I'm going to work in an area a fair amount, I move there first to make all subsequent commands nicer)

Also, consistency helps build muscle memory. I'd be happy to always remain in Cursorless mode.

(And muscle memory is weird. After using cursorless keyboard for just a few minutes, I systematically try to :w to save instead of cmd-s, without thinking about it.)

[josharian]

Curious what you're using "pre" and "post" for where you want to remain in Cursorless mode?

Another thing: "bring bat after air"

I do this by "default air post default bat bring".

[josharian]

Curious what you're using "pre" and "post" for where you want to remain in Cursorless mode?

Another: Go to beginning of long function, then start operating on args etc. ("default air scope func pre")

[josharian]

OK, experimenting with ah, al = pre, post ; aH, aL = pre, post with exit.

[pokey]

Another thing: "bring bat after air"

I do this by "default air post default bat bring".

Must be annoying that doesn't insert space tho. We should implement "bring after"

[pokey]

When I type f,x,b,z (combine, blue, bolt), the status bar says "What hat?" I think it means "which glyph/char", which is a bit confusing.

I was actually thinking that the input of character would become a token in the parser itself, so then you'd actually get no feedback in the status bar other than what you'd already typed, like for other things

[josharian]

Another discovery: plain old pour (ctrl-c,ao) doesn't work, I have to grab a line first (ctrl-c,i,ao). Feels like a bug?

[pokey]

Oh yeah I have a fix for that kinda thing incoming

[josharian]

Jotting down some crude notes for things discussed on call (ideas, discussion points, etc, not really a todo list, just mnemonics):

• missing inside
• match spoken form exactly? Subject-Object-Verb vs Object-Subject-Verb, etc
• missing full-fledged modifiers (3 tokens), destinations
• specify in config whether an action exits cursorless mode
• current key sequence as uncommitted transaction, backspace edits that transaction
• importance of hat stability; use space to “end” current sequence?
• muscle memory and predictability vs Huffman coding (but on further thought this may be a false dichotomy)

[pokey]

filed:

• keyboard: Make it configurable whether an action exits cursorless mode #2117
• keyboard: backspace deletes a key from current key sequence #2118
• keyboard: simple local keyboard history #2119

[josharian]

Idea: Should we make re-assigning hats an explicit action? There's no natural "end of command" in keyboard, and keeping hats stable is useful for rapid chaining. A single explicit keystroke and/or exiting cursorless mode would be a good moment to update hats.

[pokey]

We could experiment with things along these lines. A couple easy ways to try it just using existing settings:

• set decoration debounce timeout setting higher
• set hat stability to stable

I'm not opposed to adding a reallocate hats command as well. It should be trivial to implement. And now that we have various stable hats I think it could be useful even ignoring keyboard. Back when hats were only greedy it didn't make much sense.

Then you can just use our support for mapping keys to arbitrary VSCode commands to run it

[josharian]

Idea: "macros". Maybe represented in json config as an array of cursorless inputs (each of which is a string or a dictionary).

Use case: Currently a very high proportion of my cursorless keyboard usage is "bring air to this". (Maybe this'll change as my usage and cursorless keyboard both develop.) I'd like this to be of the form "d a ap" (default; air; bring-to-this) rather than the current "d x at d a au" (default; plex-for-this; take; default; air; bring).

Related: It'd be nice to have key mappings for this, that, source. That'd help a little here, but macros would be better yet. :)

[pokey]

Fwiw on the branch I shared (with some cleanup) you should be able to just use at at the beginning to select current token. I'm assuming that's what you're after for that specific use case?

But macros could be interesting; prob would use dsl described in #492

[josharian]

I haven’t gotten past code review + trying to fix the build errors, but will play with that

[josharian]

Weird thought I keep having: I want a “short literal” mode. Press the short literal key sequence, and then type any key sequence (the literal), then enter, and it inserts the literal. It is equivalent to exiting cursorless mode, typing text, and then re-entering cursorless. But mode switching is mentally expensive, and this feels “easier”. Jogging it down here for future consideration.

[pokey]

huh interesting. tho it would be nice to see the literal you're typing

[josharian]

In the spirit of writing down the things I find that I want: I want snippet integration. But I moved all my snippets to talon, because it’s nicer. Hmmm. Probably maybe I could hack this in for a handful of snippets—it’d be enough—using vscode commands. Will have to try that.

[pokey]

fwiw we will prob support cursorless being able to just read from your talon snippets dir if you point your cursorless snippets dir at it

[josharian]

Prefix ambiguity I'd like to allow:

• - means "backwards" when followed by a number, i.e. "-3st" is "three tokens backwards"
• - means "extend" when followed by a mark, i.e. "da-dc" is "air past cap"

[pokey]

one prob is that -st means "token backward", which is a thing, tho very uncommon

[josharian]

i'd be happy having to write -1st for token backward.

[josharian]

fwiw, i've been using , for "append" and - for "extend", and have been happy with it. (i changed collection item from , to si.)

[josharian]

I changed to ! for backward, which I rarely use.

[josharian]

For the day when this is not experimental and we are writing how to guides: https://gist.github.com/josharian/674ab547578e3d1e905f706bb549a440 is a karabiner elements complex modification to make "single tap left command key" enter cursorless mode.

[josharian]

I find myself wanting some kind of "reset" mechanism. I make a mistake or a typo and then it is in a weird state and I don't know how to get back to normal currently I exit cursorless mode and then reenter cursorless mode, which is fundamentally fine but feels wrong/clunky somehow. Maybe I just need to get over it.

[josharian]

Oops, I wrote that in the original pile of goo above. Guess it is a recurring theme. :)

[josharian]

It would also help if the toast error messages telling me I made a mistake autodismissed after a little while.

[pokey]

You should be able to just press "escape" if you've mapped your keyboard shortcuts correctly