Linear Tracker Plugin

The Linear tracker plugin integrates with Linear’s issue tracking system, allowing Agent Orchestrator to manage tasks, track progress, and update issue state as agents work.

Overview

This plugin uses Linear’s GraphQL API and supports two authentication methods:

Direct API: Using LINEAR_API_KEY environment variable
Composio SDK: Using COMPOSIO_API_KEY for integrated workflow automation

The plugin automatically detects which method is available and routes requests accordingly.

Linear uses alphanumeric identifiers (e.g., INT-1234) rather than numeric issue numbers. Branch names follow the convention feat/INT-1234.

Configuration

Configure the Linear tracker plugin in your agent-orchestrator.yaml:

plugins:
  tracker:
    name: linear

projects:
  - id: my-app
    repo: owner/repo-name
    tracker:
      type: linear
      teamId: "abc123-team-uuid"        # Required: Linear team UUID
      workspaceSlug: "my-workspace"     # Optional: for prettier URLs

Configuration Options

teamId

string

required

Linear team UUID. Required for creating issues and filtering by team.Find your team ID in Linear’s URL or via the API.

workspaceSlug

string

Linear workspace URL slug for generating issue URLs.Example: If your Linear URL is https://linear.app/my-workspace/issue/INT-123, the slug is my-workspace.

Requirements

Prerequisites:

LINEAR_API_KEY environment variable (for direct API access) OR
COMPOSIO_API_KEY environment variable (for Composio SDK)
Network access to https://api.linear.app/graphql

Authentication Setup

Option 1: Direct API Key

# Get your API key from Linear settings:
# https://linear.app/settings/api

export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxxx"

Option 2: Composio SDK

# Install Composio SDK
pnpm add @composio/core

# Set API keys
export COMPOSIO_API_KEY="your-composio-key"
export COMPOSIO_ENTITY_ID="default"  # Optional, defaults to "default"

Finding Your Team ID

# Run this query in Linear's API explorer:
# https://linear.app/settings/api

query {
  teams {
    nodes {
      id
      name
      key
    }
  }
}

Or use the Linear CLI:

# Linear URL contains team key (e.g., INT)
# https://linear.app/my-workspace/team/INT/active

Features

Issue Operations

Get Issue Fetch a single issue by identifier:

const issue = await tracker.getIssue("INT-1234", project);
// Returns: { id, title, description, url, state, labels, assignee, priority }

List Issues List issues with filters:

const issues = await tracker.listIssues({
  state: "open",                    // "open" | "closed" | "all"
  labels: ["bug", "frontend"],     // Filter by labels
  assignee: "John Doe",             // Filter by display name
  limit: 30                         // Max results (default: 30)
}, project);

The Linear API automatically filters by teamId from the project config, so you only see issues for your team.

Create Issue Create a new issue:

const issue = await tracker.createIssue({
  title: "Bug: App crashes on startup",
  description: "## Steps to Reproduce\n\n1. Open app\n2. Crashes",
  labels: ["bug", "high-priority"],
  assignee: "John Doe",
  priority: 1  // 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low
}, project);

Update Issue Update issue state, labels, assignee, or add comments:

await tracker.updateIssue("INT-1234", {
  state: "closed",                  // "open" | "in_progress" | "closed"
  labels: ["fixed"],                // Adds labels (additive)
  assignee: "Jane Smith",           // Change assignee by display name
  comment: "Fixed in PR #456"       // Add comment
}, project);

Issue State Mapping

Linear State Type → Tracker State:

Linear State	Tracker State
`triage`	`open`
`backlog`	`open`
`unstarted`	`open`
`started`	`in_progress`
`completed`	`closed`
`canceled`	`cancelled`

Linear has rich workflow states. The plugin maps them to standardized tracker states while preserving Linear’s native state information.

Priority Levels

Linear uses numeric priorities:

Priority	Value	Typical Use
No priority	0	Unset
Urgent	1	Critical bugs
High	2	Important features
Normal	3	Standard work
Low	4	Nice-to-have

Prompt Generation

The plugin generates context-aware prompts for agents:

const prompt = await tracker.generatePrompt("INT-1234", project);

Example output:

You are working on Linear ticket INT-1234: Fix login redirect bug
Issue URL: https://linear.app/my-workspace/issue/INT-1234

Labels: bug, authentication
Priority: Urgent

## Description

