Linear
The Linear channel answers comments on Linear issues that mention the agent. The agent comments back as a Linear member, through that member's personal API key.
Setup
-
Pick the Linear member the agent comments as. A dedicated member, such as
acme-agent, keeps its comments apart from a person's own. Signed in as that member, open Settings > Account > Security & access and create a personal API key. -
As a workspace admin, open Settings > API > Webhooks and create a webhook. Leave the URL for step 5. Under data change events, select Comments. Copy the signing secret.
-
Store both:
broods env set LINEAR_API_KEYbroods env set LINEAR_WEBHOOK_SECRET -
Define the connection and the teams it answers in:
broods/index.tsimport {defineAgent,defineLinearChannel,defineLinearConnection,env,} from "broods";export const linear = defineLinearConnection({apiKey: env("LINEAR_API_KEY"),webhookSecret: env("LINEAR_WEBHOOK_SECRET"),userName: "acme-agent",});export const engineering = defineLinearChannel({name: "engineering",connection: linear,team: "ENG",});export const myAgent = defineAgent({name: "my-agent",connections: [linear],});userNameis the member's display name, the name after@in a mention and at the end of its profile URL. UseallowedChannelIds: ["*"]on the connection to answer on every team. -
Run
broods devorbroods deployand paste the printed URL/v1/webhooks/{accountId}/linearinto the webhook from step 2.
Configuration
| Field | Required | Description |
|---|---|---|
apiKey | yes | personal API key of the member the agent comments as |
webhookSecret | yes | the webhook's signing secret. Checks Linear-Signature on every delivery |
userName | yes | the member's display name. @userName addresses the agent |
apiUrl | no | GraphQL endpoint. Public https only. Defaults to https://api.linear.app/graphql |
allowedChannelIds | no | team keys, such as ENG, or ["*"] for every team |
allowedUserIds | no | Linear user ids (UUIDs) allowed to trigger the agent. Everyone when omitted |
trace | no | "enabled" adds the dashboard trace link to replies |
partition | no | workspace folder split. See Workspaces |
A delivery signed more than a minute before it arrives is refused, so a captured webhook cannot be replayed.
What works
- A new comment on an issue that mentions
@userNameruns the agent. Other comments, edits, and the agent's own comments do not. - The agent sees the issue identifier, title and URL with the comment.
- The reply nests under the comment's thread. Each root comment is its own conversation.
- The agent reacts with 👀 to the comment that called it, and
send-reactionsworks on it.
What does not:
- No agent sessions. Linear's agent mode needs an OAuth app installed with
actor=app, and its tokens expire after a day or a month. Refreshing them needs state kept between requests, which the channel does not have, so only personal API keys are supported. - No typing indicator. Linear shows one only inside agent sessions.
- No streaming. The answer is posted as one comment once the turn ends, because every edit of a comment would come back to Broods as another webhook.
- No inbound or outbound files. Pictures and documents travel as links in the text.
- Comments on project updates and documents are ignored. Only issue comments reach the agent.
- Slash text is passed to the agent as input, as on GitHub.
See Channels for channel tools and shared behavior.