How to use SwiftFairy

Install and open the app

Download the current macOS release, move SwiftFairy to Applications, and open it. SwiftFairy requires an Apple silicon Mac; check the release page for the minimum macOS version.

The first-run setup introduces Scrolls, offers trial activation, and detects supported coding agents. You can revisit agent connections later in Settings → Integrations.

Activate Scroll access

Scrolls are the domain-specific reference material SwiftFairy uses for matching. Each Scroll needs an active license or trial before your agent can use its guidance.

Start a trial

In the library, select a Scroll and choose Start Free Trial. Each Scroll has a one-day trial. No payment information is required.

Use a purchased license

Select the Scroll in the library, choose Enter Product Key, paste the key from your purchase, and choose Unlock.

Check or recover access

Open Settings → Licenses to see active licenses, trials, and saved license codes. Use Refresh Licenses after a purchase or renewal. If you no longer have your key, choose Retrieve a License Code or use the request-access page.

Keep Scrolls current

Use Check for Scroll Updates in the library toolbar. When an update is available, follow the action shown on the Scroll card. SwiftFairy installs licensed Scroll updates from its server where supported.

Connect a coding agent

During setup, SwiftFairy detects installed agents and can connect them. Later, open Settings → Integrations and choose Install beside an agent. The connection guide covers Codex, Claude Code, Cursor desktop and CLI, and Gemini CLI.

After connecting, start a new agent conversation so it loads the SwiftFairy server. For Codex, restart Codex and then start a new task.

Use SwiftFairy with your agent

Ask for it on a specific task

Once the agent is connected, you can call out SwiftFairy in a prompt: “Use SwiftFairy to check the relevant APIs before implementing this change, then review the Swift code you changed.” You can also ask for a review of an existing diff or a broader codebase audit.

Add a standing project instruction

For ongoing development, add an instruction to your repository's agent configuration: AGENTS.md for Codex or Cursor, CLAUDE.md for Claude Code, or GEMINI.md for Gemini CLI. This gives the agent a reason to consult SwiftFairy during implementation, without repeating the request in each task.

When working on Swift or SwiftUI code, consult SwiftFairy for relevant API, framework, or domain guidance and examples before making changes. Audit the affected code with SwiftFairy after meaningful edits. Read the cited guidance and assess findings against the project context before applying them.

SwiftFairy's guidance queries can surface scoped examples and domain knowledge before implementation. Its audits check Swift code against your active Scrolls and return relevant findings and API requirements. The agent decides when to call these tools; the project instruction makes that workflow explicit.

Treat findings as review input: check the reported evidence and applicability against the surrounding code, then decide what to change. SwiftFairy distinguishes requirements from recommendations and considerations.

If an agent cannot reach SwiftFairy, check its status in Settings → Integrations and reinstall the integration if the app reports that it needs repair.