Running a Scan

Set up with your agent

The recommended way to set up Periphery is with your coding agent and the Periphery skills. Install the skills from your project directory:

npx skills add periphery-pro/skills

Then ask your agent to set up Periphery for your project with the periphery-scan-setup skill. The agent installs or updates Periphery, helps you sign in, works out the right options for your project with you, saves them to a .periphery.yml configuration file, and runs your first scan. Once Periphery is set up, ask your agent to run a scan whenever you want to find and remove unused code. See Removing Unused Code.

Note

To learn more about npx skills, see skills.sh.

Set up manually

To set up without an agent, install Periphery, sign in, and start the guided setup from your project directory:

periphery scan --setup

The guided setup detects your project type and configures a few options. After answering a few questions, Periphery prints the full scan command and runs it.

The guided setup is intended to get you started. Run periphery help scan to see all available scan options.

How a scan works

Periphery builds your project to generate an index store, combines it with information parsed from the source files, and maps the relationships between declarations. It then reports declarations that cannot be reached from the project’s entry points.

Tip

The index store only contains information about source files in the build targets compiled during the build phase. If a given class is only referenced in a source file that was not compiled, then Periphery will identify the class as unused. It’s important to ensure you build all the targets you expect to contain references. For an Xcode project, this is controlled using the --schemes option. For a Swift package, all targets are built automatically.

If your project consists of one or more standalone frameworks that do not also contain some kind of application that consumes their interfaces, you need to tell Periphery to assume that all public declarations are used with the --retain-public option.

For projects that are mixed Objective-C & Swift, it’s highly recommended you read about the implications this can have on your results.

Next Steps

Once you’ve settled upon the appropriate options for your project, persist them in a YAML configuration file so you can simply run periphery scan. See Configuration for the full list of options, and Removing Unused Code for guidance on removing code.

To use Periphery in CI, see Continuous Integration. If your project already contains a lot of unused code, Baselines let you report only newly introduced results.