> 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/features/swarmia-ai.md). # Swarmia AI Ask questions about engineering data and turn answers into charts and reports. Swarmia AI lets you ask questions about engineering data in plain language. It combines delivery performance, AI usage, survey feedback, and initiatives into answers, charts, and reports. You can continue the conversation, refine a result, or open it in [Explore](https://help.swarmia.com/features/metrics/explore) to edit and save it. ### Getting started Start a conversation in either place: 1. Select **Swarmia AI** in the main navigation. 2. Select **Ask Swarmia AI** in any view.
Starting from a view includes its context automatically. This helps you ask targeted questions about the data in front of you. ### Asking questions Ask in plain language. Include a team, time range, metric, or comparison when it matters. Try prompts like these: * “Give me a daily digest of team metrics. Highlight meaningful changes.” * “Visualize PR cycle time by team for the last quarter.” * “Show DORA metrics for the last 30 days. Compare them with the prior period.” * “What are our current delivery bottlenecks? What should we fix first?” * “How is AI affecting test coverage? Suggest improvements.” * “Summarize our latest survey results. Where should we improve most?” Find tested prompts for every role in the [prompt library](/guides/prompt-library.md). Swarmia AI analyzes quantitative metrics and qualitative feedback, including survey comments. It can also use the [Build book](https://www.swarmia.com/build/) to suggest next steps. To see which entities and properties you can use in a report, take a look at the [Data model](/data-model/entities.md) documentation.
### Attaching files Attach files to give Swarmia AI context that isn't in Swarmia, like a planning doc, a spreadsheet export, or a screenshot. To attach a file, select the paperclip icon in the message box, or drag files onto a conversation. Try prompts like: * "Here's our Q3 roadmap. Which of our initiatives match these goals?" * "Compare this teams and members list with the one in Swarmia and find the discrepancies." * "Summarize this retro doc and find the metrics that back it up." You can attach these file types: * **Text:** TXT, Markdown (MD), CSV, and JSON * **Images:** PNG, JPG, GIF, and WebP * **Documents:** PDF Keep in mind: * **Up to 3 files per message.** Each file can be up to 5 MB. * **Files stay in the conversation.** Swarmia AI can use them in follow-up questions. You can't download them from Swarmia. * **You can't add files when you edit a message.** Send a new message instead. ### Response format and follow-ups Responses can include: * **Summaries** — plain-language analysis and recommendations * **Tables** — breakdowns by team, person, time period, or metric * **Charts** — visualized trends and comparisons Refine any response. You can: * Ask a follow-up question. * Request a breakdown by team, author, or time period. * Add or remove data from a chart. * Open the result in **Explore** to adjust, save, and revisit it. Swarmia AI responds quickly by default. Increase the reasoning level for deeper analysis. This may take longer.
### Saving results Open any table or chart in [Explore](https://www.swarmia.com/changelog/2026-04-02-explore-view). You can adjust it with AI and save it as a custom report. ### Taking action Swarmia AI can make selected changes for you. Ask in plain language when you know what to do next. It prepares the change, asks for missing details, and shows a preview. Nothing changes until you confirm. Afterward, it shows the affected objects. You can inspect or undo the result where available. Actions use your existing permissions. Swarmia AI cannot perform actions you cannot perform yourself. Learn more about [Roles and permissions](/settings/organization/managing-users-and-roles.md).
#### Available actions * **Save a key metric.** Ask Swarmia AI to save a useful metric as a [Key metrics](/features/metrics/key-metrics.md). * **Set up a working agreement.** Ask it to “Set up [Working agreements](/features/working-agreements.md) eg: for unlinked PRs.” Swarmia AI gathers the required limits, previews the agreement, and applies it after confirmation. Notifications are included with the agreements. * **Create a custom PR view.** Ask "Create a [PR inbox](/features/managing-pull-requests-in-progress-with-the-pull-request-view.md) view for PRs in the payments repository, PRs with a certain label, and more." Swarmia AI proposes a name, icon, and filters, previews the matching PRs, and saves the view after you confirm. * **Set up** [Initiatives](/features/focus/deliver-strategic-initiatives.md)**:** Ask "Create an initiative for every Story with ‘billing API’ in the name." Swarmia AI suggests a name and scope, shows you a preview, and creates it after you confirm. * **Filter or sort a view.** Ask “Show only PRs from the Ballmer team.” Swarmia AI creates a new Explore view. Your current view stays unchanged. * **Add an annotation.** Ask Swarmia AI to explain a pull request, issue, or signal. It drafts [Notes](/features/notes.md) for you to accept, edit, or reject. AI-written annotations are marked as such. * **Change team settings.** Ask "Exclude Dependabot pull requests from the Payments team." Swarmia AI shows the current and new values side by side and saves the change after you confirm. See [what you can change](#changing-team-settings). #### What's not supported Swarmia AI cannot change organization-wide settings or rewrite historical data. ### Asking about settings Ask Swarmia AI how your organization or team is set up in Swarmia, or why some data is or isn't counted. It reads your current settings instead of guessing, and links to the settings page it refers to. Try prompts like these: * "Why doesn't this pull request show up in the Payments team's metrics?" * "Which Slack channel does the Payments team get notifications in?" * "Which Jira projects and issue types do we sync?" * "Who are the team admins for the Platform team?" Swarmia AI can read these settings: * **Team settings:** [Team PR exclusions](/settings/team/team-pr-exclusions.md), [Issue ownership](/settings/team/issue-ownership.md) including the sprint board, and [Team notifications](/settings/team/team-notifications.md). * **Organization settings:** teams and team admins, authors, user roles, issue trackers, organization PR exclusions, issue linking, test file rules, investment categories, deployments, and the connection status of integrations. You see the same settings you can see in Swarmia. Swarmia AI never shows credentials, API tokens, or webhook secrets, and it doesn't read API tokens or subscription details. #### Changing team settings Swarmia AI can propose changes to these team settings: | Setting | Example request | | ---------------------------------------------------------- | ----------------------------------------------------------------------------- | | [Team PR exclusions](/settings/team/team-pr-exclusions.md) | "Exclude pull requests with the `dependencies` label from the Payments team." | | [Issue ownership](/settings/team/issue-ownership.md) | "Add the Mobile project to the Payments team's issue ownership." | | [Sprint board](/settings/team/sprints.md) | "Use the PAY Jira board for the Payments team's sprints." | | [Team notifications](/settings/team/team-notifications.md) | "Send the Payments team's daily digest at 9:00 on weekdays." | To change team settings, you need to be an organization admin, an editor, or a team admin of that team. Viewers can ask about settings, but can't change them. Learn more about [Roles and permissions](/settings/organization/managing-users-and-roles.md). Keep in mind: * **Name the team.** Swarmia AI doesn't guess which team you mean. * **One change per proposal.** If you ask for several changes, confirm each one separately. * **Changes apply to past data too.** PR exclusion and issue ownership changes affect historical and future data, including parent team rollups. Swarmia recalculates reports in the background after you confirm, so they can take a while to update. * **Parent teams have limits.** You can't change PR exclusions or issue ownership for a parent team, or assign it a sprint board. * **Set up notifications first.** If a team has never set up notifications, set them up in [team notification settings](https://app.swarmia.com/settings/team/notifications) before you ask Swarmia AI to change them. * **Proposals can go out of date.** If someone changes the setting before you confirm, the proposal fails. Ask Swarmia AI for a new one. ### Appropriate use and limitations Results depend on your available data. Missing or inconsistent data can affect accuracy. Swarmia AI identifies patterns in engineering activity. It does not measure individual productivity, performance, or competence. Its outputs can be incomplete or incorrect. Activity counts vary by project type, review load, batch size, and role. They do not show the quality or amount of an individual's contribution. Do not use outputs for individual decisions. This includes performance reviews, compensation, promotion, discipline, or termination. Use Swarmia AI for team and system insights. Apply judgment with full context. Every insight is backed by an explicit data query. Select **Explore** to inspect the query, adjust it, and rerun it. ### Sharing feedback Rate each response with 👍 or 👎. For more detailed feedback, reach out to your customer success manager or email . To ask the same questions from Claude, Cursor, or another compatible client, connect the [MCP server](/settings/integrations/mcp-server.md) --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.swarmia.com/features/swarmia-ai.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.