Hang Diagnostics

Systematic diagnosis and resolution of app hangs. A hang occurs when the main thread is blocked for more than 1 second, making the app unresponsive to user input.

Red Flags — Check This Skill When

Symptom	This Skill Applies
App freezes briefly during use	Yes — likely hang
UI doesn't respond to touches	Yes — main thread blocked
"App not responding" system dialog	Yes — severe hang
Xcode Organizer shows hang diagnostics	Yes — field hang reports
MetricKit MXHangDiagnostic received	Yes — aggregated hang data
Animations stutter or skip	Maybe — could be hitch, not hang
App feels slow but responsive	No — performance issue, not hang

What Is a Hang

A hang is when the main runloop cannot process events for more than 1 second. The user taps, but nothing happens.

User taps → Main thread busy/blocked → Event queued → 1+ second delay → HANG

Key distinction: The main thread handles ALL user input. If it's busy or blocked, the entire UI freezes.

Hang vs Hitch vs Lag

Issue	Duration	User Experience	Tool
Hang	>1 second	App frozen, unresponsive	Time Profiler, System Trace
Hitch	1-3 frames (16-50ms)	Animation stutters	Animation Hitches instrument
Lag	100-500ms	Feels slow but responsive	Time Profiler

This skill covers hangs. For hitches, see axiom-swiftui-performance. For general lag, see axiom-performance-profiling.

The Two Causes of Hangs

Every hang has one of two root causes:

1. Main Thread Busy

The main thread is doing work instead of processing events.

Subcategories:

Type	Example	Fix
Proactive work	Pre-computing data user hasn't requested	Lazy initialization, compute on demand
Irrelevant work	Processing all notifications, not just relevant ones	Filter notifications, targeted observers
Suboptimal API	Using blocking API when async exists	Switch to async API

2. Main Thread Blocked

The main thread is waiting for something else.

Subcategories:

Type	Example	Fix
Synchronous IPC	Calling system service synchronously	Use async API variant
File I/O	Data(contentsOf:) on main thread	Move to background queue
Network	Synchronous URL request	Use URLSession async
Lock contention	Waiting for lock held by background thread	Reduce critical section, use actors
Semaphore/dispatch_sync	Blocking on background work	Restructure to async completion

Decision Tree — Diagnosing Hangs

START: App hangs reported
  │
  ├─→ Do you have hang diagnostics from Organizer or MetricKit?
  │     │
  │     ├─→ YES: Examine stack trace
  │     │     │
  │     │     ├─→ Stack shows your code running
  │     │     │     → BUSY: Main thread doing work
  │     │     │     → Profile with Time Profiler
  │     │     │
  │     │     └─→ Stack shows waiting (semaphore, lock, dispatch_sync)
  │     │           → BLOCKED: Main thread waiting
  │     │           → Profile with System Trace
  │     │
  │     └─→ NO: Can you reproduce?
  │           │
  │           ├─→ YES: Profile with Time Profiler first
  │           │     │
  │           │     ├─→ High CPU on main thread
  │           │     │     → BUSY: Optimize the work
  │           │     │
  │           │     └─→ Low CPU, thread blocked
  │           │           → Use System Trace to find what's blocking
  │           │
  │           └─→ NO: Enable MetricKit in app
  │                 → Wait for field reports
  │                 → Check Organizer > Hangs

Tool Selection

Scenario	Primary Tool	Why
Reproduces locally	Time Profiler	See exactly what main thread is doing
Blocked thread suspected	System Trace	Shows thread state, lock contention
Field reports only	Xcode Organizer	Aggregated hang diagnostics
Want in-app data	MetricKit	MXHangDiagnostic with call stacks
Need precise timing	System Trace	Nanosecond-level thread analysis

Time Profiler Workflow for Hangs

1. Launch Instruments → Select Time Profiler template
2. Record during hang → Reproduce the freeze
3. Stop recording → Find the hang period in timeline
4. Select hang region → Drag to select frozen timespan
5. Examine call tree → Look for main thread work

What to look for:

• Functions with high "Self Time" on main thread
• Unexpectedly deep call stacks
• System calls that shouldn't be on main thread

System Trace Workflow for Blocked Hangs

1. Launch Instruments → Select System Trace template
2. Record during hang → Capture thread states
3. Find main thread → Filter to main thread
4. Look for red/orange → Blocked states
5. Examine blocking reason → Lock, semaphore, IPC

Thread states:

• Running (blue): Executing code
• Preempted (orange): Runnable but not scheduled
• Blocked (red): Waiting for resource

Common Hang Patterns and Fixes

Pattern 1: Synchronous File I/O

Before (hangs):

// Main thread blocks on file read
func loadUserData() {
    let data = try! Data(contentsOf: largeFileURL)  // BLOCKS
    processData(data)
}

After (async):

func loadUserData() {
    Task.detached {
        let data = try Data(contentsOf: largeFileURL)
        await MainActor.run {
            self.processData(data)
        }
    }
}

Pattern 2: Unfiltered Notification Observer

Before (processes all):

NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleChange),
    name: .NSManagedObjectContextObjectsDidChange,
    object: nil  // Receives ALL contexts
)

After (filtered):

NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleChange),
    name: .NSManagedObjectContextObjectsDidChange,
    object: relevantContext  // Only this context
)

Pattern 3: Expensive Formatter Creation

Before (creates each time):

func formatDate(_ date: Date) -> String {
    let formatter = DateFormatter()  // EXPENSIVE
    formatter.dateStyle = .medium
    return formatter.string(from: date)
}

After (cached):

private static let dateFormatter: DateFormatter = {
    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    return formatter
}()

func formatDate(_ date: Date) -> String {
    Self.dateFormatter.string(from: date)
}

Pattern 4: dispatch_sync to Main Thread

Before (deadlock risk):

// From background thread
DispatchQueue.main.sync {  // BLOCKS if main is blocked
    updateUI()
}

After (async):

DispatchQueue.main.async {
    self.updateUI()
}

Pattern 5: Semaphore for Async Result

Before (blocks main thread):

func fetchDataSync() -> Data {
    let semaphore = DispatchSemaphore(value: 0)
    var result: Data?

    URLSession.shared.dataTask(with: url) { data, _, _ in
        result = data
        semaphore.signal()
    }.resume()

    semaphore.wait()  // BLOCKS MAIN THREAD
    return result!
}

After (async/await):

func fetchData() async throws -> Data {
    let (data, _) = try await URLSession.shared.data(from: url)
    return data
}

Pattern 6: Lock Contention

Before (shared lock):

class DataManager {
    private let lock = NSLock()
    private var cache: [String: Data] = [:]

    func getData(for key: String) -> 
how to use axiom-hang-diagnostics
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-hang-diagnostics on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-hang-diagnostics
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-hang-diagnosticscopy
The skills CLI fetches axiom-hang-diagnostics from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-hang-diagnostics
Reload or restart Cursor to activate axiom-hang-diagnostics. Access the skill through slash commands (e.g., /axiom-hang-diagnostics) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?