debug-visual

Analyze X11 events to diagnose flicker, focus stealing, and layout thrashing.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/brian-wijaya/dotfiles --skill debug-visual
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-visual
Source: https://github.com/brian-wijaya/dotfiles/tree/main/.claude/skills/debug-visual
Command: npx skills add https://github.com/brian-wijaya/dotfiles --skill debug-visual

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps identify and analyze visual glitches on your desktop by collecting and inspecting X11 events to determine causes such as flicker, focus stealing, or layout thrashing.

Core Features & Use Cases

  • Somatic X11 perception: Tap into the X11 event stream to diagnose flicker, focus changes, ghost windows, and layout issues.
  • Reproducible analysis: Record timestamps and event sequences to correlate user-reported visuals with system behavior.
  • Use Case: When a window flickers continuously, run the debug-visual skill to collect events and present a likely cause with suggested fixes.

Quick Start

Start the diagnostic session by marking the current time with mcp__somatic-temporal__now and prompting the user to reproduce the issue. Then query events via mcp__somatic-x11-bus__get_events and analyze patterns like flicker, focus steal, or ghost windows. Finally, flash a confirmation with mcp__somatic-hud__flash_text.

Frequently Asked Questions about debug-visual

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose X11 window flicker and focus stealing issues?

To diagnose X11 window flicker and focus stealing, this skill analyzes the live X11 event stream and timing data. It correlates user actions with system events to identify the root cause of visual glitches in desktop sessions.

What is the best way to troubleshoot ghost windows and layout thrashing on Linux?

Troubleshooting ghost windows and layout thrashing involves recording timestamps and event sequences to match user-reported visuals with system behavior. This approach captures X11 events to pinpoint discrepancies causing the display errors.

How do I record and analyze X11 events to find what is causing visual glitches?

You record and analyze X11 events by marking the current time, reproducing the issue, and querying the event bus. This captures the exact event sequence and timing data needed to correlate user actions with visual anomalies.

Does this visual issue diagnostic tool work with live desktop sessions?

Yes, this diagnostic process works directly with live desktop sessions. It taps into the active X11 event stream to collect real-time data on flicker, focus changes, and layout issues as they occur on your screen.

What are the limitations of using X11 event analysis for desktop visual issues?

The limitation of X11 event analysis is its dependency on reproducing the issue live during a diagnostic session. It cannot analyze past visual glitches if the event stream was not actively being recorded when the anomaly occurred.

Can I use somatic perception to correlate user actions with system window management events?

Yes, you can use somatic perception to correlate user actions with window management events. It taps into the X11 bus to collect timing data and event sequences, matching user-reported visuals with underlying system behavior.