# Technical Documentation: github/CopilotForXcode > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/github/CopilotForXcode) ### Overview (`README.md`) # GitHub Copilot for Xcode [GitHub Copilot](https://github.com/features/copilot) for Xcode is the leading AI coding assistant for Swift, Objective-C and iOS/macOS development. It delivers intelligent Completions, Chat, and Code Review—plus advanced features like Agent Mode, Next Edit Suggestions, MCP Registry, and Copilot Vision to make Xcode development faster and smarter. > [!IMPORTANT] > Starting from version v0.50.0, we have added internal support for the upcoming usage-based billing experience, including experience updates to the usage panel, usage notifications, and model picker. These changes will become visible once usage-based billing is rolled out. > > To ensure compatibility with the new billing experience, we strongly recommend upgrading to the latest plugin version as soon as possible: > > * **GitHub Copilot for Xcode: v0.50.0 or later** > > Clients using older plugin versions will continue to function. However, the billing and usage experience may not be optimal and may not accurately reflect the latest usage-based billing experience. ## Chat GitHub Copilot Chat provides suggestions to your specific coding tasks via chat. Chat of GitHub Copilot for Xcode ## Agent Mode GitHub Copilot Agent Mode provides AI-powered assistance that can understand and modify your codebase directly. With Agent Mode, you can: - Get intelligent code edits applied directly to your files - Run terminal commands and view their output without leaving the interface - Search through your codebase to find relevant files and code snippets - Create new files and directories as needed for your project - Get assistance with enhanced context awareness across multiple files and folders - Run Model Context Protocol (MCP) tools you configured to extend the capabilities Agent Mode integrates with Xcode's environment, creating a seamless development experience where Copilot can help implement features, fix bugs, and refactor code with comprehensive understanding of your project. ## Code Completion You can receive auto-complete type suggestions from GitHub Copilot either by starting to write the code you want to use, or by writing a natural language comment describing what you want the code to do. Code Completion of GitHub Copilot for Xcode ## Requirements - macOS 13+ - Xcode 14+ - A GitHub account ## Getting Started 1. Install via [Homebrew](https://brew.sh/): ```sh brew install --cask github-copilot-for-xcode ``` Or download the `dmg` from [the latest release](https://github.com/github/CopilotForXcode/releases/latest/download/GitHubCopilotForXcode.dmg). Drag `GitHub Copilot for Xcode` into the `Applications` folder:

Screenshot of opened dmg

Updates can be downloaded and installed by the app. 1. Open the `GitHub Copilot for Xcode` application (from the `Applications` folder). Accept the security warning.

Screenshot of MacOS download permission request

1. A background item will be added to enable the GitHub Copilot for Xcode extension app to connect to the host app. This permission is usually automatically added when first launching the app.

Screenshot of background item

1. Three permissions are required for GitHub Copilot for Xcode to function properly: `Background`, `Accessibility`, and `Xcode Source Editor Extension`. For more details on why these permissions are required see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md). The first time the application is run the `Accessibility` permission should be requested:

Screenshot of accessibility permission request

The `Xcode Source Editor Extension` permission needs to be enabled manually. Click `Extension Permission` from the `GitHub Copilot for Xcode` application settings to open the System Preferences to the `Extensions` panel. Select `Xcode Source Editor` and enable `GitHub Copilot`:

Screenshot of extension permission

1. After granting the extension permission, open Xcode. Verify that the `Github Copilot` menu is available and enabled under the Xcode `Editor` menu.

Screenshot of Xcode Editor GitHub Copilot menu item

Keyboard shortcuts can be set for all menu items in the `Key Bindings` section of Xcode preferences. 1. To sign into GitHub Copilot, click the `Sign in` button in the settings application. This will open a browser window and copy a code to the clipboard. Paste the code into the GitHub login page and authorize the application.

Screenshot of sign-in popup

