linear

@subsimplicity/pi-extension-linear is a pi extension that gives agents focused Linear issue tools while they work in a coding session.

The extension is intentionally a local Linear toolbelt first: it uses Linear's GraphQL API with a personal API key or OAuth access token, avoids polling, and only injects issue context automatically when a prompt mentions Linear issue identifiers such as ENG-123.

Supported surface

This package is a focused Pi extension for Linear issue workflows. It is not a standalone MCP server or a full Linear API wrapper.

Issue read/search

• Fetch an issue by UUID or identifier, e.g. ENG-123.
• Include issue description, URL, priority, estimate, due date, timestamps, workflow state, team, project, labels, creator, assignee, delegate, and recent comments.
• Search recently updated issues with filters for:
  • text query against identifier/title/description/searchable content
  • team UUID, key, or exact name
  • workflow state name or state type
  • label names
  • priority
  • assignee UUID or email
  • project name
  • archived issue inclusion
• List issues assigned to and recently created by the authenticated user.

Team/workflow discovery

• List Linear teams with UUIDs, keys, and names.
• List workflow states for a team by team UUID, key, or exact name.

Issue writes

• Create issues with team, title, and optional markdown description, assignee, due date, label IDs, priority, project, and state.
• Update issues by UUID or identifier. Supported fields are title, description, assignee, due date, replacement label IDs, priority, project, and state.
• Add markdown comments to issues.

Pi integration

• Show a linear: status indicator in pi.
• Inject concise Linear context automatically when a prompt mentions issue keys such as ENG-123.
• Add #... autocomplete for recently updated Linear issues.

Requirements

Set one of these environment variables before starting pi:

export LINEAR_API_KEY=lin_api_...
# or, for OAuth bearer-token auth:
export LINEAR_ACCESS_TOKEN=...

Personal API keys are easiest for local use. OAuth/app-actor and webhook-based Linear Agents are intentionally out of scope for this first package.

Install / use locally

From this package directory:

bun install
pi -e ./src/index.ts

To install from a local checkout so pi loads it automatically:

pi install ./path/to/linear

Use a project-local install when you want pi to record it in that project's .pi/settings.json:

pi install -l ./path/to/linear

Tools

Tool	Purpose
linear_setup	Check Linear credentials and return the authenticated user.
linear_get_issue	Fetch an issue by UUID or identifier, e.g. ENG-123.
linear_search_issues	Search issues with focused filters and recently-updated ordering.
linear_my_work	List issues assigned to and recently created by the authenticated user.
linear_list_teams	List Linear teams with keys and UUIDs.
linear_list_states	List workflow states for a team.
linear_create_issue	Create a Linear issue.
linear_update_issue	Update a Linear issue.
linear_comment_issue	Add a markdown comment to a Linear issue.

Commands

• /linear-setup — check credentials and show the authenticated Linear user.
• /linear-issue ENG-123 — fetch an issue and add it to the transcript.
• /linear-search text — search recently updated issues by text.
• /linear-my-work — show issues assigned to and recently created by you.
• /linear-teams — list team keys and UUIDs.
• /linear-states TEAM_KEY — list workflow states for a team.

Autocomplete

Type # followed by part of an issue key/title to autocomplete recently updated issues. Completing #ENG inserts ENG-123.

Development

bun install
bun run typecheck
bun run lint