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.
- xcsiftSkill
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
- Distinctive: line 23
IMPORTANT: Always run before committing changes:
- Very specific: line 33
Use Conventional Commits: fix:, feat:, docs:, chore:, refactor:, test:.
- Very specific: line 57
The signer is the workflow's path: Do not rename release.yml or sign from another workflow file: consumers refuse the release until a …
- Very specific: line 126
After plugin installation, xcodebuild and swift build commands are automatically piped through xcsift for structured output.
- Distinctive: line 314
When adding new string patterns, add to the appropriate enum rather than using inline literals
- Very specific: line 470
Every line passes through processLine exactly once, in order, whichever feed path delivered it.
- Very specific: line 471
Look-ahead is pendingRecordedIssueLine, held until the next line arrives
- Distinctive: line 570
No flag required - detection is automatic
- Very specific: line 578
Test results are indented by four spaces and carry no passed/failed: ✔ <test> (<t> seconds), ✖ <test>, <reason>, ✖ <file>:<line>, <reason> …
- Very specific: line 616
Create the file in Tests/XCSiftCoreTests/Fixtures/
- Very specific: line 617
Add to Package.swift resources: .copy("Fixtures/your-file.txt")
- Distinctive: line 669
No executables in output
- Distinctive: line 721
No config returns nil
- Very specific: line 758
Test status markers (✔, ✖): indented, Swift Testing, parallel, UI tests, and Tuist's own ✔ Success / ✖ Error
- Distinctive: line 784
When modifying code, ensure Linux compatibility:
- Very specific: line 785
Use conditional imports: #if canImport(Darwin) / #elseif canImport(Glibc) / #elseif canImport(Musl)
- Very specific: line 786
Avoid fputs(..., stderr) — use FileHandle.standardError.write() for Swift 6 concurrency safety
- Very specific: line 945
When running on GitHub Actions (GITHUB_ACTIONS=true), xcsift automatically appends workflow annotations after the JSON/TOON output.
- Very specific: line 998
If no config file is found, xcsift uses CLI defaults.
- Very specific: line 1076
IMPORTANT: When modifying public API, CLI flags, or features, you MUST update the corresponding DocC documentation in Sources/xcsift.docc/.
- Distinctive: line 1090
For user: Run in a separate terminal:
≈ “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.
Files
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 releaseTesting
swift testFormatting
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 xcsiftxcsift 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.ymlor 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: writebelongs to thepackslipjob 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_minfollows the Linux build container (swift:6.3-jammy, glibc 2.35),os_minfollows.macOS(.v13)inPackage.swift. Change them with either, and add an[[artifact]]entry with a new platform. packslip readslibsfrom 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/xcsiftat the tagged commit.PluginFilesTestskeepsskills/xcsift/SKILL.mdequal toSharedTemplates.skillMarkdown, whichinstall-codexandinstall-cursorwrite, 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 --uninstallXcode'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 pluginCodex:
xcsift install-codex # Install skill
xcsift uninstall-codex # Remove skillCursor:
xcsift install-cursor # Install hooks (project-level)
xcsift install-cursor --global # Install hooks (global)
xcsift uninstall-cursor # Remove hooksAfter 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 valuesArchitecture
The codebase follows a modular architecture:
Core Components
- main.swift - Entry point using Swift ArgumentParser
- Reads stdin through
StreamingLineReaderand coordinates parsing/output - Outputs JSON or TOON format (controlled by
--format/-fflag)
- Reads stdin through
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
- OutputParser.swift - Core parsing logic
StreamingOutputParseraccumulates events line-by-line;OutputParserwraps it for complete inputOutputParserclass 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
RegisterWithLaunchServicesandValidatelines
2b. MCP/ (MCP proxy) - xcsift mcp, an MCP server that fronts another Xcode MCP server
MCPCommand.swift: themcpsubcommand; upstream command comes after--(.postTerminator, which keepsxcsift mcp --helpworking).validate()refuses an uncompilable--build-tool-patternand out-of-range limits, so nothing fails open at runtimeMCPProxyRunner.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 —Processis 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 messageMCPProxySession.swift: protocol-aware routing — tracks in-flight ids in a lock-guardedPendingRequestTable(the session itself is immutable), rewrites matching results, adds atoolscapability toinitializewhen the server declares none, and advertises and serves the injectedxcsift_parse_build_logtool. Everything else is forwarded byte for byte. Declaring that capability makes the listing the proxy's to answer: it servestools/listitself, and — because the two pumps have no ordering between them, so the client's request can overtake the initialize response — also answers a-32601rejection oftools/listwith the injected tool. Any other error is still the server's to reportMCPMessageFramer.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-encodedBuildOutputSifter.swift: decides what happens to one text block (Outcomecarries a replacement, appended blocks and stderr notes).ToolTrustsays 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 readXcodeTestResults.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 unlessTotal Resultsand 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.
BuildOutputSifterparses it once and passes the value toBuildLogReference.logPaths(in:json:homeDirectory:)andenumeratesTestResults(_:) 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(inBuildOutputSifter.swift): every default the flags and the types share, so a documented default lives in one placeInstall/MCPServerInstaller.swift:--install/--uninstall, throughclaude mcp addandclaude mcp removerather than by editing JSON. The registration records the same argument list--print-configprints (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), andquiet/exit_on_failure, which belong to neither and are the pipeline's own. What a consumer is handed says what it can do:ResultRenderertakes aRenderConfig, the MCP proxy takes both halves and never seesquietorexit_on_failure— the two values documented as meaningless over MCP, now by construction SiftingOptionsis an@OptionGroupdeclared by both the root command andmcp. This is required, not cosmetic: ArgumentParser lets the root command consume its own options wherever they appear, so a subcommand that re-declares--warningsnever sees it. Sharing oneParsableArgumentstype makes the root's parsed value flow to the subcommand.ResultRendererencodes aBuildResultas JSON/TOON/annotations for both modes
- CoverageParser.swift - Code coverage parsing
CoverageParserstruct 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
- FileSystemProtocol.swift & ShellRunnerProtocol.swift - Dependency injection
- Protocols for file system and shell command abstraction
- Enable mocking in tests to avoid slow I/O operations
- Configuration.swift, ConfigLoader.swift, ConfigMerger.swift - Configuration file support
Configurationstruct (Codable) for TOML config file parsingConfigLoaderhandles file discovery and parsing with user-friendly errorsConfigMergermerges config file values with CLI arguments (CLI takes precedence)- Uses swift-toml library for TOML parsing
Data Flow
- Stdin input →
readStandardInput() - Raw text →
OutputParser.parse()→ line-by-line regex matching - Parsed data →
BuildResultstruct - 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.withoutIndentationstrips that whitespace from parsed file paths — otherwise every reported path is unopenable. - Suite completions repeat (inline, under
Summary:, sometimes again) with identical millisecond timestamps.LineParserkeys 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.swiftuses.xctestsuite 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:
LineParsertallies✔ Test "…" passed after …by test name (Xcode repeats whole blocks) and expandswith 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
startedfor 34 Swift Testing tests and an outcome for 29.summary.unreported_testscarries 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 namedTest 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\nas a singleCharacter.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, andBuildLogReference. - A non-finite duration (
Double("inf")parses) cannot be encoded, and would turn a finished build into an encoding error.LineParser.finiteDurationdrops it.
Multi-line Context Pattern
LineParser.processLinesees one line at a time, pluslookBackBuffer: the last three non-blank lines it processed, each marked with whether a parser claimed it. Every line passes throughprocessLineexactly once, in order, whichever feed path delivered it.- Look-ahead is
pendingRecordedIssueLine, held until the next line arrives - Existing examples: look-back for
PhaseScriptExecutioncontext and for failed build commands, look-ahead for Swift Testing#expectcomments failedTestsare 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.sourceContextOpentracks 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 codebecomes a.commandFailedevent 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 testrestates the failures that stopped it underTesting failed:.seenFailedCommandsrecognises those, includingPhaseScriptExecution, and drops them.- A success marker vouches for the failures before it:
failedCommandsSinceSuccessMarkerresets on every marker, andStreamingOutputParser.finishreports that many failed commands from the end. Command PhaseScriptExecution failedis a plain.errorand is always reported.
- 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
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(intypefield) - 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
--warningsflag (no separate flag needed)
- Format:
- 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 codeand 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 theTest Case '-[…]' failedline 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 carryXCTAssertTrue failed, soLineParserskips them before any parser (the.expectedFailurecandidate bit). An unmet strict expectation (error: … : Expected failure '…' but none recorded) is a real failureXCTSkip: XCTest counts a skipped test as executed (Executed 10 tests, with 1 test skipped and 5 failures).LineParsersubtracts 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)
detailsline:U+100135 (macOS) /↳U+21B3 (Linux) — carries#expectcustom commentsfailline: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
- XCTest failure line:
- 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
RegisterWithLaunchServicesandValidatelines to extract executable targets (path, name, target) - Build Info: Unified per-target phases, timing, and dependencies
- Enabled with
--build-infoflag - 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_targetsarray - 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 insummary.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_onarray for each target (omitted when empty)
- Enabled with
- Code Coverage with Auto-Conversion: Automatically converts coverage files to JSON when
--coverageflag 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
.profrawfiles, locates test binary, runsllvm-profdata mergeandllvm-cov export.profraw→.profdata→ JSON (fully automatic)
- xcodebuild auto-conversion: Finds
.xcresultbundles, runsxcrun 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
- SPM:
- 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
testname anddurationin seconds
- Enabled with
- 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
FailedTeststruct for failed tests - Tracked internally for passed tests (used for slow/flaky detection)
- Duration included in
- xcbeautify Input Parsing: Opt-in
--xcbeautifyflag 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/✖ Errorare 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
Testin xcbeautify's rendering, and XCTest'sExecuted …totals do not include it.LineParser.recordingXcbeautifySwiftTestingResultcounts 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 itsrecorded an issueline. 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 whenGITHUB_ACTIONSis set. The path is not escaped, solineandcolare read from the end. That renderer writes a failing test as::errortoo: an indented message (XCTest, parallel) or one that ends inissue(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.didEmitXcbeautifyHintproperty (private(set))
- Parses
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:
- Create the file in
Tests/XCSiftCoreTests/Fixtures/ - Add to
Package.swiftresources:.copy("Fixtures/your-file.txt") - 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:
safegives a warning, CLIdisabledsilences 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 theLineParserandTrackingLineParsercontract 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 reportingMCPSifterTests: 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 throughMCPProxySessionTests: 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 evictionMCPCommandTests: the configuration snippet (completeness, escaping, terminators), every validation refusal, the deprecated key folding flags (they parse, the snippet drops them), andMCPServerInstallerTests— theclaude mcpcommands built for--install/--uninstall, their shell quoting, and the taken-name and never-registered casesMCPProxyEndToEndTests: 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)
- ASCII and emoji error/warning markers (
Run individual tests:
swift test --filter OutputParserTests.testParseErrorDependencies
- 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 returnnilon 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)— useFileHandle.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-jammycontainers). 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
varin a@Sendableclosure is rejected by strict concurrency. For shared mutable state across@Sendableclosures (e.g.Pipe.readabilityHandler,DispatchQueue.async,DispatchSourceTimerevent handlers), wrap the state in afinal class … @unchecked Sendableand gate every read/write with anNSLock.
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
--coverageflag is used):{"summary": {"coverage_percent": X.X, ...}} - Detailed warnings list (with
--warningsflag):{"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"]}]}
- Undefined symbols:
- Default behavior (without flag): Only shows warning count in summary, omits detailed warnings array to reduce token usage
- Quiet mode (with
--quietor-qflag): Produces no output when build succeeds with zero warnings and zero errors - Coverage data (with
--coverageflag):- Summary-only mode (default - token-efficient): Only includes coverage percentage in summary
{ "summary": { "coverage_percent": 85.5 } } - Details mode (with
--coverage-detailsflag): 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
- Summary-only mode (default - token-efficient): Only includes coverage percentage in summary
- Executable targets (with
--executableor-eflag): 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-infoflag): 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 insummary.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
phasesfield, targets without dependencies won't havedepends_onfield, noslowest_targetswhen 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:
| Environment | Format Flag | Output |
| Local | (none) | JSON |
| Local | -f json | JSON |
| Local | -f toon | TOON |
| Local | -f github-actions | Annotations only |
| CI | (none) | JSON + Annotations |
| CI | -f json | JSON + Annotations |
| CI | -f toon | TOON + Annotations |
| CI | -f github-actions | Annotations 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 warningsAnnotations 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-actionsConfiguration 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
.xcsift.tomlin current working directory~/.config/xcsift/config.tomlin home directory
If no config file is found, xcsift uses CLI defaults.
CLI Flags
--init- Generate a.xcsift.tomltemplate 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 jsonBoolean 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 StringDocumentation 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 structureMCPProxy.md-xcsift mcpreferenceGettingStarted.md- Installation and basic usageUsage.md- CLI flags and options referenceOutputFormats.md- JSON/TOON/GitHub Actions format detailsCodeCoverage.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 xcsiftOpens 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.
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
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.