Users are redirected to the wrong page after login...

Please implement the changes described in this ticket. When done, commit and push your changes.

Branch Naming

The plugin generates branch names from issue identifiers:

tracker.branchName("INT-1234", project);
// Returns: "feat/INT-1234"

This follows Linear’s recommended convention for branch names.

Issue URLs and Labels

// Generate URL from issue identifier
tracker.issueUrl("INT-1234", project);
// Returns: "https://linear.app/my-workspace/issue/INT-1234"

// Extract identifier from URL
tracker.issueLabel("https://linear.app/my-workspace/issue/INT-1234", project);
// Returns: "INT-1234"

Usage Example

Start Agent on Issue

# agent-orchestrator.yaml
projects:
  - id: my-app
    repo: owner/my-app
    path: ~/repos/my-app
    defaultBranch: main
    tracker:
      type: linear
      teamId: "abc123-team-uuid"
      workspaceSlug: "my-workspace"

# Start agent on Linear issue
ao start my-app "INT-1234"

# The agent will:
# 1. Fetch issue details from Linear
# 2. Create branch "feat/INT-1234"
# 3. Generate prompt with issue context (including priority)
# 4. Start coding to fix the issue

Auto-Update on Progress

# Configure reactions to update Linear when work starts
reactions:
  - event: session_started
    action: run
    command: |
      # Update Linear issue to "In Progress"
      ao tracker update $ISSUE_ID --state in_progress

Troubleshooting

Error: LINEAR_API_KEY environment variable is required

The plugin couldn’t find authentication credentials.Solution:

# Option 1: Direct API
export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxxx"

# Option 2: Composio SDK
pnpm add @composio/core
export COMPOSIO_API_KEY="your-composio-key"

Error: Linear tracker requires 'teamId' in project tracker config

The teamId field is missing from project configuration.Solution:

projects:
  - id: my-app
    tracker:
      type: linear
      teamId: "abc123-team-uuid"  # Add this

Find your team ID in Linear’s API explorer.

Error: Composio SDK (@composio/core) is not installed

You’re using COMPOSIO_API_KEY but the SDK isn’t installed.Solution:

pnpm add @composio/core

Or switch to direct API with LINEAR_API_KEY.

Error: No workflow state of type 'completed' found

Your Linear team doesn’t have a workflow state of the required type.Linear requires specific workflow state types:

unstarted for “open”
started for “in_progress”
completed for “closed”

Solution: Check your team’s workflow settings in Linear and ensure you have states of each type.

Timeout errors

Linear API requests have a 30-second timeout.Solutions:

Check network connectivity
Verify Linear API status: https://status.linear.app/
Check API rate limits (direct API has limits)
Use Composio SDK for better rate limit handling

User not found when setting assignee

The plugin looks up users by displayName (not email or ID).Solution:

// Use the exact display name from Linear
await tracker.updateIssue("INT-1234", {
  assignee: "John Smith"  // Must match Linear display name exactly
}, project);

Find display names in Linear’s user settings.

Labels not found when creating issue

The plugin looks up labels by name for your team.Solution:

Create labels in Linear first (Settings → Labels)
Use exact label names (case-sensitive)
Labels are best-effort: if not found, issue is still created without them

API Reference

Tracker Interface Methods

getIssue(identifier, project)

Fetches issue details by Linear identifier
Returns: Issue object with all fields including priority

isCompleted(identifier, project)

Checks if issue is in completed or canceled state
Returns: boolean

issueUrl(identifier, project)

Generates Linear issue URL
Returns: string

issueLabel(url, project)

Extracts issue identifier from URL
Returns: string (e.g., "INT-1234")

branchName(identifier, project)

Generates branch name from identifier
Returns: string (e.g., "feat/INT-1234")

generatePrompt(identifier, project)

Creates context prompt for agent
Returns: string (formatted prompt with priority)

listIssues(filters, project)

Lists issues with optional filters
Automatically filters by teamId
Returns: Issue[]

updateIssue(identifier, update, project)

Updates issue state/labels/assignee/comments
Handles workflow state transitions
Returns: void

createIssue(input, project)

Creates a new issue
Returns: Issue (created issue)

Advanced Usage

GraphQL Transport

The plugin uses a transport abstraction that supports two backends:

// Direct Linear API
const transport = createDirectTransport();

// Composio SDK
const transport = createComposioTransport(apiKey, entityId);

