Skip to content

talon_helpers

This directory contains helper scripts and voice commands designed to simplify debugging, developing, and extending Talon configurations. It provides utilities for inspecting Talon's internal state (registry lists, active tags, modes, scopes, and settings), extracting metadata from focused applications, and automatically scaffolding new application context files.

Metadata Extraction and Debugging

The talon_helpers.py file acts as the primary hub for inspecting and interacting with the Talon runtime. It exposes actions that interact with Talon's core APIs (registry, ui, scope, speech_system, etc.) to return or print diagnostic information.

Its features include:

  • Clipboard Utilities: Formatting and copying current application details (like bundle identifiers on macOS, executable names on Windows, window titles, and classes) to the clipboard. The actions talon_add_context_clipboard_python and talon_add_context_clipboard automatically format this data as valid python/talon syntax block matches.
  • State Inspection: Debugging actions that dump active modes, registry tags, lists, scope values, or settings to the console log, or copy registry lists to the clipboard using Python's pprint module.
  • Simulation & Testing: Running the simulated speech engine using speech_system._sim(phrase) to preview how Talon would evaluate a specific utterance without actually executing the underlying actions.

Automated Application Scaffolding

The create_app_context.py file streamlines the process of adding support for a new application. When invoked, it automatically inspects the currently focused application and creates a standardized directory structure and files in the repository's /apps directory:

  1. Context Detection: It parses the active application's name, bundle ID (macOS), or executable name (Windows), formatting it into a safe snake-case string.
  2. Boilerplate Generation: It writes a Python context file (.py) containing the template Module and Context match rules, and a corresponding .talon context file ready for custom voice commands.
  3. Project Organization: If successful, it opens the newly created directory in the system's file manager to let the developer start writing commands immediately.

Voice Command Interface

The talon_helpers.talon file maps spoken phrases to the helper actions defined in the Python files, as well as several built-in Talon menu options.

  • System Navigation: Commands like talon open log, talon open rebel (REPL), and talon open debug trigger native Talon menu options.
  • Inspecting Elements: Phrases like talon copy name, talon copy executable, and talon copy class load the focused app's parameters into the system clipboard, making it easy to paste them when manually editing contexts.
  • State Scaffolding: Commands like talon create app context or platform-specific versions (e.g., talon create windows app context) trigger the automatic scaffolding system.
  • Active Debugging: Phrases like talon test last or talon test <phrase> run simulated evaluations of commands, which is extremely useful for figuring out which rules are matching or failing. Commands such as talon debug list {user.talon_lists} print active registry lists directly to the console.