swiftfindrefs

What This Skill Does

The swiftfindrefs skill is a precision-oriented tool designed for developers working within the Apple ecosystem. It leverages Xcode’s IndexStoreDB to identify every source file referencing a specific Swift symbol. Unlike text-based search tools like grep or ripgrep, which rely on pattern matching and often produce false positives (e.g., matching string literals or commented-out code) or miss dynamic references, swiftfindrefs queries the compiler’s own indexing engine. This ensures that the results are semantically accurate and exhaustive, making it the mandatory tool for refactoring, dead-code elimination, and dependency management in complex Swift projects.

Installation

Ensure you have Homebrew installed on your macOS environment. Execute the following commands in your terminal to tap the repository and install the binary:

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

Alternatively, you can integrate it via the ClawHub agent platform:

clawhub install openclaw/skills/skills/michaelversus/swiftfindrefs

Use Cases

1. Safe Refactoring: When renaming a class, protocol, or function, use this tool to locate every invocation site, ensuring no breaking changes are introduced in distant modules.
2. Dependency Resolution: After moving a symbol to a new module, use the tool to identify all files requiring a new import statement.
3. Dead Code Analysis: Confirm whether a symbol is truly unused before removing it from the codebase, preventing runtime errors caused by premature deletion.
4. Impact Analysis: Identify the blast radius of changing an API signature by listing all dependent files before modification.

Example Prompts

1. "Use swiftfindrefs to find all references for the class 'UserManager' in the current project and list the files for me to review."
2. "I am moving the 'NetworkClient' struct to a new module. Find all files using this struct so I can add the necessary import statements."
3. "Run a search for the function 'processPayment(amount:)' to ensure no internal services are still relying on it before I deprecate the API."

Tips & Limitations

• Pre-build Requirement: The tool relies on DerivedData. Always perform a successful build of your project before running swiftfindrefs to ensure the IndexStore is up to date.
• Symbol Precision: Always provide the --symbolType (class, struct, enum, etc.) to improve search accuracy and resolve symbol collisions.
• File Safety: Never guess where a symbol is defined or used. Always trust the output of swiftfindrefs. If the tool reports an error, it is likely due to an outdated index; rebuild your project and retry.
• Limitations: This tool is strictly for macOS environments with Xcode installed. It is not designed for cross-platform Swift development outside of Apple's build ecosystem.