Skip to main content

​
What Linear adds to Halo

Linear is an actions-only integration:
ModeWhat it does
ActionsAgents file Linear tickets — bugs and feature requests — when they detect them in conversations.
Linear AgentA dedicated agent that replies to dev comments on tracked Linear tickets, pulling details from the original customer conversation.
There’s no ingest mode (Halo doesn’t pull existing Linear issues into knowledge) and no notifications mode (your team uses Linear’s native notifications). Connect at Integrations > Linear.

​
Setup

​
Connecting

Click Connect Linear. You’ll be redirected to Linear’s OAuth consent screen as an app actor (actor=app). Required scopes (comma-separated):
  • read, write
  • issues:create
  • comments:create
  • app:mentionable
  • app:assignable
After approval, the Halo Linear app appears in your Linear workspace and can be assigned to issues, mentioned in comments, and used to create new tickets.

​
Webhook

Linear webhooks are configured at the Linear app level (one webhook per Halo deployment, not per customer). The endpoint: 
https://app.haloagents.ai/api/integrations/linear/webhook
Verification uses HMAC-SHA256 with LINEAR_WEBHOOK_SECRET and a 60-second timestamp window.

​
Required resource subscriptions

Enable the following resource types on the Halo Linear app’s webhook in your Linear workspace settings:
ResourceWhy Halo needs it
CommentsPowers the AI reply pipeline on tracked tickets.
IssuesKeeps the inbox panel’s status, priority, and title in sync as tickets move through your Linear workflow (Backlog → In Progress → Done).
Issue attachmentsMirrors engineer-uploaded screenshots and link attachments into the dashboard panel for support agents.
Issue Labels (optional)Reserved for future label-change workflows. Currently a no-op.
Halo is intentionally narrow about what it processes:
  • Comments: only create events from human users on tracked issues.
  • Issues: create + update only. remove is ignored to preserve the historical row in the inbox.
  • Issue attachments: create, update, remove all handled; rows are upserted/deleted in linear_issue_attachments.
  • Everything else (Reactions, Projects, Cycles, etc.) returns 200 with no work.

​
Attachments are dashboard-only

Linear attachments often contain internal screenshots, signed S3 URLs, error reports, or other private artifacts. Halo enforces a strict boundary:
  • The linear_issue_attachments table is RLS-scoped to org members. End-user surfaces (the SDK chat widget) cannot read it.
  • The getLinearTicketInfo AI read tool intentionally does not include attachments in its return shape, so the AI cannot leak them into a customer reply.
  • The inbox right-rail Attachments section is labeled “internal, not shown to customers” so support agents understand the boundary.
If you build a new surface that touches Linear data, treat attachments as engineer-only by default.

​
Actions

​
create_bug

The agent files a bug ticket in Linear when it detects a confirmed bug in a conversation. Configuration on the agent’s action card:
  • Default team — which Linear team gets the ticket
  • Labels — added to every filed bug
  • Confidence threshold — only file when the agent is at least N% sure it’s a bug (vs user error)
  • Classification — confirmed_bug vs needs_review
  • Priority — 0–4 (Linear priority scale)
Classification logic: bugs the AI is highly confident about go in as confirmed_bug. Anything ambiguous goes in as needs_review for a human to triage.

​
create_feature_request

The agent captures customer feature requests, improvements, and integration asks as Linear tickets. Configuration:
  • Same team/labels as create_bug
  • Classification — feature_request, improvement, or integration_request
Use this to keep your Linear backlog populated with real customer demand without manually translating Halo conversations.

​
The Linear Agent

When you set up Linear, you can also create a dedicated Linear Agent that replies to dev comments on Halo-created Linear tickets.

​
How it works

1

Bug detected in conversation

During a customer chat, the AI identifies a bug and creates a Linear ticket using create_bug with relevant details — error messages, steps to reproduce, browser info, user context.
2

Developer comments on the ticket

An engineer picks up the ticket and leaves a comment — for example, “What page was the user on?” or “Can you share the full error message?”
3

Linear Agent replies with context

The Linear Agent reads the comment, searches the original conversation, and posts a reply directly on the Linear ticket.

​
Setup

  1. Go to Integrations > Linear
  2. Click Create Linear Agent (or use the agent template at AI Agents > New)
  3. The agent is created with sensible defaults — instructions optimized for concise, technical replies aimed at developers, with knowledge search enabled
You can customize the agent like any other agent.

​
Response modes

The Linear Agent’s behavior on dev comments is controlled by response_mode on the action config:
ModeBehavior
Reply to all comments (always)Responds to every comment on tickets it created. Best for hands-free context retrieval.
Reply only when mentioned (mention_only)Responds only when a comment includes @halo. Opt-in style.
OffNever replies. Bugs are still created from conversations.
When using mention-only, include @halo anywhere in the comment to trigger a response: 
@halo What browser and OS was this user on?

​
What the agent can answer

The Linear Agent has access to:
  • Error details — error messages, stack traces, codes
  • Steps to reproduce — what the customer was doing
  • User environment — browser, OS, device, custom traits
  • User and company info — name, email, plan, custom fields
  • Conversation history — the full back-and-forth
It also has knowledge search enabled, so it can answer “is this expected behavior?” or “is there a setting that controls this?”

​
Limitations

The Linear Agent only replies to comments on tickets that Halo created. It does not respond to comments on:
  • Tickets created manually in Linear
  • Tickets created by other tools
  • Comments from other agents/bots

​
Read tool: getLinearTicketInfo

Beyond actions, agents can use a passive getLinearTicketInfo read tool when org-level read_enabled is on. This lets the agent pull ticket details when a customer references a specific ticket ID in a conversation. Toggle read_enabled on the integration page.

​
Status and stats

The integration page shows:
  • Total Linear issues tracked by Halo
  • Confirmed bugs vs needs review breakdown
  • Feature requests count
  • read_enabled, reply_enabled, customer_messaging_enabled toggles
  • Default team and labels

​
Where to go next

Agent Actions

Enable Linear actions per agent.

Agent Channels

Configure which agents file Linear tickets.