Linear AI Agent: Build a Governed Issue-Triage App
Linear's own agent can work inside the issue tracker. A custom agent needs more than issue access: durable workflow state, scoped write permissions and an audit trail. See where each belongs in a practical issue-triage design.

What is a Linear AI agent?
A Linear AI agent is software that reads, updates, summarizes or routes work in Linear. It comes in three forms: Linear's own agent, a third-party integration, or a custom app that calls the Linear API. For recurring triage, the custom app is the form that holds up in production. Routing rules, state and logs live in code. The model only handles issues the rules cannot settle.
Major is where that app gets built. An agent works out the triage logic once, builds the app that runs it, and from then on the repeatable steps run as deterministic code with scoped credentials and an audit trail. Reason once. Run forever.
Linear Agent, integrations and a Major app
- Linear Agent: answers questions, summarizes issues and projects, drafts updates, and creates or changes issues, per Linear's documentation. Open it with Cmd/Ctrl+J or @Linear in a comment. It only touches content the invoking user can access. Skills and Loops are workflows the model performs again each time.
- Third-party integration: an outside agent installs through OAuth with
actor=app, which needs workspace-admin approval. Assigning an issue makes it the delegate while the human stays owner (Linear's agent docs). - Major app: the agent writes the webhook handler, rules, decision database and audit log once. Routine issues run as code. Reviewers see why each issue went where it did.
Linear Agent is a fine place for ad hoc questions and drafting inside Linear. A triage process that must run the same way on the thousandth issue as on the first, and prove it, is software.
Which Linear jobs need a model?
Five jobs come up repeatedly: triaging new issues, spotting duplicates, enriching issues with context from other systems, writing cycle reports, and drafting project updates.
The first three are mostly rules. A bug from a given customer segment goes to a given team with a given label. An issue that links a pull request gets that PR's status attached. Those steps belong in code. Cycle reports and update drafts need judgment about what matters, so that is where the model spends tokens.
A confidence score alone should never auto-close an issue or change priority on something consequential. Rules route the routine cases. A person owns severity.
What you need to know about the Linear API
Linear exposes one GraphQL endpoint at https://api.linear.app/graphql. A personal API key goes in the header as Authorization: <API_KEY>. OAuth tokens go in as Authorization: Bearer <ACCESS_TOKEN>, and Linear recommends OAuth for applications. Scopes include read, write, issues:create, comments:create and admin. Request the narrowest set. With actor=app, changes are attributed to the app, not the person who authorized it.
Reads and writes are ordinary GraphQL operations such as issue(id: "LIN-42") and issueCreate(input: {...}). For events, webhooks cover issues, comments, labels, projects and cycles. Each delivery carries a Linear-Signature header holding a hex-encoded HMAC-SHA256 of the raw body, plus a webhookTimestamp you should check is within one minute.
The strengths are real: one endpoint, push events so you never poll, and scopes that limit writes. The constraints are specific.
- GraphQL failures appear in an
errorsarray, and a response can return HTTP 200 with partial data and errors together. Code that checks only the status treats failures as successes. - A rate-limit hit returns HTTP 400 with
extensions.codeofRATELIMITED. Read theX-RateLimit-Requests-RemainingandX-RateLimit-Complexity-Remainingheaders and the current rate-limit docs instead of hardcoding quotas. - Creating webhooks needs workspace-admin rights or an OAuth app with the
adminscope. - Linear retries failed deliveries up to three times, so duplicates happen and the handler needs idempotency.
Build the Linear issue-triage agent on Major
The design below is a blueprint, not a measured deployment. It connects Linear, GitHub and Slack.
- Connectors. Linear, GitHub and Slack, each with credentials scoped to one Linear team, the relevant repositories and one review channel.
- The app holds state. A managed database stores every issue ID seen, the rule that fired, the decision, the timestamp and the write result. A repeat webhook delivery finds its issue ID already stored and is dropped.
- Event. A Linear webhook for created issues hits the app, which verifies
Linear-Signatureagainst the raw body and rejects stale timestamps. - Context. If the issue links a GitHub PR, the app fetches its status and files changed.
- Policy route. Fixed rules map team, label and keywords to a destination. No match, or two rules in conflict, marks the issue ambiguous.
- The agent's judgment. For ambiguous issues only, the agent summarizes the issue and suggests a label. It posts to Slack, where a person owns the severity and priority call.
- Governed writes. A matched issue gets one mutation limited to the team and label fields. An allowed-fields check in code means a bad prompt cannot widen it. RBAC controls who can edit the rules, and every action is logged.
Rule drift is what goes wrong. Keyword rules misroute when product vocabulary changes, and nothing errors. Because the app logs the rule behind every decision, you can find and fix misroutes later.
Build this on Major with SSO, permissions, database and audit handled by the platform. For tracing what the app did, see agent observability and agentic AI governance. The decision history follows the pattern in durable state for AI agents.
Start building on Major
Describe your Linear triage rules to Major and an agent builds the webhook app, decision database and Slack review queue, with scoped credentials and an audit log from the first deploy. Your team keeps the severity call, and the model only sees the issues the rules could not settle.
Related articles
Frequently asked questions
- What can a Linear AI agent do?
- Linear's built-in agent can answer questions from workspace data, summarize issues and projects, draft updates, and create or change issues and projects, within the access of the user invoking it. A custom agent built on the Linear API can add rule-based routing, enrichment from other systems, and its own logs.
- How do you connect an AI agent to Linear?
- Call the GraphQL endpoint at api.linear.app/graphql with a personal API key or an OAuth access token. Linear recommends OAuth for applications. Use actor=app to attribute changes to the app, and register a webhook to receive issue events as they happen.
- Can a Linear AI agent automatically triage issues?
- Yes, for clear cases. Fixed rules can route an issue by team, label, or keyword and write the result back. Ambiguous issues should go to a person, especially for severity and priority. A confidence score alone should not close issues or change consequential fields.
- How should an agent handle Linear API limits?
- Read the current rate-limit documentation and the X-RateLimit response headers instead of hardcoding thresholds. A limit hit returns HTTP 400 with the RATELIMITED code in extensions. Back off until the reset time, batch queries, and use webhooks rather than polling.