agentleFS
ldomaradzkildomaradzki/xcsift/CLAUDE.md

xcsift

CLAUDE.md511 starsChanged 12 months agoMITView on GitHub

xcsift is a Swift command-line tool that parses and formats xcodebuild/SPM output for coding agents. It transforms verbose Xcode build output into token-efficient JSON format optimized for machine readability rather than human consumption. CI lints once, with the swift format of Xcode 27.0 (swift format lint --strict --recursive .). Format with the same toolchain: two swift-format releases can format the same code differently. Homebrew (Recommended): xcsift is in homebrew-core with Autobump enabled — new releases are automatically picked up within…

  • Installs packages
  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

21 rules. About 0 are common, 7 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    IMPORTANT: Always run before committing changes:

    line 23
  2. Very specific:

    Use Conventional Commits: fix:, feat:, docs:, chore:, refactor:, test:.

    line 33
  3. Very specific:

    The signer is the workflow's path: Do not rename release.yml or sign from another workflow file: consumers refuse the release until a …

    line 57
  4. Very specific:

    After plugin installation, xcodebuild and swift build commands are automatically piped through xcsift for structured output.

    line 126
  5. Distinctive:

    When adding new string patterns, add to the appropriate enum rather than using inline literals

    line 314
  6. Very specific:

    Every line passes through processLine exactly once, in order, whichever feed path delivered it.

    line 470
  7. Very specific:

    Look-ahead is pendingRecordedIssueLine, held until the next line arrives

    line 471
  8. Distinctive:

    No flag required - detection is automatic

    line 570
  9. Very specific:

    Test results are indented by four spaces and carry no passed/failed: ✔ <test> (<t> seconds), ✖ <test>, <reason>, ✖ <file>:<line>, <reason> …

    line 578
  10. Very specific:

    Create the file in Tests/XCSiftCoreTests/Fixtures/

    line 616
  11. Very specific:

    Add to Package.swift resources: .copy("Fixtures/your-file.txt")

    line 617
  12. Distinctive:

    No executables in output

    line 669
  13. Distinctive:

    No config returns nil

    line 721
  14. Very specific:

    Test status markers (✔, ✖): indented, Swift Testing, parallel, UI tests, and Tuist's own ✔ Success / ✖ Error

    line 758
  15. Distinctive:

    When modifying code, ensure Linux compatibility:

    line 784
  16. Very specific:

    Use conditional imports: #if canImport(Darwin) / #elseif canImport(Glibc) / #elseif canImport(Musl)

    line 785
  17. Very specific:

    Avoid fputs(..., stderr) — use FileHandle.standardError.write() for Swift 6 concurrency safety

    line 786
  18. Very specific:

    When running on GitHub Actions (GITHUB_ACTIONS=true), xcsift automatically appends workflow annotations after the JSON/TOON output.

    line 945
  19. Very specific:

    If no config file is found, xcsift uses CLI defaults.

    line 998
  20. Very specific:

    IMPORTANT: When modifying public API, CLI flags, or features, you MUST update the corresponding DocC documentation in Sources/xcsift.docc/.

    line 1076
  21. Distinctive:

    For user: Run in a separate terminal:

    line 1090

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

xcsift is a Swift command-line tool that parses and formats xcodebuild/SPM output for coding agents. It transforms verbose Xcode build output into token-efficient JSON format optimized for machine readability rather than human consumption.

Commands

Building

swift build
swift build -c release

Testing

swift test

Formatting

IMPORTANT: Always run before committing changes:

swift format --recursive --in-place .

CI lints once, with the swift format of Xcode 27.0 (swift format lint --strict --recursive .). Format with the same toolchain: two swift-format releases can format the same code differently.

Commit Style

Use Conventional Commits: fix:, feat:, docs:, chore:, refactor:, test:. See git log --oneline for examples.

Installation

Homebrew (Recommended):

brew install xcsift

xcsift is in homebrew-core with Autobump enabled — new releases are automatically picked up within 3 hours.

From Source:

swift build -c release
cp .build/release/xcsift /usr/local/bin/

Releases

A v* tag runs .github/workflows/release.yml: build makes the two archives, release publishes them, then packslip signs a packslip release manifest and publish-packslip attaches it as packslip.sigstore.json. mise's packslip: backend installs from that manifest, and consumers hold every later release to what they accepted:

  • The signer is the workflow's path. Do not rename release.yml or sign from another workflow file: consumers refuse the release until a person approves the new signer.
  • Keep attest: true. A release that drops the build provenance the previous one carried is refused.
  • id-token: write belongs to the packslip job alone, and every action in it stays pinned to a full commit SHA, because any of them can sign as this workflow.
  • Host requirements are written by hand in the job's release.toml: glibc_min follows the Linux build container (swift:6.3-jammy, glibc 2.35), os_min follows .macOS(.v13) in Package.swift. Change them with either, and add an [[artifact]] entry with a new platform. packslip reads libs from the binaries itself.
  • The release must be published, not a draft: the signing job reads it with contents: read.
  • The skill it offers is skills/xcsift at the tagged commit. PluginFilesTests keeps skills/xcsift/SKILL.md equal to SharedTemplates.skillMarkdown, which install-codex and install-cursor write, so edit the template and copy it to the file.

MCP Proxy

xcsift can sit in front of Xcode's own MCP server (Xcode 26+) and sift the build output in its tool results:

# Wrap Xcode's built-in MCP server (Xcode 26+) — the default upstream
xcsift mcp
xcsift mcp -- xcrun mcpbridge

# Any other stdio Xcode MCP server (Tuist-based wrappers, custom servers, …)
xcsift mcp -f toon -w -- /usr/local/bin/my-xcode-mcp serve

# Print a client configuration snippet instead of running
xcsift mcp --print-config

# Register the proxy with Claude Code, and remove it again. `--install` records the flags given
# alongside it; `--uninstall` removes the entry whichever way it was registered.
xcsift mcp --install -f toon --warnings
xcsift mcp --uninstall

Xcode's own server (xcrun mcpbridge) answers only while MCP is enabled (Xcode ▸ Settings ▸ Intelligence, or sudo xcrun mcp-server enable); when it exits without answering, the proxy writes that diagnostic to stderr.

Proxy-specific flags: --on-summary append|replace|off, --no-inject-tools, --build-tool-pattern, --min-raw-lines, --max-log-size, --verbose, and for registration --install, --uninstall, --force, --server-name, --scope. Every parsing/formatting flag (--format, --warnings, --build-info, --executable, --slow-threshold, --xcbeautify) is shared with the pipeline mode through SiftingOptions, and .xcsift.toml is honoured.

Plugin Installation

xcsift can be integrated with coding assistants via built-in plugin installers:

Claude Code:

xcsift install-claude-code      # Install from marketplace
xcsift uninstall-claude-code    # Remove plugin

Codex:

