Linear Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Linear Integration module enables pi-digby to function as an agent assistant within the Linear project management platform. It allows the bot to respond to issue-related events, provide automated updates, and interact with users through Linear's Agent Session interface. Unlike the Slack integration, which supports real-time editing and deletion, the Linear integration follows an append-only activity model where agent progress is tracked through "thoughts" and final responses are posted as session outcomes.
Sources: src/surface/linear.ts:11-16, src/main.ts:219-224
Architecture and Data Flow
The integration is built on a webhook-driven architecture. When a user interacts with an agent session in Linear, a webhook is sent to the pi-digby HTTP server, which routes the request to a dedicated Linear handler. This handler converts Linear events into a standard BotEvent format used by the internal runner system.
Webhook Handling
The createLinearWebhookHandler utilizes the Linear SDK's LinearWebhookClient to verify signatures and parse incoming AgentSessionEvent payloads. It specifically monitors for session creation and user prompts.
The diagram shows the flow of data from a Linear webhook through the internal processing queue to the agent runner and back to Linear.
Sources: src/linear/router.ts:21-30, src/main.ts:225-235
Event Mapping
Linear events are mapped to internal bot events to ensure compatibility with the agent's core logic.
| Linear Action | Internal Event Type | Description |
|---|---|---|
created | agent_session | Triggered when a new agent session is initiated. Extracts context from the prompt or issue title. |
prompted | agent_session | Triggered by follow-up user messages or explicit stop signals. |
stop signal | N/A | Triggers the handleStop logic to abort the current runner. |
Sources: src/linear/router.ts:39-80
The Linear Surface
The LinearSurface class implements the AgentSurface interface, adapting the agent's output capabilities to Linear's append-only activity timeline.
Output Management
Because Linear does not support editing existing activities, the surface handles progress updates differently than Slack:
- Progress/Details: Emitted as "ephemeral thoughts" that stack in the session history, allowing users to see the agent's step-by-step execution.
- Responses: Buffered locally within the class and only posted to the Linear API when the run is explicitly resolved.
- Formatting: Uses standard Markdown (bold, italic, code blocks, links) instead of Slack's
mrkdwnformat.
Sources: src/surface/linear.ts:18-60, src/agent/prompt.ts:40-43
Lifecycle Sequence
The following sequence illustrates how the LinearSurface manages a typical agent run:
This diagram visualizes the buffering of the final response and the immediate streaming of thoughts.
Sources: src/surface/linear.ts:31-75
Configuration and Environment
The Linear integration is optional and only activates if the required environment variables are present.
Required Credentials
| Variable | Description |
|---|---|
LINEAR_API_KEY | API key for interacting with the Linear GraphQL API. |
LINEAR_WEBHOOK_SECRET | Secret used to verify the authenticity of incoming webhooks. |
Sources: src/main.ts:219-222
System Prompt Adaptation
When the agent detects the source is linear, the buildSystemPrompt function modifies the instructions given to the LLM:
- Identity: "You are digby, a Linear agent assistant."
- Conciseness: Explicitly instructed to be concise and avoid emojis.
- Formatting: Instructed to use standard Markdown for bold (
**), italic (*), and links.
Sources: src/agent/prompt.ts:36-45
Component Summary
| Class/Function | File Path | Responsibility |
|---|---|---|
createLinearWebhookHandler | src/linear/router.ts | Validates webhooks and dispatches events to the runner. |
LinearSurface | src/surface/linear.ts | Manages the UI state and output formatting for Linear. |
LinearClient | src/main.ts (import) | Low-level wrapper for Linear API interactions. |
handleStop | src/main.ts | Aborts active runners when a "stop" signal is received via webhook. |
Sources: src/linear/router.ts:21, src/surface/linear.ts:18, src/main.ts:225-275
The Linear Integration provides a specialized environment for pi-digby to act as an autonomous contributor to Linear issues, maintaining a persistent and transparent log of its actions through the Agent Session activity feed.