1. To install updates, click `Check for Updates` from the menu item or in the settings application. After installing a new version, Xcode must be restarted to use the new version correctly. New versions can also be installed from `dmg` files downloaded from the releases page. When installing a new version via `dmg`, the application must be run manually the first time to accept the downloaded from the internet warning. 1. To avoid confusion, we recommend disabling `Predictive code completion` under `Xcode` > `Preferences` > `Text Editing` > `Editing`. 1. Press `tab` to accept the first line of a suggestion, hold `option` to view the full suggestion, and press `option` + `tab` to accept the full suggestion. ## How to use Chat Open Copilot Chat in GitHub Copilot. - Open via the Xcode menu `Xcode -> Editor -> GitHub Copilot -> Open Chat`.

Screenshot of Xcode Editor GitHub Copilot menu item

- Open via GitHub Copilot app menu `Open Chat`.

Screenshot of GitHub Copilot menu item

## How to use Code Completion Press `tab` to accept the first line of a suggestion, hold `option` to view the full suggestion, and press `option` + `tab` to accept the full suggestion. ## License This project is licensed under the terms of the MIT open source license. Please refer to [LICENSE.txt](./LICENSE.txt) for the full terms. ## Privacy We follow responsible practices in accordance with our [Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement). To get the latest security fixes, please use the latest version of the GitHub Copilot for Xcode. ## Support We’d love to get your help in making GitHub Copilot better! If you have feedback or encounter any problems, please reach out on our [Feedback forum](https://github.com/github/CopilotForXcode/discussions). ## Acknowledgements Thank you to @intitni for creating the original project that this is based on. Attributions can be found under About when running the app or in [Credits.rtf](./Copilot%20for%20Xcode/Credits.rtf). --- ### Docs BYOK (`Docs/BYOK.md`) # Adding your API Keys with GitHub Copilot - Bring Your Own Key(BYOK) Copilot for Xcode supports **Bring Your Own Key (BYOK)** integration with multiple model providers. You can bring your own API keys to integrate with your preferred model provider, giving you full control and flexibility. Supported providers include: - Anthropic - Azure - Gemini - Groq - OpenAI - OpenRouter ## Configuration Steps To configure BYOK in Copilot for Xcode: - Open the Copilot chat and select “Manage Models” from the Model picker. - Choose your preferred AI provider (e.g., Anthropic, OpenAI, and Azure). - Enter the required provider-specific details, such as the API key and endpoint URL (if applicable). | Model Provider | How to get the API Keys | |-------------------|------------------------------------------------------------------------------------------------------------| | Anthropic | Sign in to the [Anthropic Console](https://console.anthropic.com/dashboard) to generate and retrieve your API key. | | Gemini (Google) | Sign in to the [Google Cloud Console](https://aistudio.google.com/app/apikey) to generate and retrieve your API key. | | Groq | Sign in to the [Groq Console](https://console.groq.com/keys) to generate and retrieve your API key. | | OpenAI | Sign in to the [OpenAI’s Platform](https://platform.openai.com/api-keys) to generate and retrieve your API key. | | OpenRouter | Sign in to the [OpenRouter’s API Key Settings](https://openrouter.ai/settings/keys) to generate your API key. | | Azure | Sign in to the [Azure AI Foundry](https://ai.azure.com/), go to your [Deployments](https://ai.azure.com/resource/deployments/), and retrieve your API key and Endpoint after the deployment is complete. Ensure the model name you enter matches the one you deployed, as shown on the Details page.| - Click "Add" button to continue. - Once saved, it will list available AI models in the Models setting page. You can enable the models you intend to use with GitHub Copilot. > [!NOTE] > Please keep your API key confidential and never share it publicly for safety. --- ### Docs CustomInstructions (`Docs/CustomInstructions.md`) # Use custom instructions in GitHub Copilot for Xcode Custom instructions enable you to define common guidelines and rules that automatically influence how AI generates code and handles other development tasks. Instead of manually including context in every chat prompt, specify custom instructions in a Markdown file to ensure consistent AI responses that align with your coding practices and project requirements. You can configure custom instructions to apply automatically to all chat requests or to specific files only. Alternatively, you can manually attach custom instructions to a specific chat prompt. > [!NOTE] > Custom instructions are not taken into account for code completions as you type in the editor. ## Type of instructions files GitHub Copilot for Xcode supports two types of Markdown-based instructions files: * A single [`.github/copilot-instructions.md`](#use-a-githubcopilotinstructionsmd-file) file * Automatically applies to all chat requests in the workspace * Stored within the workspace or global * One or more [`.instructions.md`](#use-instructionsmd-files) files * Created for specific tasks or files * Use `applyTo` frontmatter to define what files the instructions should be applied to * Stored in the workspace Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. Reference specific context, such as files or URLs, in your instructions by using Markdown links. ## Custom instructions examples The following examples demonstrate how to use custom instructions. For more community-contributed examples, see the [Awesome Copilot repository](https://github.com/github/awesome-copilot/tree/main).
Example: General coding guidelines ```markdown --- applyTo: "**" --- # Project general coding standards ## Naming Conventions - Use PascalCase for component names, interfaces, and type aliases - Use camelCase for variables, functions, and methods - Use ALL_CAPS for constants ## Error Handling - Use try/catch blocks for async operations - Always log errors with contextual information ```
Example: Language-specific coding guidelines Notice how these instructions reference the general coding guidelines file. You can separate the instructions into multiple files to keep them organized and focused on specific topics. ```markdown --- applyTo: "**/*.swift" --- # Project coding standards for Swift Apply the [general coding guidelines](./general-coding.instructions.md) to all code. ## Swift Guidelines - Use Swift for all new code - Follow functional programming principles where possible - Use interfaces for data structures and type definitions - Use optional chaining (?.) and nullish coalescing (??) operators ```
Example: Documentation writing guidelines You can create instructions files for different types of tasks, including non-development activities like writing documentation. ```markdown --- applyTo: "docs/**/*.md" --- # Project documentation writing guidelines ## General Guidelines - Write clear and concise documentation. - Use consistent terminology and style. - Include code examples where applicable. ## Grammar * Use present tense verbs (is, open) instead of past tense (was, opened). * Write factual statements and direct commands. Avoid hypotheticals like "could" or "would". * Use active voice where the subject performs the action. * Write in second person (you) to speak directly to readers. ## Markdown Guidelines - Use headings to organize content. - Use bullet points for lists. - Include links to related resources. - Use code blocks for code snippets. ```
## Use a `.github/copilot-instructions.md` file Define your custom instructions in a single `.github/copilot-instructions.md` Markdown file in the root of your workspace or globally. Copilot applies the instructions in this file automatically to all chat requests within this workspace. To create a `.github/copilot-instructions.md` file: 1. **Open Settings > Advanced > Chat Settings** 1. To the right of "Copilot Instructions", click **Current Workspace** or **Global** to choose whether the custom instructions apply to the current workspace or all workspaces. 1. Describe your instructions by using natural language and in Markdown format. > [!NOTE] > GitHub Copilot provides cross-platform support for the `.github/copilot-instructions.md` configuration file. This file is automatically detected and applied in VSCode, Visual Studio, 3rd-party IDEs, and GitHub.com. * **Workspace instructions files**: are only available within the workspace. * **Global**: is available across multiple workspaces and is stored in the preferences. For more information, you can read the [How-to docs](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=xcode). ## Use `.instructions.md` files Instead of using a single instructions file that applies to all chat requests, you can create multiple `.instructions.md` files that apply to specific file types or tasks. For example, you can create instructions files for different programming languages, frameworks, or project types. By using the `applyTo` frontmatter property in the instructions file header, you can specify a glob pattern to define which files the instructions should be applied to automatically. Instructions files are used when creating or modifying files and are typically not applied for read operations. Alternatively, you can manually attach an instructions file to a specific chat prompt by using the file picker. ### Instructions file format Instructions files use the `.instructions.md` extension and have this structure: * **Header** (optional): YAML frontmatter * `description`: Description shown on hover in Chat view * `applyTo`: Glob pattern for automatic application (use `**` for all files) * **Body**: Instructions in Markdown format Example: ```markdown --- applyTo: "**/*.swift" --- # Project coding standards for Swift - Follow the Swift official guide for Swift. - Always prioritize readability and clarity. - Write clear and concise comments for each function. - Ensure functions have descriptive names and include type hints. - Maintain proper indentation (use 4 spaces for each level of indentation). ``` ### Create an instructions file 1. **Open Settings > Advanced > Chat Settings** 1. To the right of "Custom Instructions", click **Create** to create a new `*.instructions.md` file. 1. Enter a name for your instructions file. 1. Author the custom instructions by using Markdown formatting. Specify the `applyTo` metadata property in the header to configure when the instructions should be applied automatically. For example, you can specify `applyTo: "**/*.swift"` to apply the instructions only to Swift files. To reference additional workspace files, use Markdown links (`[App](../App.swift)`). To modify or view an existing instructions file, click **Open Instructions Folder** to open the instructions file directory. ## Tips for defining custom instructions * Keep your instructions short and self-contained. Each instruction should be a single, simple statement. If you need to provide multiple pieces of information, use multiple instructions. * For task or language-specific instructions, use multiple `*.instructions.md` files per topic and apply them selectively by using the `applyTo` property. * Store project-specific instructions in your workspace to share them with other team members and include them in your version control. * Reuse and reference instructions files in your [prompt files](PromptFiles.md) to keep them clean and focused, and to avoid duplicating instructions. ## Related content * [Community contributed instructions, prompts, and chat modes](https://github.com/github/awesome-copilot) --- ### Docs PromptFiles (`Docs/PromptFiles.md`) # Use prompt files in GitHub Copilot for Xcode Prompt files are Markdown files that define reusable prompts for common development tasks like generating code, performing code reviews, or scaffolding project components. They are standalone prompts that you can run directly in chat, enabling the creation of a library of standardized development workflows. They can include task-specific guidelines or reference custom instructions to ensure consistent execution. Unlike custom instructions that apply to all requests, prompt files are triggered on-demand for specific tasks. > [!NOTE] > Prompt files are currently experimental and may change in future releases. GitHub Copilot for Xcode currently supports workspace prompt files, which are only available within the workspace and are stored in the `.github/prompts` folder of the workspace. ## Prompt file examples The following examples demonstrate how to use prompt files. For more community-contributed examples, see the [Awesome Copilot repository](https://github.com/github/awesome-copilot/tree/main).
Example: generate a Swift form component ```markdown --- description: 'Generate a new Swift sheet component' --- Your goal is to generate a new Swift sheet component. Ask for the sheet name and fields if not provided. Requirements for the form: * Use sheet design system components: [design-system/Sheet.md](../docs/design-system/Sheet.md) * Always define Swift types for your sheet data * Create previews for the component ```
## Prompt file format Prompt files are Markdown files and use the `.prompt.md` extension and have this structure: * **Header** (optional): YAML frontmatter * `description`: Short description of the prompt * **Body**: Prompt instructions in Markdown format Reference other workspace files, prompt files, or instruction files by using Markdown links. Use relative paths to reference these files, and ensure that the paths are correct based on the location of the prompt file. ## Create a prompt file 1. **Open Settings > Advanced > Chat Settings** 1. To the right of "Prompt Files", click **Create** to create a new `*.prompt.md` file. 1. Enter a name for your prompt file. 1. Author the chat prompt by using Markdown formatting. Within a prompt file, reference additional workspace files as Markdown links (`[App](../App.swift)`). You can also reference other `.prompt.md` files to create a hierarchy of prompts. You can also reference [instructions files](CustomInstructions.md) in the same way. To modify or view an existing prompt file, click **Open Prompts Folder** to open the prompts file directory. ## Use a prompt file in chat In the Chat view, type `/` followed by the prompt file name in the chat input field. This option enables you to pass additional information in the chat input field. For example, `/create-swift-sheet`. ## Tips for defining prompt files * Clearly describe what the prompt should accomplish and what output format is expected. * Provide examples of the expected input and output to guide the AI's responses. * Use Markdown links to reference custom instructions rather than duplicating guidelines in each prompt. ## Related resources * [Community contributed instructions, prompts, and chat modes](https://github.com/github/awesome-copilot) --- --- METRICS --- - Files Extracted: 4 - Estimated Token Budget: ~5363 tokens - Canonical Reference: https://codewiki.google/github.com/github/CopilotForXcode