What platforms are supported?

macOS with Xcode installed; swiftfindrefs must be in PATH.

What if IndexStore resolution fails?

Stop and report the error; do not guess or edit files without a complete reference set.

Can I customize the data store path?

Yes. Use the --dataStorePath flag to specify a known IndexStoreDB path and skip discovery.

swiftfindrefs

Scanned

@michaelversus

npx machina-cli add skill @michaelversus/swiftfindrefs --openclaw

Files (1)

SKILL.md

2.8 KB

SwiftFindRefs

Purpose

Use swiftfindrefs to locate every Swift source file that references a given symbol by querying Xcode’s IndexStore (DerivedData). This skill exists to prevent incomplete refactors caused by text search or heuristics.

Rules

Always run swiftfindrefs before editing any files.
Only edit files returned by swiftfindrefs.
Do not substitute grep, rg, IDE search, or filesystem heuristics for reference discovery.
Do not expand the file set manually.
If IndexStore/DerivedData resolution fails, stop and report the error. Do not guess.

Preconditions

macOS with Xcode installed
Project has been built at least once (DerivedData exists)
swiftfindrefs available in PATH

Installation

brew tap michaelversus/SwiftFindRefs https://github.com/michaelversus/SwiftFindRefs.git
brew install swiftfindrefs

Canonical command

Prefer providing --projectName and --symbolType when possible.

swiftfindrefs \
  --projectName <XcodeProjectName> \
  --symbolName <SymbolName> \
  --symbolType <class|struct|enum|protocol|function|variable>

Optional flags:

--dataStorePath <path>: explicit DataStore (or IndexStoreDB) path; skips discovery
-v, --verbose: enables verbose output for diagnostic purposes (flag, no value required)

Output contract

One absolute file path per line
Deduplicated
Script-friendly (safe to pipe line-by-line)
Ordering is not semantically meaningful

Standard workflows

Workflow A: Find all references

Run swiftfindrefs for the symbol.
Treat the output as the complete reference set.
If more detail is needed, open only the returned files.

Workflow B: Fix missing imports after moving a symbol

Use swiftfindrefs to restrict scope, then add imports only where needed.

swiftfindrefs -p <Project> -n <Symbol> -t <Type> | while read file; do
  if ! grep -q "^import <ModuleName>$" "$file"; then
    echo "$file"
  fi
done

Then for each printed file:

Insert import <ModuleName> in the imports block at the top.
Preserve existing import ordering/grouping.
Never add duplicate imports.
Do not reformat unrelated code.

Workflow C: Audit usage before deleting or renaming a symbol

Run swiftfindrefs for the symbol.
If output is empty, treat the symbol as unused (still validate via build/tests if needed).
If non-empty, review the listed files before changing public API.

References

CLI details: references/cli.md
Playbooks: references/workflows.md
Troubleshooting: references/troubleshooting.md

Source

git clone https://clawhub.ai/michaelversus/swiftfindrefsView on GitHub

Overview

SwiftFindRefs uses IndexStoreDB to enumerate every Swift source file that references a given symbol. It queries Xcode’s DerivedData to deliver a complete reference set and avoids unreliable text searches. This is essential for find references, fixing missing imports, and cross-module refactors.

How This Skill Works

The tool queries the IndexStore via swiftfindrefs, producing one absolute, deduplicated file path per line suitable for scripting. Provide the symbol name, symbol type, and project name; you can also specify a data store path or enable verbose output. If the IndexStore resolution fails, you should stop and report the error instead of guessing.

When to Use It

Before editing any files to identify all references to a symbol
After moving or renaming a symbol to fix missing imports
During cross-module refactors to scope changes precisely
When auditing usage before deleting or renaming a public API
When deterministic results are required instead of grep or IDE search

Quick Start

Step 1: Ensure macOS with Xcode installed, a built project, and swiftfindrefs in PATH
Step 2: Run swiftfindrefs with projectName, symbolName, and symbolType; optionally add --dataStorePath or -v
Step 3: Open and edit only the returned files; re-run a build/tests to validate changes

Best Practices

Always run swiftfindrefs before editing
Edit only the files returned by swiftfindrefs
Use --dataStorePath to skip discovery when a known data store exists
Deduplicate output and pipe safely; avoid manual file set expansion
Validate changes with a build/test cycle to confirm correctness

Example Use Cases

Find all references of a class across multiple modules in a large app
Fix missing imports after moving a symbol to a new module
Audit references before deleting a public API
Audit cross-module references before a module boundary refactor
Verify usages of a symbol before a wide-scale refactor

Frequently Asked Questions

Add this skill to your agents