ghostty-crash-triage

name: ghostty-crash-triage description: Triage Ghostty macOS crashes by extracting .ghosttycrash envelopes, matching minidumps to dSYM debug IDs, symbolicating with lldb/atos, and writing a dated bug+crash report archive entry. Use when debugging Ghostty renderer crashes, OSC8 hover issues, or any panic/index-out-of-bounds reports captured in ~/.local/state/ghostty/crash.

Ghostty Crash Triage

Overview

Extract a Sentry envelope from ~/.local/state/ghostty/crash, match its debug ID to a dSYM, symbolicate the minidump, and write a minimal bug report with evidence in the repo archive.

Quick Start

Run the one-command triage:

python .claude/skills/ghostty-crash-triage/scripts/triage.py

This will:

1. Select the newest crash file
2. Extract the minidump and event metadata
3. Search for a matching dSYM
4. Symbolicate with lldb (or fall back to atos if dSYM is unavailable)
5. Generate a REPORT.md skeleton

Options

# Triage a specific crash file
python scripts/triage.py ~/.local/state/ghostty/crash/<id>.ghosttycrash

# Specify output directory
python scripts/triage.py --out-dir bug-crash-reports/my-issue

# Add extra dSYM search paths
python scripts/triage.py --dsym-search ~/my-dsyms

Output Files

After running triage, the output directory contains:

dSYM Archive Strategy

The Problem

dSYM files are required for symbolication but are lost when the app is rebuilt. If you rebuild Ghostty after a crash, the new dSYM won't match the crash's debug_id.

Recommended Solution

Archive dSYMs by debug_id in ~/.ghostty-dsyms/:

~/.ghostty-dsyms/
├── 02F9811F-0F22-3C7B-BC89-79A31322DB2B/
│   └── Ghostty.app.dSYM/
├── BD9D9D6C-F0AB-318A-90A2-3192BFC87875/
│   └── Ghostty.app.dSYM/
└── ...

After building a release, archive the dSYM:

# Get the debug_id from the dSYM
UUID=$(dwarfdump --uuid macos/build/ReleaseLocal/Ghostty.app.dSYM | grep arm64 | awk '{print $2}')

# Archive it
mkdir -p ~/.ghostty-dsyms/$UUID
cp -r macos/build/ReleaseLocal/Ghostty.app.dSYM ~/.ghostty-dsyms/$UUID/

The triage script automatically searches ~/.ghostty-dsyms/ for matching dSYMs.

Search Order

The triage script searches these locations (in order):

1. Extra paths via --dsym-search
2. ~/.ghostty-dsyms/ (archived dSYMs)
3. macos/build/ReleaseLocal/ (local build)
4. /Applications/Ghostty.app/ (installed app)

Modify scripts/config.json to customize the search paths.

Manual Workflow

For advanced use, the individual scripts can be run manually:

1) Extract the envelope

python scripts/extract_sentry_envelope.py \
  ~/.local/state/ghostty/crash/<id>.ghosttycrash \
  bug-crash-reports/<YYYY-MM-DD>

2) Match debug_id to a dSYM

Read ghostty_image.debug_id from event_summary.json and compare:

dwarfdump --uuid macos/build/ReleaseLocal/Ghostty.app.dSYM

3) Symbolicate with lldb

scripts/lldb_bt.sh \
  bug-crash-reports/<YYYY-MM-DD>/<minidump>.dmp \
  /Applications/Ghostty.app/Contents/MacOS/ghostty \
  macos/build/ReleaseLocal \
  bug-crash-reports/<YYYY-MM-DD>/lldb_bt.txt

4) Fallback with atos (if no matching dSYM)

# Get load address from event_summary.json (image_addr field)
atos -o /path/to/ghostty -arch arm64 -l 0x100eec000 \
  0x00000001015b5d38 0x00000001015b59f8 ...

Scripts

Configuration

Edit scripts/config.json:

{
  "dsym_search_paths": [
    "~/.ghostty-dsyms",
    "macos/build/ReleaseLocal",
    "/Applications/Ghostty.app/Contents/MacOS"
  ],
  "crash_dir": "~/.local/state/ghostty/crash",
  "output_root": "bug-crash-reports",
  "unsymbolicated_threshold": 0.5
}

• dsym_search_paths: Directories to search for dSYMs and binaries
• crash_dir: Where Ghostty writes crash files
• output_root: Base directory for triage output
• unsymbolicated_threshold: Ratio of unsymbolicated frames to trigger atos fallback

Creating GitHub Discussions

Ghostty uses GitHub Discussions as the first line of reporting for bugs and crashes. After triaging a crash, create a DISCUSSION.md file in the output directory following the Issue Triage template.

Discussion Template

The discussion should include:

See bug-crash-reports/2025-12-25/DISCUSSION.md for an example.

Creating via GitHub CLI

After writing DISCUSSION.md, create the discussion using the GraphQL API:

# Read the discussion content
BODY=$(cat bug-crash-reports/<date>/DISCUSSION.md)
TITLE="Search thread crash: integer underflow in CircBuf.getPtrSlice"

# Create the discussion
gh api graphql -f query='
mutation($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
  createDiscussion(input: {
    repositoryId: $repositoryId
    categoryId: $categoryId
    title: $title
    body: $body
  }) {
    discussion {
      url
    }
  }
}' \
  -f repositoryId="R_kgDOHFhdAg" \
  -f categoryId="DIC_kwDOHFhdAs4Cmv-L" \
  -f title="$TITLE" \
  -f body="$BODY"

Reference IDs

Listing Categories

To discover category IDs:

gh api graphql -f query='{
  repository(owner: "ghostty-org", name: "ghostty") {
    discussionCategories(first: 10) {
      nodes { id name }
    }
  }
}'