argus-build-diagnostics

tuist's avatarfrom tuist

Diagnose xcodebuild builds using argus. Use this instead of parsing xcodebuild output to avoid filling the context window. Query build errors, warnings, slowest targets, bottlenecks, implicit/redundant dependencies, and dependency graph with linking information for optimization analysis.

⭐33stars🔀2forks📁View on GitHub🕐Updated Dec 13, 2025

When & Why to Use This Skill

Argus Build Diagnostics is a specialized Claude skill designed to streamline the analysis and optimization of Xcode builds. By integrating with the Argus tool, it allows AI agents to query structured build data—such as errors, bottlenecks, and dependency graphs—without the need to parse massive, context-consuming raw xcodebuild logs. This skill is essential for developers looking to improve build performance, manage complex dependencies, and optimize application launch times through data-driven insights.

Use Cases

  • 1. Build Performance Optimization: Identify the slowest targets and execution bottlenecks to significantly reduce compilation times.
  • 2. Dependency Audit & Cleanup: Detect implicit or redundant dependencies to maintain a clean and efficient project architecture.
  • 3. Binary Size & Launch Time Tuning: Analyze linking types (static vs. dynamic) and dependency graphs to optimize app footprint and startup speed.
  • 4. Automated Error Troubleshooting: Quickly extract and summarize specific compilation errors and warnings from complex build traces for faster debugging.
nameargus-build-diagnostics
descriptionDiagnose xcodebuild builds using argus. Use this instead of parsing xcodebuild output to avoid filling the context window. Query build errors, warnings, slowest targets, bottlenecks, implicit/redundant dependencies, and dependency graph with linking information for optimization analysis.

Argus Build Diagnostics

Use argus to analyze Xcode builds instead of parsing raw xcodebuild output.

Installation

mise install github:tuist/argus@0.4.0

Running a Build

Run xcodebuild with argus intercepting the build:

BUILD_TRACE_ID=$(uuidgen)
XCBBUILDSERVICE_PATH=$(which argus) BUILD_TRACE_ID=$BUILD_TRACE_ID xcodebuild build -scheme MyScheme

Querying Build Results

After the build completes, use these commands to analyze results:

# Get build summary
argus trace summary --build $BUILD_TRACE_ID

# Get compilation errors
argus trace errors --build $BUILD_TRACE_ID

# Get slowest targets
argus trace slowest-targets --build $BUILD_TRACE_ID --limit 5

# Get build bottlenecks
argus trace bottlenecks --build $BUILD_TRACE_ID

Dependency Analysis

Detect dependency issues in your project:

# Show what each target imports
argus trace imports --build $BUILD_TRACE_ID

# Find implicit dependencies (imports not declared as dependencies)
argus trace implicit-deps --build $BUILD_TRACE_ID

# Find redundant dependencies (declared but never imported)
argus trace redundant-deps --build $BUILD_TRACE_ID

Add --json flag for structured output.

Dependency Graph and Linking Analysis

Query the build dependency graph with product type and linking information to identify optimization opportunities:

# Get the full dependency graph with linking info
argus trace graph --build $BUILD_TRACE_ID

# Query what a specific target depends on (transitive)
argus trace graph --source MyApp

# Query only direct dependencies
argus trace graph --source MyApp --direct

# Query what depends on a specific target
argus trace graph --sink CoreKit

# Find the path between two targets
argus trace graph --source MyApp --sink CoreKit

# Filter by dependency type
argus trace graph --source MyApp --label package
argus trace graph --source MyApp --label framework

Available Labels

  • target: Project targets
  • package: Swift package dependencies
  • framework: Framework dependencies
  • xcframework: XCFramework dependencies
  • sdk: System SDK frameworks
  • bundle: Bundle dependencies

Output Fields

The graph output includes:

  • name: Target name
  • productType: Xcode product type identifier (e.g., com.apple.product-type.framework)
  • artifactKind: The kind of artifact (e.g., framework, staticLibrary, dynamicLibrary)
  • machOType: Mach-O type (staticlib, mh_dylib, mh_execute)
  • dependencies: Array of linked dependencies with:
    • kind: Link kind (static, dynamic, framework)
    • mode: Link mode
    • isSystem: Whether it's a system dependency

Optimizing Launch Time and Binary Size

Use the graph information combined with linking types to make optimization decisions:

To improve launch time (reduce dylib loading):

  1. Query the graph to find dynamically linked dependencies: argus trace graph --source MyApp --json
  2. Look for dependencies with kind: "dynamic" or kind: "framework"
  3. Consider converting frequently-used internal frameworks from dynamic to static linking
  4. Targets with machOType: "mh_dylib" that are only used by one app are candidates for static linking
  5. Fewer dynamic libraries means fewer dlopen calls at launch

To reduce binary size:

  1. Query the graph to identify statically linked dependencies
  2. Look for large targets with kind: "static" that are shared across multiple apps
  3. Converting these to dynamic frameworks allows code sharing and reduces total install size
  4. Targets with machOType: "staticlib" used by multiple apps benefit from being dynamic

Analysis workflow:

# 1. Get the full graph to understand the dependency structure
argus trace graph --build latest --json > graph.json

# 2. Find all targets that depend on a library you want to optimize
argus trace graph --sink MyLibrary --json

# 3. Check if a target is statically or dynamically linked
argus trace graph --source MyApp --direct --json | jq '.dependencies[] | select(.name == "MyLibrary")'

Decision criteria:

  • If a library is used by only one target: prefer static linking (better launch time)
  • If a library is used by multiple apps/extensions: prefer dynamic linking (smaller total size)
  • For debug builds: prefer dynamic linking (faster incremental builds)
  • For release builds with App Thinning: static linking may be preferred

Listing Previous Builds

# List all tracked projects
argus trace projects

# List builds for a project
argus trace builds --project my-app --limit 10