Skip to content

command_client

The Talon Command Client module provides a high-performance, file-based Remote Procedure Call (RPC) interface. This mechanism allows Talon to communicate reliably with external applications, such as text editors (like VS Code) that run a local command server.

Through a combination of serialized JSON payloads, platform-specific keyboard shortcuts, and filesystem polling, the client triggers and orchestrates external editor actions synchronously or asynchronously.

Architectural Overview

The file-based RPC process relies on a cooperative handshake between Talon and the target application:

┌───────────────┐                  ┌───────────────────────────┐
│ Talon Speech  │                  │    rpc_client Module      │
│  Environment  │                  │ (Handles file-system IPC) │
└───────┬───────┘                  └─────────────┬─────────────┘
        │                                        │
        │ 1. Triggers Action                     │
        ▼                                        ▼
 ┌───────────────┐   Writes JSON Request  ┌─────────────┐
 │  command_      ├──────────────────────►│  Temporary  │
 │  client.py    │                        │  Directory  │
 └──────┬────────┘                        └──────┬──────┘
        │                                        ▲
        │ 2. Sends Hotkey Trigger                │ Writes Response
        ▼                                        │
 ┌───────────────┐                               │
 │ Target Editor │───────────────────────────────┘
 │ (e.g. VSCode) │
 └───────────────┘
  1. Request Formulation: A spoken command triggers an action in command_client.py.
  2. Serialization: The client writes a structured JSON payload targeting a directory specified by the host application (using rpc_client).
  3. Application Signaling: Talon sends an OS-specific keypress (e.g., ctrl-shift-f17 or cmd-shift-f17) to force the active application to read and process the request file.
  4. Polling and Resolution: The client polls the temporary directory for a corresponding JSON response, parses the result, safely cleans up the files, and returns the output to Talon.

Core Components

The implementation is split into a declaration tag, the primary coordination actions, and a low-level IPC transport layer.

1. Declaring Capabilities: command_client_tag.py

This file defines the user.command_client tag, indicating that the active application supports file-based RPC communication. It also declares the core interface method:

  • command_server_directory(): Returns the directory name dedicated to the application's RPC files. Each supporting application must implement its own context override for this action to specify where its command server communicates.

2. Action Coordination: command_client.py

This is the central coordinator for all RPC tasks. It defines the actions used by user voice commands and handles phrase lifecycle events:

  • RPC Runners: Actions like run_rpc_command, run_rpc_command_and_wait, and run_rpc_command_get provide varying execution strategies (e.g., fire-and-forget, block until completion, or fetch command return values).
  • Operating System Specializations: Contexts are matched by platform. While Windows and Linux issue ctrl-shift-f17 to trigger the application's command server, macOS overrides this behavior to use cmd-shift-f17.
  • Speech Phrase Synchronization: Registers with Talon’s speech system (pre:phrase and post:phrase) to write a prePhrase signal file in the communication directory. This allows integrations (such as Cursorless) to track exact phrase boundaries and synchronize with Talon.

3. File IPC Transport: rpc_client

This subdirectory contains the implementation details for file-based communication. It manages the lower-level mechanics of:

  • Resolving platform-specific temporary directories safely across multi-user environments.
  • Enforcing lock safety during concurrent file writes.
  • Reading responses using low-overhead exponential backoff polling.
  • Resolving OS-specific lock issues, especially Windows file access conflicts (using a "graveyard" folder to safely offload locked files).

For detailed technical insights on how the underlying transport manages writes, polling timeouts, and cleanup safety, refer to the rpc_client documentation.

Troubleshooting and Hotkey Conflicts

As described in the module's README.md, command execution relies on specific keyboard events to alert the hosting application. If you encounter Exception: Timed out waiting for response errors, ensure the following hotkeys are not mapped or blocked by other background software:

  • Mac: cmd-shift-f17
  • Windows & Linux (non-VSCode): ctrl-shift-f17
  • Linux (VSCode-specific): ctrl-shift-alt-p