Skip to content

i3wm

This directory contains the Talon configuration and supporting Python implementation required to control the i3 window manager (i3wm) via voice.

By default, these configurations are restricted to Linux systems and will only activate when the user explicitly enables the user.i3wm tag (e.g., by adding tag(): user.i3wm to their user settings).

How It Works

The integration is built on three core components that coordinate voice inputs, environment configurations, and IPC calls to the window manager:

  • i3wm.py — Defines the core settings, overrides default Talon window-switching behaviors, and makes system calls to the i3-msg utility.
  • i3wm.talon — Maps spoken commands to custom and standard Talon actions.
  • i3wm_resize_dir.talon-list — Provides a list of direction options used to scope the capture parameters during window resizing.

Technical Architecture and Key Concepts

1. Interfacing with i3wm via IPC

Because i3wm is managed via its own IPC interface, i3wm.py makes extensive use of Python's subprocess module to run i3-msg commands (e.g., i3-msg --quiet <command>).

The helper action user.i3msg() handles standard, synchronous command execution, while i3msg_nocheck() is utilized for operations where we do not need to block on exit codes (such as sequential window resizing loops).

2. Overriding Window Focus Mechanics

Standard desktop environment focus behaviors do not map cleanly to i3wm. In traditional window environments, an application requesting focus can cause i3wm to flag the target window as "urgent" rather than immediately shifting the active workspace focus.

To overcome this, i3wm.py overrides the default context actions for window and application switching:

  • user.switcher_focus_window(window)
  • user.switcher_focus(name)
  • user.switcher_focus_app(app)

Instead of relying on the UI toolkit's focus mechanisms, these overrides extract the unique system window ID (window.id) and directly force focus through the i3wm IPC using:

i3-msg "[id=<window_id>] focus"

This guarantees that helper utilities (such as the Talon Draft Editor) can reliably force-focus windows across different virtual workspaces.

3. Settings and Configuration

The implementation defines two configurable settings to accommodate custom i3wm configuration files:

  • user.i3_terminal_key (Default: super-enter): Key combination used to spawn a terminal emulator.
  • user.i3_launch_key (Default: super-d): Key combination used to bring up the application launcher (e.g., dmenu or rofi).

Command Interface

i3wm.talon maps user voice commands to layout adjustments, workspace switches, container movement, and utility management.

Window Navigation and Layouts

Users can manage window layouts and split orientations with commands like:

  • "window left" / "window right" — Move focus directionally.
  • "window horizontal" / "window vertical" — Pre-split containers.
  • "window stacking" / "window tabbed" — Alter container presentation layout.
  • "toggle floating" / "focus floating" — Manage floating windows.

Window Sizing

Window sizing logic leverages the direction vocabulary defined in i3wm_resize_dir.talon-list. Commands like "window grow" or "window shrink" invoke user.i3wm_resize_window(), which loops over directions (such as width, height, left, right) and commands i3 to increment/decrement dimensions in blocks of 10 pixels.

Scratchpad and Launcher Integration

The configuration provides custom scratchpad management, allowing developers to quickly tuck windows out of the way or pull them back into focus:

  • "make scratch" — Sends the active window to the i3 scratchpad.
  • "show scratch" / "hide scratch" — Toggles the scratchpad container overlay.
  • "new scratch shell" — Launches a terminal, sleeps briefly to let the window map, and immediately sends it to the scratchpad as a slide-over terminal.