elizaos--eliza/plugins/plugin-linear/README.md

@elizaos/plugin-linear

Linear issue-tracking integration for elizaOS. Gives Eliza agents full CRUD control over Linear issues, comments, teams, and projects through natural-language commands.

What it does

• Create, read, update, archive, and search Linear issues
• Add, update, delete, and list comments on issues
• Browse teams and active projects as agent context
• Track an in-memory activity log of all Linear operations the agent performs
• Register as a named search category (linear_issues) for structured issue queries
• Support both API-key and OAuth workspace authentication
• Multi-account configuration — manage multiple Linear workspaces from one agent

Requirements

• Node.js runtime (ESM)
• A Linear API key from linear.app/settings/api

Installation

bun add @elizaos/plugin-linear

Configuration

Minimal (single workspace, API key)

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxx

Full options

# Required
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxx

# Optional
LINEAR_WORKSPACE_ID=your_workspace_id
LINEAR_DEFAULT_TEAM_KEY=ENG          # default team key for new issues
LINEAR_ACCOUNT_ID=default            # label for this account in multi-account setups

# Multi-account (JSON array or object keyed by account ID)
LINEAR_ACCOUNTS=[{"accountId":"work","apiKey":"lin_api_...","defaultTeamKey":"ENG"},{"accountId":"oss","apiKey":"lin_api_..."}]

# OAuth (only needed if using OAuth flow instead of API keys)
LINEAR_OAUTH_CLIENT_ID=your_client_id
LINEAR_OAUTH_CLIENT_SECRET=your_client_secret
LINEAR_OAUTH_REDIRECT_URI=https://your-app/oauth/linear/callback

Character-file alternative — set character.settings.linear.accounts to an array or object of account configs with the same fields.

Enabling the plugin

Add it to your agent's plugin list:

import { linearPlugin } from "@elizaos/plugin-linear";

const agent = new AgentRuntime({
  plugins: [linearPlugin],
  // ...
});

The plugin validates the Linear API key on startup and will throw LinearAuthenticationError if none is found or the key is invalid.

Capabilities

Actions

The plugin exposes a single LINEAR action that routes to 11 operations. The agent infers the operation from context, or you can pass action explicitly.

Operation	What it does
create_issue	Create a new issue in a team
get_issue	Fetch issue details by identifier (e.g. ENG-123)
update_issue	Change title, description, priority, assignee, labels, state, estimate, or due date
delete_issue	Archive an issue
search_issues	Filter issues by query, state, assignee, label, project, team, or priority
create_comment	Add a comment to an issue
update_comment	Edit a comment
delete_comment	Remove a comment
list_comments	List comments on an issue
get_activity	View the agent's operation history log
clear_activity	Clear the activity log

Example triggers:

• "Create a Linear issue for the login bug in team ENG"
• "What's the status of ENG-456?"
• "Comment on ENG-123 that QA can retest"
• "Search open high-priority bugs assigned to alice"
• "Update ENG-789 priority to urgent"

Context providers

These inject Linear data into the agent's context window automatically when relevant. All require ADMIN role.

Provider	Data injected
LINEAR_ISSUES	Up to 10 recent issues with state and assignee
LINEAR_TEAMS	Up to 20 teams with key, name, description
LINEAR_PROJECTS	Up to 10 active projects with state and dates
LINEAR_ACTIVITY	Last 10 Linear operations the agent performed

Search category

The plugin registers a linear_issues search category that accepts structured filters: query, state, assignee, label, project, team, priority, limit, accountId.

Priority values

Linear uses numeric priorities: 1 = Urgent, 2 = High, 3 = Normal, 4 = Low, 0 = No priority.

Notes

• "Delete issue" calls Linear's archive endpoint — Linear does not expose hard-delete via the public API.
• The activity log is in-memory and resets when the agent stops. Maximum 1000 entries.
• All four providers are gated to the automation and connectors contexts, so they appear only when those contexts are active.