xcsift install-codex            # Install skill
xcsift uninstall-codex          # Remove skill

Cursor:

xcsift install-cursor           # Install hooks (project-level)
xcsift install-cursor --global  # Install hooks (global)
xcsift uninstall-cursor         # Remove hooks

After plugin installation, xcodebuild and swift build commands are automatically piped through xcsift for structured output.

Any agent, through mise: mise skills sync links the skill of the installed release into .claude/skills (-g for ~/.claude/skills, --dir for another directory). It installs the skill only, no hook.

Running the Tool

# Basic usage (reads from stdin)
# IMPORTANT: Always use 2>&1 to capture stderr (where compiler errors and warnings are written)
xcodebuild build 2>&1 | xcsift

# Test output parsing
xcodebuild test 2>&1 | xcsift

# Swift Package Manager
swift build 2>&1 | xcsift
swift test 2>&1 | xcsift

# Print detailed warnings list (by default only warning count is shown in summary)
swift build 2>&1 | xcsift --warnings
xcodebuild build 2>&1 | xcsift --warnings

# Quiet mode - suppress output when build succeeds with no warnings or errors
swift build 2>&1 | xcsift --quiet
xcodebuild build 2>&1 | xcsift -q

# Werror mode - treat warnings as errors (build fails if warnings present)
swift build 2>&1 | xcsift --Werror
xcodebuild build 2>&1 | xcsift -W

# Exit on failure - exit with non-zero code if build does not succeed
swift build 2>&1 | xcsift --exit-on-failure
xcodebuild build 2>&1 | xcsift -E

# CI integration - combine --Werror and --exit-on-failure for strict CI builds
# This fails the build if there are any errors, warnings, or test failures
xcodebuild build 2>&1 | xcsift --Werror --exit-on-failure
swift build 2>&1 | xcsift -W -E

# xcbeautify/Tuist input - parse xcbeautify-formatted output
# Enables [x], [!], ✔, ✖ markers from xcbeautify/Tuist
tuist build MyScheme 2>&1 | xcsift --xcbeautify
xcodebuild build 2>&1 | xcbeautify 2>&1 | xcsift --xcbeautify

# Combine with other flags
tuist build MyScheme 2>&1 | xcsift --xcbeautify -f toon -w

# Executable targets - output executable targets generated by the build
# Parses RegisterWithLaunchServices and Validate lines from xcodebuild output
xcodebuild build 2>&1 | xcsift --executable
xcodebuild build 2>&1 | xcsift -e

# Combine with other flags
xcodebuild build 2>&1 | xcsift -e -w -f toon

# Code coverage - automatically converts .profraw/.xcresult to JSON (no manual conversion needed!)

# SPM: auto-detects and converts .profraw files (summary-only by default)
swift test --enable-code-coverage 2>&1 | xcsift --coverage
swift test --enable-code-coverage 2>&1 | xcsift -c

# xcodebuild: auto-detects and converts .xcresult bundles (searches DerivedData automatically!)
# Automatically filters coverage to tested target only
xcodebuild test -enableCodeCoverage YES 2>&1 | xcsift --coverage

# Show detailed per-file coverage (default is summary-only for token efficiency)
swift test --enable-code-coverage 2>&1 | xcsift --coverage --coverage-details
xcodebuild test 2>&1 | xcsift -c --coverage-details

# Specify custom coverage path (optional - auto-detects by default)
swift test --enable-code-coverage 2>&1 | xcsift --coverage --coverage-path .build/arm64-apple-macosx/debug/codecov
xcodebuild test 2>&1 | xcsift --coverage --coverage-path path/to/file.xcresult

# Auto-detection and conversion:
# SPM (.profraw → .profdata → JSON via llvm tools):
#   - .build/debug/codecov
#   - .build/arm64-apple-macosx/debug/codecov
#   - .build/x86_64-apple-macosx/debug/codecov
#   - .build/arm64-unknown-linux-gnu/debug/codecov
#   - .build/x86_64-unknown-linux-gnu/debug/codecov
#
# xcodebuild (.xcresult → JSON via xcrun xccov):
#   - ~/Library/Developer/Xcode/DerivedData/**/*.xcresult (searches automatically)
#   - Current directory/**/*.xcresult

# TOON format (30-60% fewer tokens for LLMs)
# Token-Oriented Object Notation - optimized for LLM consumption

# Basic TOON output
xcodebuild build 2>&1 | xcsift --format toon
xcodebuild build 2>&1 | xcsift -f toon

# TOON with warnings
swift build 2>&1 | xcsift -f toon --warnings
xcodebuild build 2>&1 | xcsift -f toon -w

# TOON with coverage
swift test --enable-code-coverage 2>&1 | xcsift -f toon --coverage
xcodebuild test -enableCodeCoverage YES 2>&1 | xcsift -f toon -c

# Combine all flags
xcodebuild test 2>&1 | xcsift -f toon -w -c --coverage-details

# TOON format features:
# - 30-60% token reduction compared to JSON
# - Tabular format for uniform arrays (errors, warnings, tests)
# - Human-readable indentation-based structure
# - Ideal for LLM consumption and API cost reduction
# - Works with all existing flags (--quiet, --coverage, --warnings)

# TOON Configuration - customize delimiter

# Delimiter options (default: comma):
# - comma: CSV-style format (default, most compact)
# - tab: TSV-style format (better for Excel/spreadsheet import)
# - pipe: Alternative separator (good for data with many commas)

# Tab delimiter - useful for Excel/spreadsheet import
xcodebuild build 2>&1 | xcsift -f toon --toon-delimiter tab
swift build 2>&1 | xcsift --format toon --toon-delimiter tab

# Pipe delimiter - alternative when data contains many commas
xcodebuild test 2>&1 | xcsift -f toon --toon-delimiter pipe

# TOON key folding is deprecated: TOON specification 4.0 removed it.
# xcsift always writes nested objects (TOON specification 4.1).
# --toon-key-folding and --toon-flatten-depth (and key_folding / flatten_depth in the config file)
# still parse, so existing scripts and MCP registrations still start, but they have no effect.
# `safe` writes a warning to stderr. The flags are hidden from --help.

# Combine TOON options
xcodebuild test 2>&1 | xcsift -f toon --toon-delimiter pipe -w -c

# Slow/flaky test detection
# Detects tests that exceed a duration threshold and tests that both pass and fail in the same run

# Set slow threshold to 1.0 seconds (tests taking longer are marked as slow)
swift test 2>&1 | xcsift --slow-threshold 1.0
xcodebuild test 2>&1 | xcsift --slow-threshold 0.5

# Combine with other flags
swift test 2>&1 | xcsift -f toon --slow-threshold 2.0 -w
xcodebuild test 2>&1 | xcsift --slow-threshold 1.0 --coverage

