Skip to content

CLAUDE.md

Latest commit

 

History

History
178 lines (137 loc) · 6.08 KB

CLAUDE.md

File metadata and controls

178 lines (137 loc) · 6.08 KB

CLAUDE.md - XcodeLLMToolchain

This file provides guidance to Claude Code (or any AI assistant) working on this codebase.

CRITICAL: Always Use codemap First

Before making ANY code changes, run codemap to understand the codebase structure:

codemap --deps --json .

Or for specific file context:

codemap --deps --json . | jq '.files[] | select(.path | contains("FileName"))'

This project is built around codemap integration - the LLM tools use it internally. You should too.

Project Overview

XcodeLLMToolchain is an open-source crash and memory analysis toolkit using Apple's Foundation Models (macOS 26+). It runs entirely on-device via the Neural Engine - no cloud, no API keys.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    XCODE LLM TOOLCHAIN                      │
├─────────────────────────────────────────────────────────────┤
│   LLDB Scripts (Python)      CLI (Swift)                    │
│   ├── explain_here           └── xcode-llm                  │
│   ├── crash_explain                    │                    │
│   └── memory_explain                   ▼                    │
│              │              ┌─────────────────────────────┐ │
│              └────────────► │      XcodeLLMCore           │ │
│                             │   @Generable types          │ │
│                             │   Tool calling (codemap)    │ │
│                             └────────────┬────────────────┘ │
│                                          ▼                  │
│                             ┌─────────────────────────────┐ │
│                             │ Apple Foundation Models     │ │
│                             │   On-device • Private       │ │
│                             └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Key Files

Path Purpose
Sources/XcodeLLMCore/XcodeLLMEngine.swift Core LLM engine with structured output
Sources/XcodeLLMCore/CrashExplanation.swift @Generable types and Instructions
Sources/XcodeLLMCore/Tools/CodeMapTool.swift Tool for LLM to query codemap
Sources/XcodeLLMCore/Tools/ReadSourceTool.swift Tool for LLM to read source files
Sources/XcodeLLM/Entry.swift CLI entry point
lldb/plugin.py LLDB command registration
lldb/capture_lib/commands.py crash_explain, memory_explain, explain_here
lldb/capture_lib/analysis.py Crash data extraction from LLDB

Build Commands

# Build everything
swift build

# Build release
swift build -c release

# Run tests
swift test

# Run CLI
.build/debug/xcode-llm --help

# Test with crash suite
.build/debug/swift-crash-suite force_unwrap

Key Technologies

  • Foundation Models (macOS 26): Apple's on-device 3B LLM
  • @Generable macro: Structured output - model must return valid types
  • @Guide descriptions: Tell the model what each field means
  • Tool calling: Model can invoke codemap and read source files
  • Instructions: System prompts for consistent behavior

Code Patterns

Structured Output

@Generable
public struct CrashExplanation {
    @Guide(description: "Category of crash", .anyOf(["null_pointer", "force_unwrap_nil", ...]))
    public var crashType: String
}

Tool Definition

public final class CodeMapTool: Tool {
    public let name = "get_dependencies"
    public let description = "Get dependency info for a file..."

    @Generable
    public struct Arguments {
        @Guide(description: "Path to project root")
        var projectPath: String
    }

    public func call(arguments: Arguments) async throws -> String { ... }
}

LLM Session

let session = LanguageModelSession(
    tools: [ReadSourceTool(), CodeMapTool()],
    instructions: makeCrashInstructions()
)
let response = try await session.respond(
    to: "Analyze crash...",
    generating: CrashExplanation.self
)

LLDB Integration

The Python scripts in lldb/ capture crash context and pipe JSON to the Swift CLI:

LLDB → capture crash data → JSON → xcode-llm CLI → Foundation Models → structured explanation

Common Tasks

Adding a new crash type

  1. Add to CrashType enum in GeneratedCrash.swift
  2. Add to crashType anyOf list in CrashExplanation.swift
  3. Add test case in SwiftCrashSuite/main.swift

Adding a new tool

  1. Create Sources/XcodeLLMCore/Tools/NewTool.swift
  2. Implement Tool protocol with @Generable Arguments
  3. Add to tools array in XcodeLLMEngine.init()

Adding a new LLDB command

  1. Add function in lldb/capture_lib/commands.py
  2. Register in lldb/plugin.py __lldb_init_module

Testing

# Unit tests
swift test

# Manual testing with crash suite
lldb .build/debug/swift-crash-suite -- force_unwrap
(lldb) run
(lldb) crash_explain

# Battle mode (generate crash, then explain)
.build/debug/xcode-llm --battle

Dependencies

  • macOS 26 (Tahoe) or later
  • Apple Silicon Mac
  • Xcode 26+
  • codemap (optional but recommended): brew install jordancoin/tap/codemap

Style Guidelines

  • Keep prompts minimal - let @Guide descriptions do the work
  • One sentence per @Guide description
  • Prefer structured output over free-form text
  • Trim data to fit token limits (Foundation Models has ~32k context)
  • User code frames are more valuable than system frames