Why so many people quit Talon at setup, and how to get past it

Talon is the most capable voice control system there is. Its speech runs on your own machine, its command model is genuinely well designed, and the people who use it every day depend on it completely. It is also free.

And a great many people who would benefit from it never get there. Not because talking to a computer turns out to be unpleasant, but because they hit a wall in the first hour that has nothing to do with voice at all. Here is where.

Wall one: a fresh install appears to do nothing

You download Talon, install it, and it starts. There is a small icon in the menu bar. You say something reasonable, like "scroll down", and nothing happens.

This is correct behaviour and almost nobody expects it. Talon on its own is an engine with no commands. The thousands of spoken forms people talk about live in a separate community command set that you have to go and get. Nothing in the installer says so at the moment you need to know it.

So the very first experience is one of apparent failure, at exactly the point where a new user is deciding whether this thing works. A significant number of people stop here and conclude that voice control is not ready.

Past it: understand that Talon plus a command set is the real product. Getting that set is the actual setup task, not an optional extra.

Wall two: the command set lives on GitHub

The community command set is an open source project, MIT licensed, maintained by the people who use it. It is excellent, and it is distributed the way software projects are distributed: as a repository on GitHub.

For a developer, "clone the community repo" is four words and eight seconds. For a person who has never used Git, it is a wall made of unfamiliar vocabulary. What is a repository. What is cloning. Which of these green buttons. What do I do with a zip file once I have it.

Past it: you can download the repository as a zip archive from the GitHub page without installing Git or making an account. That gets you a folder, which is all you actually need.

Wall three: it has to go in a folder you cannot see

That folder has to end up inside ~/.talon/user/. The leading dot means macOS hides it in the Finder by default, so following the instruction literally leads to a window where the folder you were told to open does not appear to exist.

This is a genuinely nasty step for a non-technical person, because nothing has gone wrong and there is no error to search for. The path simply is not visible.

Past it: in the Finder, press Command, Shift and the full stop key together to show hidden files, or use the Go menu and Go to Folder to type the path directly.

Wall four: changing anything means editing code

Once running, you will want to change something almost immediately. A command that never lands for your voice. A word it keeps mishearing. A shortcut you want for the thing you do forty times a day.

All of that lives in plain text files with a specific syntax, or in Python. Editing them is not difficult in an absolute sense, but it asks a person to open a code editor, understand a file format, and know which of several hundred files to change. When the thing you wanted was to rename one phrase, that is a lot to ask.

There is a sharper version of this problem. The obvious instinct, adding your own version of a command alongside the existing one, creates two spoken forms that match the same phrase. Which one wins is not something a newcomer can reason about. So the intuitive fix produces confusing behaviour, and the correct fix requires understanding the system properly.

Past it: edit the existing command rather than adding a competing one, and keep a copy of anything before you change it.

Wall five: nothing tells you what you can say

This is the one that quietly defeats people who got everything else right. You now have a working system that knows several thousand commands and no way to browse them. The knowledge lives in documentation, a community wiki, and a Slack workspace.

So the daily experience becomes: want to do a thing, suspect there is a command for it, cannot find out without leaving what you were doing and searching a wiki. Most people simply reach for the mouse instead, and slowly stop using the system they just installed.

Past it: there is no clean answer within Talon itself. Learn a small number of commands deliberately and add to them on purpose rather than hoping to absorb them.

None of this is Talon's fault

Talon was made by a developer, largely for developers, many of whom came to it because they could no longer type and still needed to write software. Judged as a tool for that audience it is exceptional, and the setup process is entirely unremarkable for the people it was designed for.

The gap is one of audience, not quality. The people most likely to need hands-free computing are not, in general, the people most comfortable cloning a repository into a hidden directory. That is the whole problem, and it is a solvable one.

If you are going to do it by hand

The honest short version of the manual route, in order:

1. Install Talon from its website and let it start.
2. Go to the community command set on GitHub and download it as a zip.
3. Show hidden files in the Finder, or use Go to Folder, and open ~/.talon/user/.
4. Put the unzipped folder inside it.
5. Restart Talon. Say something simple and confirm it responds.
6. Find the community documentation and bookmark it, because you will need it.

Budget an evening the first time, and do it while your hands still work rather than during a flare-up. That last piece of advice is the one people wish they had taken.

Common questions