// Both implement the same interface
const data = await transport<{ issue: LinearIssue }>(query, variables);

Custom Workflow States

When updating issue state, the plugin:

Queries your team’s workflow states
Finds the appropriate state by type
Updates the issue to that state

// This finds your team's "started" state and uses it
await tracker.updateIssue("INT-1234", {
  state: "in_progress"
}, project);

Label Management

Labels are additive: using updateIssue with labels merges them with existing labels, it doesn’t replace them.

// Add labels to an issue
await tracker.updateIssue("INT-1234", {
  labels: ["in-progress", "needs-review"]
}, project);

// Existing labels are preserved

Priority Workflow

// Create high-priority issue
const issue = await tracker.createIssue({
  title: "Critical bug",
  description: "Production is down",
  priority: 1,  // Urgent
  labels: ["bug", "production"]
}, project);

// Priority is included in generated prompts
const prompt = await tracker.generatePrompt(issue.id, project);
// Contains: "Priority: Urgent"

Comment Workflow

// Post status update
await tracker.updateIssue("INT-1234", {
  comment: "🚀 Started working on this issue"
}, project);

// Post completion comment
await tracker.updateIssue("INT-1234", {
  state: "closed",
  comment: "✅ Fixed in PR #456\n\nAll tests passing."
}, project);

Integration with Other Plugins

With SCM Plugin

The tracker and SCM plugins work together for full issue-to-PR workflow:

Tracker generates prompt from Linear issue (with priority context)
Agent writes code
SCM creates PR with Linear issue link
Reactions auto-close issue when PR merges

reactions:
  - event: pr_merged
    action: run
    command: |
      # Linear's smart PR integration automatically closes issues
      # when PR title contains issue identifier (e.g., "INT-1234: Fix bug")

With Workspace Plugin

The tracker provides the branch name for workspace creation:

const branchName = tracker.branchName("INT-1234", project);
// Used by workspace plugin to create branch "feat/INT-1234"

With Composio

When using Composio SDK, you get additional benefits:

Centralized credential management
Workflow automation triggers
Multi-tool integrations
Better rate limit handling

Performance Considerations

GraphQL Queries

The plugin uses optimized GraphQL queries:

Fetches only required fields
Uses variables to prevent injection
Batches related operations when possible

Caching

The Composio SDK client is cached:

// Client is created once and reused
const client = new Composio({ apiKey });

Timeouts

All requests have a 30-second timeout to prevent hanging:

Direct API: native timeout in node:https
Composio SDK: Promise.race with timeout

Security Considerations

API keys are read from environment variables (never hardcoded)
GraphQL queries use variables (no string interpolation)
User input is validated before API calls
Team ID is required (prevents cross-team data access)
All requests are HTTPS-only

Source Code

Source: packages/plugins/tracker-linear/src/index.ts

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

​Linear Tracker Plugin

​Overview

​Configuration

​Configuration Options

​Requirements

​Authentication Setup

​Finding Your Team ID

​Features

​Issue Operations

​Issue State Mapping

​Priority Levels

​Prompt Generation

​Branch Naming

​Issue URLs and Labels

​Usage Example

​Start Agent on Issue

​Auto-Update on Progress

​Troubleshooting

​API Reference

​Tracker Interface Methods

​Advanced Usage

​GraphQL Transport

​Custom Workflow States

​Label Management

​Priority Workflow

​Comment Workflow

​Integration with Other Plugins

​With SCM Plugin

​With Workspace Plugin

​With Composio

​Performance Considerations

​GraphQL Queries

​Caching

​Timeouts

​Security Considerations

​Source Code

Build docs developers (and LLMs) love

Linear Tracker Plugin

Overview

Configuration

Configuration Options

Requirements

Authentication Setup

Finding Your Team ID

Features

Issue Operations

Issue State Mapping

Priority Levels

Prompt Generation

Branch Naming

Issue URLs and Labels

Usage Example

Start Agent on Issue

Auto-Update on Progress

Troubleshooting

API Reference

Tracker Interface Methods

Advanced Usage

GraphQL Transport

Custom Workflow States

Label Management

Priority Workflow

Comment Workflow

Integration with Other Plugins

With SCM Plugin

With Workspace Plugin

With Composio

Performance Considerations

GraphQL Queries

Caching

Timeouts

Security Considerations

Source Code