crashdx

# crashdx

[![CI](https://github.com/r00tify/crashdx/actions/workflows/ci.yml/badge.svg)](https://github.com/r00tify/crashdx/actions/workflows/ci.yml)

A crash **diagnosis** engine for Apple platforms: parses `.ips` crash reports, symbolicates
them against dSYMs, and produces an evidence-cited, ranked diagnosis, not just a
symbolicated stack trace.

Ships as a dependency-free Swift library (`CrashDXCore` imports only Foundation), a CLI
(`crashdx`), and an MCP server (`crashdx-mcp`), so agents and humans use the same engine.

## Why

A symbolicated stack trace tells you where a process died, not why. crashdx adds a second
stage on top of symbolication: deterministic, rule-based evidence extraction (watchdog
budgets, jetsam tables, register and memory state, `lastExceptionBacktrace`/`asi`) feeding
a ranked set of competing hypotheses, each citing the specific facts that support it and
pointing back into the raw report.

Two properties it holds onto deliberately:

- **Every claim is traceable.** Facts carry a JSON path into the original report, so any
  verdict can be checked rather than trusted.
- **It says "inconclusive" when it is.** A verdict requires the leading hypothesis to be
  strongly supported *and* clearly ahead of the runner-up; otherwise you get the ranked
  candidates and what would settle it.

There are no LLM calls in the engine: it produces verifiable facts and ranked
interpretations, and leaves the narrative to whatever consumes them. See
[docs/DESIGN.md](docs/DESIGN.md) for the full architecture.

## Requirements

- macOS 14+
- **Swift 6.2+** toolchain. The manifest itself is `swift-tools-version:6.0`, but the MCP
  server's pinned dependencies declare up to `6.2`, and SwiftPM resolves the whole
  package graph, so 6.2 is the real floor for every target, including `CrashDXCore`.
- **Xcode** (not just Command Line Tools): symbolication drives Apple's
  `CrashSymbolicator.py` from Xcode's `CoreSymbolicationDT.framework`, located via
  `xcode-select -p`. Without it, crashdx falls back to `atos`, which resolves fewer
  source locations. Parsing and diagnosis work either way.
- `/usr/bin/python3` and `/usr/bin/dwarfdump` (both provided by Xcode's command line
  tools), used to run `CrashSymbolicator.py` and to verify dSYM UUIDs.

### Supported reports

Honest scope, because a crash diagnoser that quietly does worse on your platform is worse
than one that says so:

- **arm64 crash reports are fully supported**: Apple silicon Macs, iOS/iPadOS/watchOS/
  tvOS devices, and Simulators hosted on Apple silicon. This is what the fixture corpus
  covers.
- **x86_64 reports** (Intel Macs, Rosetta-translated processes, Simulators on Intel) parse
  and symbolicate, and the engine reads `x86_THREAD_STATE` registers and the 4 KB page
  size. There is no Intel fixture in the corpus, so this path is reasoned-about rather
  than exercised against a real report.
- **Only crash reports** (`bug_type` 309/109). Jetsam event reports (`JetsamEvent-*.ips`,
  `bug_type` 298) and hang/stackshot reports (`bug_type` 288) use a different payload
  shape with no threads or exception object; crashdx parses them without error but has
  no facts to work from and will report inconclusive.

### Privacy

crashdx runs entirely on your machine and **makes no network calls of any kind**. Crash
reports, dSYMs, and everything derived from them stay local. This matters because `.ips`
files contain identifying data (`crashReporterKey`, boot/sleep-wake UUIDs, device model,
and usernames in paths), so if you attach one to a bug report, scrub it first.

## Install / build

```sh
git clone https://github.com/r00tify/crashdx.git
cd crashdx
swift build -c release
```

The binaries land in `.build/release/`. To put them on your `PATH`:

```sh
sudo mkdir -p /usr/local/bin
sudo cp .build/release/crashdx .build/release/crashdx-mcp /usr/local/bin/
```

(Or copy them somewhere you already own, such as `~/.local/bin`.)

## Usage

Crash reports live in `~/Library/Logs/DiagnosticReports/` on macOS (or Console.app →
Crash Reports); on iOS, Settings → Privacy & Security → Analytics & Improvements →
Analytics Data, and Xcode's Organizer for TestFlight/App Store crashes.

```sh
crashdx analyze report.ips                           # human-readable summary + diagnosis
crashdx analyze report.ips --json                    # structured AnalysisReport JSON
crashdx analyze report.ips --json --tier full        # ...with every thread included
crashdx symbolicate report.ips --dsym path/to.dSYM   # just symbolicate, print enriched .ips
crashdx --version
```

`--dsym` accepts a `.dSYM` bundle, an `.xcarchive`, or a directory to search recursively
(repeatable), and `--no-spotlight` skips Spotlight-based discovery while `--no-archives`
skips Xcode's archive directory. Run `crashdx <subcommand> --help` for the full option
list. Note that `--json` and `--tier` apply to `analyze` only; `symbolicate` always emits
a complete `.ips`.

Both subcommands search Spotlight and Xcode's archives for a matching dSYM automatically.
For foreign reports (user-submitted, TestFlight, CI artifacts) pass the build's dSYM
explicitly with `--dsym`.

Strings taken from the report (process name, symbols, paths, exception text) are escaped
before the human-readable summary prints them: C0 controls, DEL, and bidi overrides
render as `\x0A` / `\u{202E}` instead of being emitted, so a crafted report cannot forge
a `DIAGNOSIS:` line or repaint your terminal. `--json` and `symbolicate` emit the
report's strings verbatim; treat their output as data, not as terminal text.

A dSYM from a *different* build is refused rather than used: a stale dSYM produces
confidently wrong symbols, which is worse than none. That case is reported as
`uuid_mismatch` (with the offending path in `reason`), kept distinct from `no_dsym`
because the fix is different: find the archive matching the report's build UUID, rather
than go looking for a file you may already have.

### Report tiers

`--tier` controls how much of the report is emitted; it never changes the diagnosis,
which is always computed from the full report:

| Tier | Contents |
|---|---|
| `summary` (default) | Faulting thread (capped at 15 frames), `lastExceptionBacktrace`, and the diagnosis verdict + ranked hypotheses |
| `standard` | Lifts the frame cap, and adds the binary images, other threads that contain app frames, and `factsConsidered` (the evidence behind each hypothesis) |
| `full` | Adds every remaining thread, including those with no app frames |

### Exit codes

`0` success · `64` usage error · `65` the input could not be parsed as an `.ips` report,
or symbolication failed · `66` file not found or unreadable.

Diagnostics go to stderr; stdout carries report output (and `--help`/`--version`).

### MCP server

`crashdx-mcp` exposes the same pipeline over stdio (newline-delimited JSON-RPC) as the
`crashdx_analyze` and `crashdx_symbolicate` tools. With Claude Code:

```sh
claude mcp add crashdx /usr/local/bin/crashdx-mcp
```

A matching `crash-triage` Agent Skill ships in `.claude/skills/crash-triage/`, covering
how to read the diagnosis and the interpretation pitfalls specific to each crash family.

### As a library

Add `https://github.com/r00tify/crashdx.git` to your `Package.swift`, depend on the
`CrashDXCore` product, and call
`AnalyzePipeline.analyze(path:tier:dsymPaths:useSpotlight:searchArchives:)`, the same
entry point both binaries use.

`CrashDXCore` imports nothing but `Foundation`, but two limitations are worth knowing
before you depend on it:

- **It is macOS-only.** Symbolication shells out to `atos`/`dwarfdump`/`mdfind` through
  `Foundation.Process`, which does not exist on iOS. Adding this package to an iOS target
  fails during dependency resolution, before anything compiles.
- SwiftPM resolves the whole package graph rather than a single product, so depending on
  this package pins the MCP server's dependencies (swift-sdk and its transitive NIO/
  collections/log packages) in your `Package.resolved` even if you never import them.

`AnalysisReport` and the diagnosis model are `Sendable`, so analysing a directory of
reports concurrently works as you would expect.

## Project layout

```
Sources/CrashDXCore/   Parsing, symbolication, and the diagnosis engine (imports only Foundation)
Sources/crashdx/       CLI
Sources/crashdx-mcp/   MCP server (depends on swift-sdk)
Tests/                 Unit + integration tests, golden snapshots, crash fixtures
corpus/                Ground-truth crash fixtures and their verified findings
docs/DESIGN.md         Diagnosis engine architecture
Scripts/               Fixture scrubbing and the CI privacy guard
```

## Testing

```sh
swift test
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). One rule matters more than the rest: **crash
reports and dSYMs must be scrubbed before they are committed**. They carry device
identifiers and your username. `Scripts/scrub-fixture.py` handles `.ips` files and
`Scripts/check-fixtures-scrubbed.sh` (also run in CI) will tell you if anything slipped
through.

## Security and privacy

crashdx makes no network calls; nothing leaves your machine. See [SECURITY.md](SECURITY.md)
for vulnerability reporting and for what a `.ips` file actually contains before you share
one.

## License

MIT. See [LICENSE](LICENSE).