Skip to content

command_client

The community/apps/vscode/command_client directory provides a mechanism for Talon to communicate with VS Code using a file-based RPC (Remote Procedure Call) system. This allows Talon to send commands to VS Code and receive responses, even if VS Code doesn't have a direct API for Talon to interact with. It handles potential conflicts between multiple Talon instances or the same instance starting a new phrase. The system is designed to be robust even if the command server is unavailable.

The core functionality resides in the rpc_client subdirectory, which has its own detailed explanation. However, the files in this directory provide the user-facing interface to that RPC system, and also provide application-specific configurations.

Here's a breakdown of the key files:

  • command_client_tag.py: This file defines the command_client tag, which is used to enable the command client functionality for a given application. It also defines the command_server_directory action that must be implemented by each application that wishes to use the command client.

  • visual_studio.py: This file configures the command client for Visual Studio. It sets the user.command_client tag when the application is visual_studio, and it implements the command_server_directory action, returning "visual-studio-command-server".

  • command_client.py: This file provides the main interface for running RPC commands. It defines actions like run_rpc_command, run_rpc_command_and_wait, and run_rpc_command_get. These actions take a command ID and up to 5 optional arguments. They call the rpc_client_run_command action from the rpc_client subdirectory, which handles the actual communication. This file also handles emitting a pre-phrase signal, allowing for Cursorless and other code to know when a command phrase is beginning. It also defines the trigger_command_server_command_execution action, which is a keystroke to trigger the command server to execute the command. This action is OS-specific.

  • vscode.py: This file configures the command client specifically for VS Code. It sets the user.command_client tag when the application is vscode and provides the command_server_directory action implementation, returning "vscode-command-server". It also provides actions like vscode and vscode_and_wait, that provide a user-friendly way to run VS Code commands using the command server. If the command server is not available, these actions fall back to the command palette. Finally, it also defines actions for backwards compatibility, which call the new actions in command_client.py.

  • README.md: This file provides a high-level overview of the command client and instructions for contributing to the repository. Note that the code is maintained in two repos (the community repo and a dedicated one), and it gives instructions for keeping both in sync.

In summary, the files in this directory provide the glue between the generic RPC client in the rpc_client subdirectory and specific applications like VS Code. The command_client.py provides a generic way to run RPC commands through actions, while the vscode.py and visual_studio.py files provide app-specific configurations. They use the command_client tag, the command_server_directory action, and provide a user-friendly experience for calling commands, even if the server isn't available.