# Note: Flaky test detection is automatic (no flag needed)
# A test is marked as flaky if it both passes AND fails in the same run (retry scenarios)

# Build info - show per-target phases and timing
xcodebuild build 2>&1 | xcsift --build-info
swift build 2>&1 | xcsift --build-info
xcodebuild build 2>&1 | xcsift -f toon --build-info -w

# Configuration file - store default options in .xcsift.toml
# Generate a template config file in current directory
xcsift --init

# Use custom config file path
xcodebuild build 2>&1 | xcsift --config ~/my-config.toml

# Config files are searched in order:
# 1. .xcsift.toml in current directory
# 2. ~/.config/xcsift/config.toml
# CLI flags always override config file values

Architecture

The codebase follows a modular architecture:

Core Components

  1. main.swift - Entry point using Swift ArgumentParser
    • Reads stdin through StreamingLineReader and coordinates parsing/output
    • Outputs JSON or TOON format (controlled by --format / -f flag)

1b. StreamingLineReader.swift - Bounded stdin reader

  • Reads 64 KiB chunks and frames lines on the newline byte (CRLF input keeps a trailing \r)
  • Lines longer than LineParser.maximumLineBytes (64 KiB) are ignored and reported to stderr
  1. OutputParser.swift - Core parsing logic
    • StreamingOutputParser accumulates events line-by-line; OutputParser wraps it for complete input
    • OutputParser class with regex-based line parsing
    • Defines data structures: BuildResult, BuildSummary, BuildError, BuildWarning, FailedTest, SlowTest, CodeCoverage, FileCoverage, BuildInfo, TargetBuildInfo, Executable
    • Pattern matching for various Xcode/SPM output formats
    • Extracts file paths, line numbers, and messages from build output
    • Parsing Constants (dedicated enum files in Sources/):
      • XcodebuildSymbols: Named constants for raw xcodebuild/SPM string patterns (: error: , Test Case ', linker patterns, etc.)
      • XCBeautifySymbols: Markers from xcbeautify ([x], [!], ✔, ✖, etc.)
      • When adding new string patterns, add to the appropriate enum rather than using inline literals
    • Parses build phases and per-target timing information
    • Parses executable targets from RegisterWithLaunchServices and Validate lines

2b. MCP/ (MCP proxy) - xcsift mcp, an MCP server that fronts another Xcode MCP server

  • MCPCommand.swift: the mcp subcommand; upstream command comes after -- (.postTerminator, which keeps xcsift mcp --help working). validate() refuses an uncompilable --build-tool-pattern and out-of-range limits, so nothing fails open at runtime
  • MCPProxyRunner.swift: resolves the server on PATH, spawns it, pumps stdio both ways on two threads that share no mutable state, inherits its stderr, mirrors its exit status, and runs the spec's shutdown sequence (close stdin → SIGTERM → SIGKILL, by pid — Process is not Sendable) when the client's stream closes. A read error is distinguished from EOF and reported; write failures are reported once and abandon that stream rather than emitting half a message
  • MCPProxySession.swift: protocol-aware routing — tracks in-flight ids in a lock-guarded PendingRequestTable (the session itself is immutable), rewrites matching results, adds a tools capability to initialize when the server declares none, and advertises and serves the injected xcsift_parse_build_log tool. Everything else is forwarded byte for byte. Declaring that capability makes the listing the proxy's to answer: it serves tools/list itself, and — because the two pumps have no ordering between them, so the client's request can overtake the initialize response — also answers a -32601 rejection of tools/list with the injected tool. Any other error is still the server's to report
  • MCPMessageFramer.swift: newline framing. A message is buffered up to 4 MiB; past that its bytes pass through in chunks, the last one flagged so the writer can hold the stream exclusively for the whole message (both pumps write to stdout — an injected reply landing mid-message would desynchronise framing)
  • JSONValue.swift: JSON model with single-line serialization; re-serialization sorts keys and normalises numbers, which is why untouched messages are copied rather than re-encoded
  • BuildOutputSifter.swift: decides what happens to one text block (Outcome carries a replacement, appended blocks and stderr notes). ToolTrust says how far a tool's name licenses interpreting its output as a build: an unknown tool needs a terminal phase marker and never has its referenced logs read
  • XcodeTestResults.swift (XCSiftCore): reads the enumeration Xcode's server answers a test run with (TEST RESULTS SUMMARY, one block per test). It is the authority on the run, so the sifter substitutes the parsed result for it — 31 108 bytes of a measured run became 1 069, exact at 69 passed and 3 failed. Parsing is refused unless Total Results and the blocks agree, because a skipped block is a test that disappears
  • One JSON parse per content block: a summarising server answers in JSON, and both the log-path search and the enumerated-results gate read that structure. BuildOutputSifter parses it once and passes the value to BuildLogReference.logPaths(in:json:homeDirectory:) and enumeratesTestResults(_:)
  • BuildLogReference.swift: recovers build-log paths from JSON (fullLogPath) and from a rendered file tree (ANSI codes, box-drawing glyphs, ~, base directory + indented children, with the base scoped to the lines nested under it)
  • MCPDefaults (in BuildOutputSifter.swift): every default the flags and the types share, so a documented default lives in one place
  • Install/MCPServerInstaller.swift: --install / --uninstall, through claude mcp add and claude mcp remove rather than by editing JSON. The registration records the same argument list --print-config prints (MCPProxyCommand.proxyArguments(for:)), so what runs is what the flags said; removal targets the server name in whichever scope holds it, so an entry added by hand is removed by it too

Two upstream shapes: raw xcodebuild/SPM transcripts are replaced with the sifted result; already-summarised responses that reference a log on disk keep their text and get the sifted result appended (--on-summary). Anything else is untouched — the proxy never degrades a response it does not understand.

Which shape a text is is BuildOutputSifter.classify. A terminal phase marker (** BUILD FAILED **) settles that the text is build output, but not that it is the transcript: servers quote the marker into their own summaries. So a text that carries the marker alone and also names a log on disk is treated as a summary of that log — otherwise replacing it would drop the server's fields, the error count and the path itself. Only corroborated transcripts outrank a log they mention, and a replacement carries the path forward either way. When no referenced path holds a usable log, the text is sifted as build output after all, so a transcript that merely names a .txt file is not left alone.

Appending is gated, not filtered. BuildOutputSifter.adds(_:beyond:) compares the parsed log with the server's own text and opens the gate only when the log carries something the response does not; the whole result is then appended. That is what makes the proxy useful against Xcode's server — BuildProject returned structured errors but never warnings, as observed on Xcode 27 — and what keeps a failing build from being restated twice. Case and target attribution (… (in target 'A' …)) are normalised before comparing. A response enumerating per-test results is left alone: the server that ran the tests counts more accurately than an Xcode console transcript can be aggregated (known gap, see Sources/xcsift/xcsift.docc/MCPProxy.md → Limits).

Xcode's server approves agents by binary + code signature, so with the proxy the agent is xcsift, and an ad-hoc rebuild is a new agent needing re-approval (xcrun mcp-server status lists permitted agents and folders).

2c. SiftingOptions.swift / ConfigMerger.swift / ResultRenderer.swift - Shared between both modes

  • A resolved configuration is two halves and a remainder: ParseConfig (what changes the result a build's output is found to be — warnings, coverage, slow threshold, build info, xcbeautify), RenderConfig (format and the TOON options, which change nothing about what the result says), and quiet / exit_on_failure, which belong to neither and are the pipeline's own. What a consumer is handed says what it can do: ResultRenderer takes a RenderConfig, the MCP proxy takes both halves and never sees quiet or exit_on_failure — the two values documented as meaningless over MCP, now by construction
  • SiftingOptions is an @OptionGroup declared by both the root command and mcp. This is required, not cosmetic: ArgumentParser lets the root command consume its own options wherever they appear, so a subcommand that re-declares --warnings never sees it. Sharing one ParsableArguments type makes the root's parsed value flow to the subcommand.
  • ResultRenderer encodes a BuildResult as JSON/TOON/annotations for both modes
  1. CoverageParser.swift - Code coverage parsing
    • CoverageParser struct with dependency injection for testability
    • Auto-detects and converts .profraw (SPM) and .xcresult (xcodebuild) formats
    • Searches DerivedData for latest xcresult bundles
    • Static API preserved for backward compatibility
  2. FileSystemProtocol.swift & ShellRunnerProtocol.swift - Dependency injection
    • Protocols for file system and shell command abstraction
    • Enable mocking in tests to avoid slow I/O operations
  3. Configuration.swift, ConfigLoader.swift, ConfigMerger.swift - Configuration file support
    • Configuration struct (Codable) for TOML config file parsing
    • ConfigLoader handles file discovery and parsing with user-friendly errors
    • ConfigMerger merges config file values with CLI arguments (CLI takes precedence)
    • Uses swift-toml library for TOML parsing

Data Flow

  1. Stdin input → readStandardInput()
  2. Raw text → OutputParser.parse() → line-by-line regex matching
  3. Parsed data → BuildResult struct
  4. Output formatting (JSON or TOON) → stdout

Xcode Console Logs

Xcode's own build/test transcript (what its MCP server writes and reports as fullLogPath / fullConsoleLogsPath) differs from piped xcodebuild output in two ways the parser handles explicitly:

  • Diagnostics are indented under the task that emitted them. LineParser.withoutIndentation strips that whitespace from parsed file paths — otherwise every reported path is unopenable.
  • Suite completions repeat (inline, under Summary:, sometimes again) with identical millisecond timestamps. LineParser keys counted completions by suite name + timestamp, so a repeat adds no tests. Two genuine completions of one suite in the same millisecond would be indistinguishable, and a completion line with no timestamp is always counted. Tests/XCSiftCoreTests/XcodeConsoleLogTests.swift uses .xctest suite names on purpose: only bundle-level totals accumulate, so a fixture without that suffix would pass without the fix.
  • Two frameworks, one run. Xcode runs XCTest bundles and Swift Testing in the same session and an XCTest bundle summary counts Swift Testing's tests as zero, so the bundle total alone reports a two-framework run as the smaller one (a measured 72-test run came back as 23). Swift Testing's own per-test lines are counted instead, when the log carries no run summary to use: LineParser tallies ✔ Test "…" passed after … by test name (Xcode repeats whole blocks) and expands with N test cases, because each case of a parameterised test counts as a test. The glyph is the heavy check U+2714, not U+2713, and the line is indented under the task that emitted it — the shape of the line is matched, not a prefix.
  • The transcript is lossy, and says so. That same run printed started for 34 Swift Testing tests and an outcome for 29. summary.unreported_tests carries the difference, so a total that falls short of Xcode's own is explainable rather than silent. A run summary, where the log has one, is authoritative and leaves the field nil.
  • A failure restated without its test. Xcode also writes <file>:test failure:<message>, which used to become a second failure named Test assertion. A failure with no test name is dropped when something already reported carries that message, and replaced by the named rendering when that arrives second. The summary never counts fewer failures than the list it ships.
  • CRLF line endings. String.split(separator: "\n") never matches one, because Swift reads \r\n as a single Character. TextLines.split (XCSiftCore) splits on the newline byte instead, and every path that takes whole text rather than a stream goes through it: OutputParser, the MCP sifter's classification and parsing, and BuildLogReference.
  • A non-finite duration (Double("inf") parses) cannot be encoded, and would turn a finished build into an encoding error. LineParser.finiteDuration drops it.

Multi-line Context Pattern

  • LineParser.processLine sees one line at a time, plus lookBackBuffer: the last three non-blank lines it processed, each marked with whether a parser claimed it. Every line passes through processLine exactly once, in order, whichever feed path delivered it.
  • Look-ahead is pendingRecordedIssueLine, held until the next line arrives
  • Existing examples: look-back for PhaseScriptExecution context and for failed build commands, look-ahead for Swift Testing #expect comments
  • failedTests are deduplicated by normalized test name — duplicate names get merged, not appended
  • Source-context echo: a file:line:col: error:/warning:/note: header opens a block that holds the indented source line and the caret line. LineParser.sourceContextOpen tracks the block and skips error/warning parsing inside it, because echoed source can carry : error: in a string literal. The block closes on the caret line or on the next line without indentation. Indentation alone must never suppress a diagnostic: indented tool output (swiftgen: error: …) stays reportable.
  • Failed build commands: Command <Name> failed with a nonzero exit code becomes a .commandFailed event when its task reported no error or linker error of its own. A task runs from its header (a line with (in target ') to its failure line, so a failed compiler is not restated, and a CodeSign failure in the next task still is.
    • The message is the failure line, preceded by up to three look-back lines as its reason: unclaimed lines at the failure line's own indentation. A deeper line (the echoed invocation), a shallower one (a heading such as Testing failed:), a task header, a terminal marker, or an earlier failure ends the search. xcodebuild's log lines and crash backtrace frames are skipped.
    • xcodebuild test restates the failures that stopped it under Testing failed:. seenFailedCommands recognises those, including PhaseScriptExecution, and drops them.
    • A success marker vouches for the failures before it: failedCommandsSinceSuccessMarker resets on every marker, and StreamingOutputParser.finish reports that many failed commands from the end.
    • Command PhaseScriptExecution failed is a plain .error and is always reported.

Key Features

  • Error/Warning Parsing: Multiple regex patterns handle various Xcode error formats
  • Runtime Warning Parsing: Parses SwiftUI and custom runtime warnings (e.g., from swift-issue-reporting)
    • Format: /path/to/file.swift:42 Message (without : warning: keyword)
    • Warning types: compile, runtime, swiftui (in type field)
    • SwiftUI warnings detected by keywords: "Accessing Environment", "Accessing StateObject", "StateObject's wrappedValue", "Publishing changes", "Modifying state"
    • Custom runtime warnings default to type: "runtime"
    • Included with --warnings flag (no separate flag needed)
  • Linker Error Parsing: Captures undefined symbols, missing frameworks/libraries, architecture mismatches, and duplicate symbols (with structured conflicting file paths)
  • Failed Build Commands: Command CodeSign failed with a nonzero exit code and the like become errors, with the tool's own output as the reason, when the failing task reported no error of its own (see "Failed build commands" under the multi-line context pattern)
  • Test Failure Detection: XCUnit assertion failures and general test failures
    • XCTest failure line: <file>:<line>: error: -[<Class> <test>] : <message> is a failed test whatever the message says (XCTFail, XCTUnwrap, a thrown error, an unmet expectation). It is not an error, and it merges with the Test Case '-[…]' failed line by test name. A compiler diagnostic has a column and no -[, so it stays an error
    • XCTExpectFailure: XCTest writes two lines for a failure it absorbed, XCTExpectFailure: matcher accepted … and <file>:<line>: Expected failure in -[…]: …, and then reports the test as passed. Both lines can carry XCTAssertTrue failed, so LineParser skips them before any parser (the .expectedFailure candidate bit). An unmet strict expectation (error: … : Expected failure '…' but none recorded) is a real failure
    • XCTSkip: XCTest counts a skipped test as executed (Executed 10 tests, with 1 test skipped and 5 failures). LineParser subtracts the skipped tests from the executed count of .testSuiteCompleted, so they are not counted as passed
    • Swift Testing console symbols: SF Symbols from Private Use Area (macOS) with Unicode fallbacks (Linux)
      • details line: 􀄵 U+100135 (macOS) / ↳ U+21B3 (Linux) — carries #expect custom comments
      • fail line: 􀢄 U+100884 (macOS) / ✘ U+2718 (Linux)
      • default/started: 􀟈 U+1007C8 (macOS) / ◇ U+25C7 (Linux)
      • Source: apple/swift-testing Event.Symbol.swift
    • Standard format: Test Case 'X.test()' passed/failed (0.123 seconds)
    • Parallel testing format: Test case 'X.test()' passed/failed on 'Device Name' (0.123 seconds)
    • Parallel format uses lowercase 'case' and includes device name before duration
    • Both formats supported for xcodebuild parallel/multi-destination testing
  • Build Time Extraction: Captures build duration (build_time) and test execution time (test_time) separately
  • File/Line Mapping: Extracts precise source locations for navigation
  • Executable Target Detection: Parses RegisterWithLaunchServices and Validate lines to extract executable targets (path, name, target)
  • Build Info: Unified per-target phases, timing, and dependencies
    • Enabled with --build-info flag
    • Groups phases by target with per-target duration
    • Parses target dependency graph from xcodebuild output
    • Slowest Targets: Top 5 targets sorted by duration (descending) in slowest_targets array
    • Supports xcodebuild phase detection from "(in target 'X' from project 'Y')" patterns
    • Supports SPM phase detection from "[N/M] Compiling/Linking TARGET" patterns
    • Parses "Build target X (Ys)" and "** <PHASE> SUCCEEDED ** [Xs]" patterns
    • Build time in summary.build_time, test execution time in summary.test_time (not duplicated in build_info)
    • xcodebuild phases: CompileSwiftSources, SwiftCompilation, CompileC, Link, CopySwiftLibs, PhaseScriptExecution, LinkAssetCatalog, ProcessInfoPlistFile
    • SPM phases: Compiling, Linking
    • Dependency Graph: Extracts target dependencies from xcodebuild "Target dependency graph" output
      • Parses "Target 'X' in project 'Y'" and "➜ Explicit dependency on target 'Z'" patterns
      • Outputs depends_on array for each target (omitted when empty)
  • Code Coverage with Auto-Conversion: Automatically converts coverage files to JSON when --coverage flag is used
    • Auto-detection: Searches multiple default paths for both SPM and xcodebuild formats
    • Target filtering: Automatically extracts tested target name from xcodebuild output and filters coverage to that target only
    • Summary-only mode (default): Outputs only line coverage percentage to minimize token usage
    • Details mode (with --coverage-details): Includes full per-file coverage data
    • SPM auto-conversion: Finds .profraw files, locates test binary, runs llvm-profdata merge and llvm-cov export
      • .profraw → .profdata → JSON (fully automatic)
    • xcodebuild auto-conversion: Finds .xcresult bundles, runs xcrun xccov view --report --json
      • .xcresult → JSON (fully automatic)
    • No manual steps: Works out of the box with both build systems
      • SPM: swift test --enable-code-coverage 2>&1 | xcsift --coverage
      • xcodebuild: xcodebuild test -enableCodeCoverage YES 2>&1 | xcsift --coverage
    • Supports both formats seamlessly
  • Slow Test Detection: Identifies tests exceeding a configurable duration threshold
    • Enabled with --slow-threshold <seconds> flag
    • Parses test duration from both XCTest and Swift Testing output formats
    • Reports slow tests in both summary (count) and detailed list with test name and duration in seconds
  • Flaky Test Detection: Automatically detects tests that both pass and fail in the same run
    • No flag required - detection is automatic
    • Useful for identifying unstable tests in retry scenarios
    • Reports in both summary (count) and detailed list
  • Test Duration Tracking: Captures execution time for each test
    • Duration included in FailedTest struct for failed tests
    • Tracked internally for passed tests (used for slow/flaky detection)
  • xcbeautify Input Parsing: Opt-in --xcbeautify flag for parsing xcbeautify/Tuist-formatted output
    • Parses [x]/❌ as errors, [!]/⚠️ as warnings, ✔ as passed, ✖ as failed
    • Test results are indented by four spaces and carry no passed/failed: ✔ <test> (<t> seconds), ✖ <test>, <reason>, ✖ <file>:<line>, <reason> (UI tests), ✖ <test> (<t> seconds) <n> issue(s) (Swift Testing), ✔ [<Suite>] <test> on '<device>' (<t> seconds) (parallel, named <Suite>.<test>). A ✔ needs the duration and a ✖ needs a duration or a one-word test before , , so Tuist's ✔ Success / ✖ Error are not tests. An indented [!] is a Swift Testing issue and goes to the Swift Testing parser, not to warnings
    • A Swift Testing result has no Test in xcbeautify's rendering, and XCTest's Executed … totals do not include it. LineParser.recordingXcbeautifySwiftTestingResult counts a ✔/✖ result whose name has a quote or a () in the Swift Testing tallies (each parameterised case counts), and gives it the name the Swift Testing parser uses ("Display name" → Display name), so the failure merges with its recorded an issue line. XCTest names have neither
    • The terminal renderer writes a compile warning with two spaces after [!]/⚠️; the path is trimmed
    • Parses the GitHub Actions renderer (::error file=<path>,line=<n>,col=<n>::<message>, ::warning …, location optional), which Tuist selects when GITHUB_ACTIONS is set. The path is not escaped, so line and col are read from the end. That renderer writes a failing test as ::error too: an indented message (XCTest, parallel) or one that ends in issue(s) (Swift Testing) is a failed test, anything else an error
    • Auto-detection: Emits stderr hint when xcbeautify markers detected without flag
    • Testable via parser.didEmitXcbeautifyHint property (private(set))

Testing

Tests are in Tests/*.swift using XCTest framework.

Test Fixtures

Real-world output samples are stored in Tests/XCSiftCoreTests/Fixtures/ for integration tests:

  • build.txt (~2.7MB) - Large successful xcodebuild output for performance testing
  • swift-testing-output.txt (~11KB) - Swift Testing output with 23 passed tests
  • linker-error-output.txt - Real linker error output with undefined symbols
  • xcode-console-test-run.txt (~94KB) - Xcode's own console transcript for a 72-test run of two frameworks, with every block repeated under Summary: and five Swift Testing outcomes missing
  • xcode-test-results-summary.txt (~31KB) - what Xcode's MCP server answered for that same run: 72 blocks, 69 passed, 3 failed. The pair is what makes the transcript's shortfall measurable

To add new fixtures:

  1. Create the file in Tests/XCSiftCoreTests/Fixtures/
  2. Add to Package.swift resources: .copy("Fixtures/your-file.txt")
  3. Load in tests via Bundle.module.url(forResource: "your-file", withExtension: "txt")

Test Coverage

Test cases cover:

  • Error parsing from various Xcode formats
  • Warning detection
  • Runtime warning parsing (10 tests):
    • SwiftUI Environment warning parsing
    • SwiftUI Publishing changes warning parsing
    • SwiftUI Modifying state warning parsing
    • SwiftUI StateObject wrappedValue warning parsing
    • Custom runtime warning parsing (swift-issue-reporting style)
    • Compile warning type detection
    • Mixed compile and runtime warnings
    • Runtime warning deduplication
    • Runtime warning vs compile warning format distinction
    • JSON encoding with type field
  • Linker error parsing (14 tests):
    • Undefined symbol errors
    • Multiple undefined symbols
    • Architecture mismatch errors
    • Framework/library not found
    • Duplicate symbols with structured conflicting_files parsing
    • Duplicate symbols with double quotes
    • Duplicate symbols JSON encoding
    • Mixed compiler and linker errors
    • Swift mangled symbols
    • Real-world linker error output (fixture-based test)
  • Failed test extraction
  • Parallel testing format (4 tests):
    • Parallel passed test parsing
    • Parallel failed test parsing with duration
    • Mixed passed/failed parallel tests
    • Duration extraction with complex device names
  • Multi-error scenarios
  • Build time parsing
  • Edge cases (missing files, deprecated functions)
  • Code coverage data structures and parsing
  • JSON encoding with and without coverage data
  • SPM coverage format parsing
  • xcodebuild coverage format parsing (decimal and percentage formats)
  • Format auto-detection
  • Target extraction from xcodebuild output
  • Coverage target filtering
  • Summary-only vs details mode for coverage output
  • Executable parsing (6 tests):
    • Single executable parsing
    • Multiple executables parsing
    • Executables not included when flag is false
    • Executables included in JSON when flag is true
    • No executables in output
    • Executable deduplication by path
  • TOON format encoding (18 tests):
    • Basic TOON encoding
    • TOON with errors, warnings, and failed tests
    • TOON with linker errors
    • TOON with code coverage
    • TOON with executables
    • Token efficiency verification (30-60% reduction)
    • Summary-only vs details mode in TOON format
  • Build phases, timing, and dependencies (45 tests):
    • CompileSwiftSources phase parsing
    • SwiftDriver Compilation phase parsing
    • CompileC (Clang) phase parsing
    • Link phase parsing
    • CopySwiftLibs phase parsing
    • PhaseScriptExecution phase parsing
    • Multiple phases capture
    • Phases omitted by default
    • Single and multiple target timing
    • SPM timing format ("Build complete!")
    • xcodebuild timing formats (SUCCEEDED/FAILED with brackets)
    • Target completed format
    • Timing omitted by default
    • JSON encoding with phases and timing
    • SPM Compiling/Linking phase parsing
    • SPM multiple targets
    • SPM plugin compilation skipped
    • Target order preservation
    • TOON encoding with build_info
    • Dependency graph parsing (single target, multiple dependencies, no dependencies)
    • Dependency graph order preservation
    • Dependency graph deduplication
    • Dependencies combined with phases
    • depends_on field encoding (omitted when empty)
    • Slowest targets (7 tests):
      • Sorted by duration descending
      • Limited to top 5
      • Omits targets without duration
      • Empty when no durations
      • Encoding (omitted when empty, encoded when not)
      • TOON format support
  • Configuration file support (28 tests):
    • Configuration decoding (full, partial, empty)
    • Format option variants (json, toon, github-actions)
    • Delimiter option variants (comma, tab, pipe)
    • TOON section-only decoding
    • ConfigLoader tests:
      • Explicit path not found error
      • Auto-detect CWD config
      • Auto-detect user config
      • CWD priority over user config
      • No config returns nil
      • Read error handling
      • Invalid TOML syntax error
      • Template generation
    • ConfigMerger tests:
      • CLI format overrides config
      • CLI boolean flags override config
      • CLI TOON options override config
      • Config used when CLI not set
      • Defaults when neither set
      • Empty coverage path treated as nil
      • Deprecated key folding: safe gives a warning, CLI disabled silences the config value
    • ConfigError description tests
  • Failed build commands (31 tests in Tests/XCSiftCoreTests/FailedCommandTests.swift): the reason and what ends its search, task-local explanation (compiler, linker, script phase, build-system errors), Testing failed: restatements, success markers vouching only for earlier failures, multi-word rule names, CRLF and overlong lines, and the LineParser and TrackingLineParser contract of .commandFailed
  • MCP proxy (138 tests in Tests/xcsiftTests/MCP*.swift):
    • MCPMessageTests: JSON model round-trips, single-line serialization, newline framing, oversized-message passthrough and its final-chunk flag, truncation reporting
    • MCPSifterTests: build-log path recovery (prose trees and JSON), transcript replacement, trust gating, append/replace/off strategies, size limits, "nothing to add" cases, declined-log notes, and Xcode's test enumeration being replaced rather than passed through
    • MCPProxySessionTests: verbatim forwarding (non-JSON, batches, notifications, server-initiated requests, untracked ids, errors), result rewriting with sibling keys preserved, every id shape, the build-tool gate failing closed, tool injection and capability declaration, injected tool calls and their argument validation, pending-request eviction
    • MCPCommandTests: the configuration snippet (completeness, escaping, terminators), every validation refusal, the deprecated key folding flags (they parse, the snippet drops them), and MCPServerInstallerTests — the claude mcp commands built for --install/--uninstall, their shell quoting, and the taken-name and never-registered cases
    • MCPProxyEndToEndTests: the built binary proxying a canned POSIX-shell MCP server, a 5 MB passthrough followed by an in-sync sift, launch failure, a server that never answers, and shutdown escalation to SIGKILL
  • xcbeautify parsing (52 tests in Tests/XcbeautifyTests.swift):
    • ASCII and emoji error/warning markers ([x], ❌, [!], ⚠️)
    • GitHub Actions workflow commands (::error, ::warning, with and without a location)
    • Test status markers (✔, ✖): indented, Swift Testing, parallel, UI tests, and Tuist's own ✔ Success / ✖ Error
    • Pass and fail counts of runs with XCTest and Swift Testing, in both renderers, and of Swift Testing alone
    • Auto-detection hint (shown/not shown/once/clean input)
    • Flag-gating (markers ignored without --xcbeautify)
    • Integration tests (full output, TOON format, default mode unaffected)

Run individual tests:

swift test --filter OutputParserTests.testParseError

Dependencies

  • Swift ArgumentParser: CLI argument handling (Package.swift dependency)
  • ToonFormat (toon-swift): Token-Oriented Object Notation encoder for efficient LLM output (Package.swift dependency)
  • swift-toml: TOML configuration file parsing with Codable support (Package.swift dependency)
  • Foundation: Core Swift framework for regex, JSON encoding, string processing
  • XCTest: Testing framework (test target only)

Platform Support

  • macOS 15+: Full support including code coverage conversion
  • Linux (Swift 6.0+): Full support for build/test parsing; coverage features use macOS-specific tools (xcrun) and return nil on Linux

Linux Compatibility Notes

When modifying code, ensure Linux compatibility:

  • Use conditional imports: #if canImport(Darwin) / #elseif canImport(Glibc) / #elseif canImport(Musl)
  • Avoid fputs(..., stderr) — use FileHandle.standardError.write() for Swift 6 concurrency safety
  • CI builds and tests every supported toolchain (see .github/workflows/ci.yml): Swift 6.0 to 6.4 on macOS (Xcode 16.0, 16.4, 26.0, 26.6, 27.0) and on Linux (swift:6.x-jammy containers). Swift 6.0 is the minimum (swift-tools-version: 6.0, and Xcode 16.0 in the Homebrew formula), so do not use a language feature that is newer, for example a trailing comma in an argument list (Swift 6.1). Homebrew builds the macOS 27 and Linux bottles with Swift 6.4.

Swift 6 Concurrency

  • Capturing a mutable var in a @Sendable closure is rejected by strict concurrency. For shared mutable state across @Sendable closures (e.g. Pipe.readabilityHandler, DispatchQueue.async, DispatchSourceTimer event handlers), wrap the state in a final class … @unchecked Sendable and gate every read/write with an NSLock.

Output Formats

The tool outputs structured data optimized for coding agents in two formats:

JSON Format (default)

  • JSON: Structured format with status, summary, errors, warnings (optional), failed_tests, linker_errors (optional), coverage (optional), phases (optional), timing (optional)
    • summary.unreported_tests (only when non-zero): tests that started and whose outcome the log never reported. Xcode's console transcript drops lines, so a count taken from one can be short; this says by how many tests.
    • Summary always includes warning and linker error counts: {"summary": {"warnings": N, "linker_errors": N, ...}}
    • Summary includes coverage percentage (when --coverage flag is used): {"summary": {"coverage_percent": X.X, ...}}
    • Detailed warnings list (with --warnings flag): {"warnings": [{"file": "...", "line": N, "message": "...", "type": "compile|runtime|swiftui"}]}
      • type: "compile" - compiler warnings (format: file:line: warning: message)
      • type: "swiftui" - SwiftUI runtime warnings (e.g., "Accessing Environment", "Publishing changes")
      • type: "runtime" - custom runtime warnings (format: file.swift:line message)
    • Linker errors: Two types are supported:
      • Undefined symbols: {"linker_errors": [{"symbol": "_MissingClass", "architecture": "arm64", "referenced_from": "ViewController.o", "message": "", "conflicting_files": []}]}
      • Duplicate symbols: {"linker_errors": [{"symbol": "_duplicateVar", "architecture": "arm64", "referenced_from": "", "message": "", "conflicting_files": ["/path/to/FileA.o", "/path/to/FileB.o"]}]}
    • Default behavior (without flag): Only shows warning count in summary, omits detailed warnings array to reduce token usage
    • Quiet mode (with --quiet or -q flag): Produces no output when build succeeds with zero warnings and zero errors
    • Coverage data (with --coverage flag):
      • Summary-only mode (default - token-efficient): Only includes coverage percentage in summary
        {
          "summary": {
            "coverage_percent": 85.5
          }
        }
      • Details mode (with --coverage-details flag): Includes per-file coverage details
        {
          "coverage": {
            "line_coverage": 85.5,
            "files": [
              {
                "path": "/path/to/file.swift",
                "name": "file.swift",
                "line_coverage": 92.5,
                "covered_lines": 37,
                "executable_lines": 40
              }
            ]
          }
        }
      • Target filtering (xcodebuild only): Automatically extracts tested target from stdout and filters coverage to that target only
      • Supports both SPM (swift test --enable-code-coverage) and xcodebuild (-enableCodeCoverage YES) formats
      • Automatically detects format and parses accordingly
      • Warns to stderr if target was detected but no matching coverage data found
    • Executable targets (with --executable or -e flag): Includes executable targets generated by the build
      {
        "summary": {
          "executables": 1
        },
        "executables": [
          {
            "path": "/path/to/DerivedData/.../ClaudeSettings.app",
            "name": "ClaudeSettings.app",
            "target": "ClaudeSettings"
          }
        ]
      }
    • Build info (with --build-info flag): Includes per-target phases, timing, dependencies, and slowest targets
      {
        "build_info": {
          "targets": [
            {
              "name": "MyFramework",
              "duration": "12.4s",
              "phases": ["CompileSwiftSources", "Link"]
            },
            {
              "name": "MyApp",
              "duration": "23.1s",
              "phases": ["CompileSwiftSources", "Link", "CopySwiftLibs"],
              "depends_on": ["MyFramework"]
            }
          ],
          "slowest_targets": ["MyApp", "MyFramework"]
        }
      }
      • Groups phases by target with per-target timing
      • Parses target dependencies from xcodebuild "Target dependency graph" output
      • Slowest targets: Top 5 targets sorted by duration (descending)
      • Build time is in summary.build_time, test execution time is in summary.test_time (not duplicated in build_info)
      • xcodebuild phases: CompileSwiftSources, SwiftCompilation, CompileC, Link, CopySwiftLibs, PhaseScriptExecution, LinkAssetCatalog, ProcessInfoPlistFile
      • SPM phases: Compiling, Linking
      • Empty fields are omitted (targets without phases won't have phases field, targets without dependencies won't have depends_on field, no slowest_targets when empty)

TOON Format (with --format toon / -f toon flag)

TOON (Token-Oriented Object Notation) is a compact serialization format optimized for LLM consumption, providing 30-60% token reduction compared to JSON.

Key Features:

  • Tabular format for uniform arrays (errors, warnings, tests, coverage files)
  • Indentation-based structure (similar to YAML)
  • Human-readable while optimized for machine parsing
  • Works with all existing flags (--quiet, --coverage, --warnings)
  • Ideal for reducing LLM API costs

Example TOON Output:

status: failed
summary:
  errors: 1
  warnings: 3
  failed_tests: 0
  passed_tests: null
  build_time: null
  test_time: null
  coverage_percent: null
errors[1]{file,line,message}:
  main.swift,15,"use of undeclared identifier \"unknown\""
warnings[3]{file,line,message}:
  Parser.swift,20,"immutable value \"result\" was never used"
  Parser.swift,25,"variable \"foo\" was never mutated"
  Model.swift,30,"initialization of immutable value \"bar\" was never used"

Token Efficiency Comparison:

For the same build output with 1 error and 3 warnings:

  • JSON: 652 bytes
  • TOON: 447 bytes
  • Savings: 31.4% (205 bytes)

When to Use TOON:

  • Passing build output to LLM APIs (reduces costs)
  • Processing large build outputs with many errors/warnings
  • Automated CI/CD pipelines with LLM analysis
  • Token-constrained environments

When to Use JSON:

  • Integrating with existing JSON-based tooling
  • Maximum compatibility with JSON parsers
  • Pretty-printed output for human debugging

GitHub Actions Integration (automatic on CI)

When running on GitHub Actions (GITHUB_ACTIONS=true), xcsift automatically appends workflow annotations after the JSON/TOON output. This creates inline annotations in PRs and the Actions UI.

Behavior Matrix:

EnvironmentFormat FlagOutput
Local(none)JSON
Local-f jsonJSON
Local-f toonTOON
Local-f github-actionsAnnotations only
CI(none)JSON + Annotations
CI-f jsonJSON + Annotations
CI-f toonTOON + Annotations
CI-f github-actionsAnnotations only

Example CI Output:

{
  "status": "failed",
  "summary": { "errors": 1, "warnings": 2 }
}
::error file=main.swift,line=15,col=5::use of undeclared identifier 'unknown'
::warning file=Parser.swift,line=20,col=10::immutable value 'result' was never used
::notice ::Build failed, 1 error, 2 warnings

Annotations Format:

  • ::error file=X,line=Y,col=Z::message — compile errors, test failures
  • ::warning file=X,line=Y,col=Z::message — compiler warnings
  • ::notice ::summary — build summary

Usage in CI:

# GitHub Actions workflow
- name: Build
  run: xcodebuild build 2>&1 | xcsift  # JSON + annotations automatic

- name: Build with TOON
  run: xcodebuild build 2>&1 | xcsift -f toon  # TOON + annotations automatic

- name: Annotations only (no JSON/TOON)
  run: xcodebuild build 2>&1 | xcsift -f github-actions

Configuration File

xcsift supports TOML configuration files to reduce CLI flag complexity. Store your default options in a config file and override them with CLI flags when needed.

Config File Search Order

  1. .xcsift.toml in current working directory
  2. ~/.config/xcsift/config.toml in home directory

If no config file is found, xcsift uses CLI defaults.

CLI Flags

  • --init - Generate a .xcsift.toml template in the current directory
  • --config PATH - Use a specific config file (fails if not found)

Config File Format

# .xcsift.toml
# All options are optional - omit to use defaults

# Output format: "json" (default), "toon", or "github-actions"
format = "toon"

# Warning options
warnings = true          # Print detailed warnings list (-w)
werror = false           # Treat warnings as errors (-W)

# Output control
quiet = false            # Suppress output on success (-q)

# Test analysis
slow_threshold = 1.0     # Threshold in seconds for slow test detection

# Coverage options
coverage = false         # Enable coverage output (-c)
coverage_details = false # Include per-file coverage breakdown
coverage_path = ""       # Custom path to coverage data (empty = auto-detect)

# Build info
build_info = false       # Include per-target build phases and timing
executable = false       # Include executable targets (-e)

# Exit behavior
exit_on_failure = false  # Exit with failure code if build does not succeed (-E)

# Input format
xcbeautify = false       # Parse xcbeautify/Tuist-formatted input (--xcbeautify)

# TOON format configuration
[toon]
delimiter = "comma"      # "comma", "tab", or "pipe"

key_folding and flatten_depth in [toon] are deprecated and have no effect: TOON specification 4.0 removed key folding. xcsift still reads them, so an existing configuration file still loads.

Priority

CLI flags always override config file values. This is documented in --help.

Example:

# Config has format = "toon", but CLI overrides to JSON
xcodebuild build 2>&1 | xcsift -f json

Boolean flags use OR semantics: --warnings, --quiet, --coverage, etc. are enabled if CLI flag is passed OR config value is true. There are no --no-* flags, so you cannot disable a boolean via CLI if it's enabled in config.

Error Messages

Config errors provide user-friendly messages:

Error: Configuration file not found: /path/to/config.toml

Error: TOML syntax error at line 5, column 12: unterminated string

Error: Invalid value 'yaml' for 'format'. Valid options: json, toon, github-actions

Error: Type mismatch at 'warnings': expected Bool, found String

Documentation Maintenance

IMPORTANT: When modifying public API, CLI flags, or features, you MUST update the corresponding DocC documentation in Sources/xcsift.docc/.

Documentation files to update:

  • xcsift.md - Main overview and Topics structure
  • MCPProxy.md - xcsift mcp reference
  • GettingStarted.md - Installation and basic usage
  • Usage.md - CLI flags and options reference
  • OutputFormats.md - JSON/TOON/GitHub Actions format details
  • CodeCoverage.md - Coverage feature documentation

Previewing Documentation Locally

For Claude: You cannot run the preview server (it's interactive/long-running). Ask the user to run it manually.

For user: Run in a separate terminal:

swift package --disable-sandbox preview-documentation --target xcsift

Opens at: http://localhost:8080/documentation/xcsift

Note: The docs/ folder contains pre-generated documentation for GitHub Pages with --hosting-base-path xcsift. Do NOT use a simple HTTP server (like python3 -m http.server) to serve docs/ directly — it won't handle the /xcsift/ base path routing.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.