# Integrating with Linear Planning is where engineering teams lose the most time. This is where [**AI Architect**](/ai-architect/overview.md) starts. Senior engineers and tech leads spend hours on work that should take minutes — reading through old issues to understand what went wrong before, figuring out what a one-line ticket actually requires, mapping out which services will be affected and which ones have been fragile in the past. AI Architect automates this work inside Linear. When an issue is created, AI Architect posts a detailed implementation plan directly as a comment on the ticket. Feasibility analysis, story breakdown, risk warnings, historical patterns from your team's own issues — all generated in minutes, right where your team plans. ## What gets posted on your issue When AI Architect analyzes a Linear issue, it produces a structured Markdown implementation plan that covers: * **Feasibility assessment** — Is this viable given your current architecture? Which services are involved, and how stable are they? What's the blast radius if something goes wrong? * **Story breakdown** — A full decomposition into actionable tasks with acceptance criteria, dependencies, and recommended execution order. * **Effort estimates** — Both traditional and agentic estimates, with a breakdown of where AI tooling saves the most time and where it doesn't. * **Proactive risk detection** — Race conditions in concurrent flows, memory leak patterns, regression-prone areas, API rate-limiting gaps, security concerns. Each risk comes with a suggested mitigation drawn from your team's actual history. * **Historical pattern insights** — AI Architect references past issues to flag problems your team has already encountered. * **Open questions** — Technical decisions that need to be made before implementation begins, so they don't surface mid-sprint. The plan is in Markdown. Engineers can paste it directly into Cursor, Claude Code, or any other coding agent to start implementation with full architectural context already loaded. ## Prerequisites Before setting up the Linear integration, make sure the following are in place for your workspace: * The **AI Architect** feature is enabled. * **Linear analysis** is enabled. If either of these isn't active yet, contact the Bito team at to enable them. ## Setup {% stepper %} {% step %} ### Enable AI Architect for your workspace AI Architect can be set up using one of the following deployment options: #### Bito-hosted AI Architect is managed and maintained by Bito. * Follow the [Bito-hosted installation guide](/ai-architect/installation/install-ai-architect-bito-hosted.md) to get started. * If AI Architect isn't already active for your workspace, contact the Bito team at to enable it. #### Self-hosted AI Architect is deployed and managed within your own infrastructure. * Follow the [self-hosted installation guide](/ai-architect/installation/install-ai-architect-self-hosted.md) to set up and configure AI Architect for your workspace. {% endstep %} {% step %} ### Connect Linear 1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard. 2. In the **Available integrations** section, locate **Linear** and click **Connect**.
3. From next screen, click **Authorize with your Linear account**. This allows you to securely connect Bito to your Linear workspace using OAuth.
3. You will be redirected to Linear's authorization page. Sign in to Linear if prompted, then grant Bito access to your Linear workspace. Click **Authorize** to continue. Once authorized, Bito completes the connection automatically and redirects you back to the Bito dashboard.
{% hint style="info" %} **The user who completes this step must be a Linear workspace admin.** Linear's OAuth requires admin permissions to allow Bito to register the necessary webhooks on your behalf. If a non-admin connects, the setup will fail and you will see the following error: *"Insufficient permissions. Creating webhooks in Linear requires the 'admin' OAuth scope, which is granted only when a Linear workspace admin completes the connection. Ensure the connecting user is a workspace admin and try again."* {% endhint %} {% endstep %} {% step %} ### Select your Linear teams After connecting, Bito will display a list of teams from your Linear site that Bito has access to.
To enable or disable teams, go to [**Set up AI Architect**](https://alpha.bito.ai/home/ai-architect) page and select your deployment type.
For example, if you have selected **Self-hosted AI Architect**, then on the next screen click **Configure AI Architect**.
A settings screen will appear. From there, open the **Linear** tab, where you can select the Linear teams you want Bito to listen to and enable them using the toggle switch.
Only issues and comments from selected Linear teams will trigger AI Architect analysis, events from unselected teams are ignored. * You can update your team selection at any time. * Saving an empty selection effectively pauses Bito for that workspace without fully disconnecting. {% hint style="info" %} Teams in Linear are the equivalent of projects in Jira, they are the persistent scoping unit for which events Bito will act on. {% endhint %} {% endstep %} {% step %} ### Enable the feature flags Two flags control how AI Architect behaves on your Linear issues. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to enable them. | Flag | What it enables | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Linear Analysis Enabled** | Trigger on-demand analysis using `@bito`, `/bito`, or `#bito` in comments. Alternatively, add the labels `bito`, `bito-analyse`, or `bito-analyze` to the issue. | | **Linear Auto Analysis Enabled** | Automatically triggers analysis when a Linear issue is created or updated. | {% hint style="info" %} Start with **Linear Analysis Enabled** if you want to try it manually first, then enable auto-analysis when you're ready to run it on all new issues. {% endhint %} {% endstep %} {% endstepper %} ## How to trigger AI Architect in Linear #### Automatic analysis When enabled, AI Architect listens for new or updated issues in your selected teams and posts an implementation plan automatically — no action needed from the issue creator. {% hint style="info" %} Requires the **Linear Auto Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at to enable it. {% endhint %} {% hint style="info" %} You can download the plan (as a Markdown file) and use it in your agentic tools (Cursor, Claude Code, etc.) to further refine it or begin implementation. {% endhint %} #### On-demand analysis Trigger analysis manually on any issue by adding one of the following in a Linear comment: ``` @bito /bito #bito ``` {% hint style="info" %} You can use `@bito`, `/bito`, or `#bito` to ask Bito to update the analysis, refine the plan based on new information, or focus on a specific concern. **Example:** ``` @bito analyze technical feasibility ``` {% endhint %} Or by adding one of these labels to the issue: ``` bito bito-analyse bito-analyze ``` {% hint style="info" %} Requires the **Linear Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at to enable it. {% endhint %} {% hint style="info" %} **Explicit triggers always win.** Even if auto-analysis is turned off, using `@bito` in a comment or applying a trigger label will force an analysis to run. {% endhint %} ### Auto triage By default, when auto-analysis is enabled, AI Architect generates a plan for every new or updated issue in your selected Linear teams. Auto triage adds a layer of intelligence before that happens: it evaluates whether an issue actually needs a detailed implementation plan, and skips generating one if it doesn't. This keeps your issues clean and avoids generating plans for work that is already well-defined or straightforward enough to implement without one. {% hint style="info" %} **Note:** Only events from your selected Linear teams are processed. Events from unselected teams are filtered out before reaching auto triage. {% endhint %} #### How auto triage works When an issue is created or updated, AI Architect reads the full ticket — title, description, and comments — and assigns a complexity score from **1 to 10**. | Score | What happens | | :--------------------------------: | ------------------------------------------------------------ | | **Below threshold (default: `7`)** | Plan is skipped. An optional comment is posted on the issue. | | **At or above threshold** | Implementation plan is generated as usual. | When an issue is below the threshold, AI Architect posts the following comment: > **AI Architect** — This issue doesn't appear to need a detailed implementation plan based on its scope and complexity. If you'd like one anyway, type @Bito with what you want (example: `@Bito technical plan`) {% hint style="info" %} Once a plan or skip notification has been posted on an issue, auto triage will not re-trigger automatically on subsequent updates. To request a new plan, use `@bito`, `/bito`, or `#bito` directly on the issue. {% endhint %} {% hint style="info" %} **Note:** AI Architect can perform live web research to incorporate up-to-date technical context into its evaluation and plan generation. {% endhint %} #### Supported attachment formats When evaluating a ticket, AI Architect can read attachments in the following formats: * `.pdf` * `.docx` * `.xlsx` * `.csv` * `.json` * `.yaml` * `.zip` {% hint style="warning" %} SVG files are supported as images only. Binary image attachments (`.png`, `.jpg`, `.gif`, `.webp`) are not yet supported, full image support is coming soon. {% endhint %} #### Configuration The following settings control how auto triage behaves for your workspace. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to configure these. | Setting | Options | Description | | :----------------------: | ------------------ | ----------------------------------------------------------------------------------------------- | | **Complexity threshold** | Default: `7` | Minimum score required for a plan to be generated. | | **Auto analysis type** | `plan` / `comment` | Whether to generate a full plan or post a guidance comment when an issue is created or updated. | ## What AI Architect knows about your team AI Architect draws on multiple sources when it analyzes an issue: **Your codebase** — All your repositories, services, API endpoints, modules, and design patterns are indexed into a knowledge graph. AI Architect understands how your system fits together, not just what individual files contain. **Your Linear history** — AI Architect analyzes your team's past issues and categorizes recurring patterns: race conditions across subsystems, services with instability histories, security and credential issues, error handling gaps, API rate-limiting problems. This context is applied to every new issue so your team doesn't repeat what's already been learned. **Other context sources** — AI Architect also incorporates insights from Jira tickets, Confluence documents, observability data, and any custom instructions you provide. [**Learn how Bito builds the knowledge graph**](/ai-architect/knowledge-graph.md) ## Agent skills power the Linear integration AI Architect works through purpose-built agentic skills. The same skills that run on Jira issues are used for Linear, delivering full feature parity: **bito-epic-to-plan** — Converts a high-level issue or PRD into a sprint-ready plan with multiple architectural approaches, then granular tasks with effort estimates and acceptance criteria. **bito-scope-to-plan** — Auto-scales its output — a full multi-workstream plan for complex issues, a focused single-workstream plan for simpler ones. [**See all available skills**](/ai-architect/agent-skills.md) ## Disconnecting Linear To disconnect, navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page and disconnect Linear from there. Bito will automatically clean up the integration — removing the webhook from your Linear workspace, clearing your team selection, and revoking stored credentials. ## Error messages The following messages may appear if something goes wrong with your Linear integration. | Situation | Message | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Integration is no longer valid (token revoked or expired) | "Your Linear integration is no longer valid. To continue, please disconnect and reconnect your Linear workspace." | | Bito's access in Linear was revoked by an admin | "Access for the Bito Linear app was revoked. Please disconnect and reconnect the integration to avoid disruptions." | | Connecting user wasn't a Linear workspace admin | "Insufficient permissions. Creating webhooks in Linear requires the 'admin' OAuth scope, which is granted only when a Linear workspace admin completes the connection. Ensure the connecting user is a workspace admin and try again." | | Generic / unknown failure | "Something went wrong. Please try again later. If the issue persists, check your Linear settings or contact support." | --- # Agent Instructions: 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: ``` GET https://docs.bito.ai/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-linear.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.