SwiftFairy guide

Connecting coding agents

Install the integration from SwiftFairy's macOS app, then start a new conversation in the agent. These instructions cover Codex, Claude Code, Cursor desktop and CLI, and Gemini CLI.

Before connecting

Install SwiftFairy in Applications and complete its first-run setup. Open Settings → Integrations to see detected agents and each connection's status. An agent that has not been found on this Mac appears under Not found on this Mac.

The Codex, Claude Code, and Cursor integrations install plug-ins; Gemini CLI installs an extension. Each includes usage guidance and a connection to SwiftFairy's local MCP server.

Keep the SwiftFairy plug-in or extension enabled in the agent you use. Other installed plug-ins do not need to be disabled.

Codex

In SwiftFairy, open Settings → Integrations and choose Install beside Codex. SwiftFairy must be able to find a Codex installation on this Mac.

The installer registers a local SwiftFairy marketplace and installs the SwiftFairy Codex plug-in. The plug-in provides usage guidance and registers the bundled local MCP server.

Find the plug-in in Codex

Open the Plugins Directory in Codex and select the nilcoalescing-swiftfairy marketplace. SwiftFairy should appear as installed and enabled. If it is disabled, enable it, restart Codex, and start a new task. A project-specific Codex configuration can also disable a local plug-in for that project.

You can also check the installation from a terminal with codex plugin list --marketplace nilcoalescing-swiftfairy. It should list SwiftFairy as installed and enabled.

Codex plug-in documentation

Restart Codex, then start a new task. Ask Codex to use SwiftFairy to review a Swift change and report the result.

Claude Code

In SwiftFairy, open Settings → Integrations and choose Install beside Claude Code. SwiftFairy detects the Claude Code command-line tool before enabling installation.

The installer adds a local SwiftFairy marketplace and a user-scoped Claude Code plug-in. The plug-in contains usage guidance and the local MCP server connection.

Find the plug-in in Claude Code

Run /plugin and open Installed. Find SwiftFairy in the list; disabled plug-ins are grouped at the bottom. Open its details to enable it if necessary. Check the Errors tab if Claude Code reports a load failure. Start a new conversation after changing the plug-in state.

Claude Code plug-in documentation

Start a new Claude Code conversation. Ask Claude Code to review a Swift change with SwiftFairy and report the result.

Cursor

In SwiftFairy, open Settings → Integrations and choose Install beside Cursor. SwiftFairy's installer currently requires Cursor.app on this Mac, including when you plan to use Cursor CLI.

The installer adds a local Cursor Agent Plugin with SwiftFairy usage guidance and a connection to its local MCP server. The same plug-in is available to Cursor desktop and Cursor CLI.

Check Cursor desktop

Open Customize in Cursor's sidebar and check Plugins for SwiftFairy. The local plug-in is installed at ~/.cursor/plugins/local/swiftfairy. If its skill or MCP server does not appear, restart Cursor or run Developer: Reload Window. Team settings may restrict local plug-in imports.

Check Cursor CLI

Run agent mcp list in a terminal and look for the swiftfairy server. You can also run agent mcp list-tools swiftfairy to check its available tools. If the server is unavailable, start a new CLI session, then check SwiftFairy's integration status and reinstall if it reports a problem.

Cursor plug-in documentation Cursor CLI MCP documentation

In Cursor desktop, start a new Agent conversation after restarting or reloading the window. In Cursor CLI, start a new agent session. Ask it to review a Swift change with SwiftFairy and report the result.

Gemini CLI

In SwiftFairy, open Settings → Integrations and choose Install beside Gemini CLI. SwiftFairy detects the Gemini command-line tool before enabling installation.

The installer adds a Gemini CLI extension with SwiftFairy usage guidance and a local MCP server connection.

Find the extension in Gemini CLI

Run /extensions list in Gemini CLI, or gemini extensions list in a terminal. The swiftfairy extension should be enabled. If it is disabled, run gemini extensions enable swiftfairy in a terminal, then restart Gemini CLI.

Gemini CLI extension documentation

Start a new Gemini CLI conversation. Ask Gemini to review a Swift change with SwiftFairy and report the result.

Check the connection

Ask the agent to use SwiftFairy to review Swift code and report its findings or that no guidance matched. If the server is unavailable, check Settings → Integrations for a failed or repair status, then reinstall the affected integration. For Codex, restart the app before trying a new task.

Back to the How to Use guide