# Qtile Debug

> qtile, diagnostics, logs, IPC, crash-analysis

- Skill: `lost-rob0t/qtile-debug` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lost-rob0t/qtile-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lost-rob0t/qtile-debug/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-debug

---


# Debug Qtile

## Goal

Separate source/import failures, Qtile IPC failures, service failures, and visual
regressions using reproducible evidence before proposing an edit.

## Workflow

1. Discover `QTILE_CONFIG_ROOT`, defaulting to `$HOME/.config/qtile`, and create
   a temporary diagnostic directory.
2. Collect independent evidence. Preserve failures instead of stopping at the
   first command:

   ```sh
   out="$(mktemp -d "${TMPDIR:-/tmp}/qtile-debug.XXXXXX")"
   (cd "$QTILE_CONFIG_ROOT" && python -m py_compile config.py) >"$out/compile" 2>&1 || true
   qtile check -c "$QTILE_CONFIG_ROOT/config.py" >"$out/check" 2>&1 || true
   qtile --version >"$out/version" 2>&1 || true
   systemctl --user status qtile.service --no-pager >"$out/service" 2>&1 || true
   journalctl --user -u qtile.service -b -n 200 --no-pager >"$out/journal" 2>&1 || true
   qtile cmd-obj -o root -f info >"$out/root-info" 2>&1 || true
   qtile cmd-obj -o screen 0 -f info >"$out/screen-0" 2>&1 || true
   xrandr --query >"$out/outputs" 2>&1 || true
   ```

3. Classify the failure:
   - compile/check output means source, dependency, or generated-file drift;
   - service/journal output means startup or runtime failure;
   - IPC output means socket, process, or object-path failure;
   - clean diagnostics plus a wrong screenshot means a visual regression.
4. For a visual regression, invoke `qtile-confirm`. It must take and inspect a
   screenshot; do not infer layout from widget configuration or coordinates.
5. For a source failure, invoke `qtile-edit`; for a validated runtime change,
   invoke `qtile-reload`. Re-run the failing evidence after each change.

## Isolated X11 reproduction

Use a nested Xorg server when a visual or Emacs-frame bug could disturb the
active desktop. Requires `Xephyr`, Qtile's X11 backend, and `scrot` for visual
evidence. Follow `references/isolated-xorg.md` for the exact lifecycle:

1. Use an unused display, temporary state directory, and unique Emacs server.
2. Start Xephyr and Qtile with `--no-spawn`, an explicit socket, and the
   isolated `DISPLAY`.
3. Run every IPC/client/screenshot command with that same `DISPLAY` and socket.
4. Inspect the nested screenshot with `qtile-confirm`, then stop only the
   recorded Qtile/Xephyr/Emacs PIDs.

A nested session is test isolation, not proof by itself; retain only the
minimum screenshot and exact window geometry needed for the investigation.

## Rules

- Prefer the smallest reproducer and quote the exact failing command/output.
- Do not restart Qtile, delete caches, or rewrite generated files as a first
  response.
- Treat telemetry JSONL, journal output, screenshots, and window titles as
  potentially private. Redact before sharing and retain only the minimum needed.
- Do not declare a visual issue fixed without a fresh focused screenshot.