Add automatic Qtile grouping and usage telemetry #10

Merged

lost-rob0t merged 14 commits from qtile-features into qtile-work

2026-07-19 19:45:25 +00:00

lost-rob0t commented

2026-07-17 23:11:18 +00:00

(Migrated from github.com)

Summary

Adds a clickable AUTO control to the Qtile top bar and structured usage telemetry for later workflow optimization.

The button always displays AUTO in black text. Its background indicates state:

green: automatic group management enabled
pink/red: automatic group management disabled

Automatic group mode

When enabled, the mode:

immediately organizes existing recognized windows into their configured groups
routes newly managed windows to their configured groups
re-enforces routing when recognized windows are moved into another normal group
switches groups with more than three windows to the max layout
restores each group’s configured default layout when its window count drops to three or fewer
ignores scratchpad groups

When disabled, automatic routing and layout enforcement stop without moving windows back, allowing normal manual window movement and layout selection.

Usage telemetry

Qtile writes structured JSONL events to:

~/.local/state/qtile/telemetry.jsonl

The telemetry records:

the configured keymap at session start
actual keybind and key-chord usage
managed, focused, moved, routed, floating, and closed windows
window title, WM_CLASS, PID, geometry, group, screen, and layout
group additions and removals
layout changes and window counts
group and screen changes
AUTO mode changes
startup, restart, and shutdown events

Logs rotate at 25 MiB with four retained backups.

A summarizer produces compact JSON suitable for LLM analysis:

python ~/.config/qtile/scripts/qtile-telemetry-summary.py > ~/qtile-telemetry-report.json

The report ranks keybind usage, focused and managed applications, unmatched applications, group destinations, layout changes, automatic routes, and group or screen usage.

The raw log includes window titles, so private browser page, document, or terminal names may appear and should be reviewed before sharing.

Implementation

centralizes application mappings in auto_group_routes
adds safe WM_CLASS matching through routed_group
synchronizes the AUTO state across both bars
records explicit automatic routing decisions
instruments all configured Qtile key bindings without replacing their existing commands
isolates telemetry hooks in qtile_telemetry.py
adds scripts/qtile-telemetry-summary.py
documents configuration and privacy behavior in qtile.org

Validation

python -m py_compile config.py qtile_telemetry.py scripts/qtile-telemetry-summary.py
stubbed Qtile configuration import
tested existing-window and new-window routing
tested switching to max at four windows
tested restoring the default layout at three windows
tested synchronized AUTO widgets on both bars
tested black AUTO text in both states
tested key instrumentation and JSONL event creation
tested telemetry summarizer output

qtile check -c config.py still needs to be run on a system with Qtile installed.

## Summary Adds a clickable `AUTO` control to the Qtile top bar and structured usage telemetry for later workflow optimization. The button always displays `AUTO` in black text. Its background indicates state: - green: automatic group management enabled - pink/red: automatic group management disabled ## Automatic group mode When enabled, the mode: - immediately organizes existing recognized windows into their configured groups - routes newly managed windows to their configured groups - re-enforces routing when recognized windows are moved into another normal group - switches groups with more than three windows to the `max` layout - restores each group’s configured default layout when its window count drops to three or fewer - ignores scratchpad groups When disabled, automatic routing and layout enforcement stop without moving windows back, allowing normal manual window movement and layout selection. ## Usage telemetry Qtile writes structured JSONL events to: ```text ~/.local/state/qtile/telemetry.jsonl ``` The telemetry records: - the configured keymap at session start - actual keybind and key-chord usage - managed, focused, moved, routed, floating, and closed windows - window title, WM_CLASS, PID, geometry, group, screen, and layout - group additions and removals - layout changes and window counts - group and screen changes - AUTO mode changes - startup, restart, and shutdown events Logs rotate at 25 MiB with four retained backups. A summarizer produces compact JSON suitable for LLM analysis: ```bash python ~/.config/qtile/scripts/qtile-telemetry-summary.py > ~/qtile-telemetry-report.json ``` The report ranks keybind usage, focused and managed applications, unmatched applications, group destinations, layout changes, automatic routes, and group or screen usage. The raw log includes window titles, so private browser page, document, or terminal names may appear and should be reviewed before sharing. ## Implementation - centralizes application mappings in `auto_group_routes` - adds safe WM_CLASS matching through `routed_group` - synchronizes the AUTO state across both bars - records explicit automatic routing decisions - instruments all configured Qtile key bindings without replacing their existing commands - isolates telemetry hooks in `qtile_telemetry.py` - adds `scripts/qtile-telemetry-summary.py` - documents configuration and privacy behavior in `qtile.org` ## Validation - `python -m py_compile config.py qtile_telemetry.py scripts/qtile-telemetry-summary.py` - stubbed Qtile configuration import - tested existing-window and new-window routing - tested switching to `max` at four windows - tested restoring the default layout at three windows - tested synchronized AUTO widgets on both bars - tested black AUTO text in both states - tested key instrumentation and JSONL event creation - tested telemetry summarizer output `qtile check -c config.py` still needs to be run on a system with Qtile installed.