# Qtile Edit

> qtile, literate-config, tangle, configuration, tests

- Skill: `lost-rob0t/qtile-edit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lost-rob0t/qtile-edit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lost-rob0t/qtile-edit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lost-rob0t (https://skillmd.com/u/lost-rob0t)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lost-rob0t/qtile-edit

---


# Edit Qtile safely

## Goal

Change Qtile configuration at its durable source, regenerate owned outputs, and
verify syntax and behavior before reloading the live window manager.

## Workflow

1. Discover the root with `QTILE_CONFIG_ROOT`, defaulting to
   `$HOME/.config/qtile`. Read its local instructions before editing.
2. Classify the target before changing it:
   - `qtile-ai.org` is the canonical source for `config.py`.
   - `qtile-openrouter.org` is the canonical source for `qtile_openrouter.py`.
   - Standalone Python, Elisp, and shell helpers are edited at their own source.
   - Never make a lasting change only in a generated `config.py` or
     `qtile_openrouter.py`.
3. Search the source and nearby tests for the behavior. Preserve existing
   ownership, keybinding, event-loop, and display/server conventions.
4. Edit the canonical source. For an Org source, tangle from that file:

   ```sh
   emacs --batch --quick qtile-ai.org --funcall org-babel-tangle
   emacs --batch --quick qtile-openrouter.org --funcall org-babel-tangle
   ```

   Tangle only the source that changed when possible.
5. Verify generated parity and syntax from the configuration root:

   ```sh
   python -m py_compile config.py qtile_telemetry.py
   qtile check -c config.py
   ```

6. Run the narrowest relevant tests, then the full Qtile suite when practical.
   Tests must check behavior and source/generated parity, not only file
   existence.
7. Invoke `qtile-reload` only after validation passes, then invoke
   `qtile-confirm` for any visual or runtime-facing change.

## Rules

- Keep keybindings documented in their canonical literate source.
- Do not hardcode a monitor, network interface, display, username, or hostname
  when runtime discovery or an existing configuration abstraction is available.
- Do not block Qtile’s event loop with Git, network, or long-running commands.
- Do not overwrite unrelated work in a dirty tree.
- Do not commit or merge unless the user explicitly requests it.