> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/ai-coding-tool-integrations/custom-ai-tool-integrations.md). # Custom AI tool integrations Read more about Swarmia's other [AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations.md) and [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools.md). Swarmia has built-in integrations for [GitHub Copilot](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration.md), [Cursor](/settings/integrations/ai-coding-tool-integrations/cursor-integration.md), and [Claude Code](/settings/integrations/ai-coding-tool-integrations/claude-code-integration.md). For any other AI coding tool, you can create a custom integration, so it shows up alongside the built-in ones in [AI adoption](/features/ai-tools/ai-adoption.md) and [AI tool detection and filters](/features/ai-tools/ai-tool-detection-and-filters.md). ## How it works You define a custom AI tool in Swarmia, then push daily per-user usage data to it from your own scripts or systems. For each user and day, report both whether they had access to the tool (`is_enabled`) and whether they actively used it (`is_active`) — that's what separates active seats from idle ones in [AI adoption](/features/ai-tools/ai-adoption.md). You can also send optional details like message counts, subscription tiers, spend, and breakdowns by model, client, or programming language. Swarmia stores this detail, but it isn't visible in the app yet. Swarmia matches each record to an author by email. It stores the usage as daily metrics, and sending the same user, tool, and date again overwrites the previous values, so you can safely re-send a day's data. Because the data is daily and not tied to individual commits, pull requests are attributed to a custom AI tool using [time-based (low-confidence) attribution](/features/ai-tools/ai-tool-detection-and-filters.md#local-changes-editor-cli): a pull request counts as assisted when its commit author used the tool within the previous 24 hours. ## Add a custom AI tool You need the [organization admin](/settings/organization/managing-users-and-roles.md) role to manage integrations. 1. Go to [Settings → AI tools](https://app.swarmia.com/settings/ai-assistants) and find the **Other AI tools** section. 2. Click **Add new**. 3. Enter a **Name** (shown in reports) and an **API identifier** (`aiService` in the [additional AI integrations API](/settings/integrations/swarmia-apis/additional-ai-integrations.md)). The identifier can't be changed after creation. 4. Click **Save**. The tool's row shows when Swarmia last received data for it. You don't need to create it in advance, since posting data for a new identifier creates the tool automatically. To rename a tool or delete it, click the edit icon on its row. Deleting a tool also removes all of its usage data. ## Send usage data Usage data is submitted to the [additional AI integrations API](/settings/integrations/swarmia-apis/additional-ai-integrations.md), which authenticates with an API token. Generate one with the **AI Usage** scope in [Settings → API tokens](https://app.swarmia.com/settings/api-tokens). The API reference documents the endpoint, the full request schema, and every field you can report. ## Frequently asked questions ### How is this different from the built-in integrations? The [GitHub Copilot](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration.md), [Cursor](/settings/integrations/ai-coding-tool-integrations/cursor-integration.md), and [Claude Code](/settings/integrations/ai-coding-tool-integrations/claude-code-integration.md) integrations fetch data for you once you connect them. With a custom AI tool, you're responsible for collecting the usage data from your tool and pushing it to Swarmia through the API. ### Where does the data show up? In [AI adoption](/features/ai-tools/ai-adoption.md), alongside the built-in tools, once the tool has received user data. The tool also appears in [AI tool detection and filters](/features/ai-tools/ai-tool-detection-and-filters.md), where pull requests are attributed to it through [time-based (low-confidence) attribution](/features/ai-tools/ai-tool-detection-and-filters.md#local-changes-editor-cli). ### Can I backfill historical data? Yes, you can send data for any dates via the [additional AI integrations API](/settings/integrations/swarmia-apis/additional-ai-integrations.md). ### Can I add custom coding agents or review agents? Support for custom [coding agents](/features/ai-tools/cloud-agents.md) and [review agents](/features/ai-tools/review-agents.md) is coming soon. You'll be able to set them up by configuring their authors, without sending data through the API. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.swarmia.com/settings/integrations/ai-coding-tool-integrations/custom-ai-tool-integrations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.