pi-linear — Linear Integration for pi

Linear issue tracker integration for the pi coding agent. Pull issues, work on them with full agent context, mark them as Done, and post session summaries back as Linear comments — all without leaving the terminal.

Prerequisites

1. A Linear account
2. A personal Linear API key — create one at https://linear.app/settings/api
3. Node.js 18+ (for built-in fetch)

Install

# From npm (once published)
pi install npm:pi-linear

# From git
pi install git:github.com/YOUR_USER/pi-linear

# Local development
pi -e ./extensions/linear.ts

Setup

Set your Linear API key as an environment variable:

export LINEAR_API_KEY=lin_api_your_key_here

Note on OAuth tokens: If you're using a Linear OAuth access token instead of a personal API key, prefix it with Bearer :

export LINEAR_API_KEY="Bearer your_oauth_token"

Personal API keys (lin_api_...) do NOT need the Bearer prefix.

Quick Start

1. Start pi
2. Type /linear-issues to browse projects → milestones → issues
3. Tell pi: "Work on LIN-42"
4. Pi reads the issue, does the work, and marks it Done

Available Tools

Tools can be integrated in your workflow to create new issues or manage existing ones.

Tool	Description
linear_list_projects	List accessible Linear projects
linear_list_milestones	List milestones with issue counts
linear_list_issues	List issues (defaults to unstarted/Todo)
linear_get_issue	Full issue details with description, comments, sub-issues
linear_get_my_issues	Current user's assigned unstarted issues
linear_search_issues	Search issues by term
linear_add_comment	Post a markdown comment on an issue
linear_update_issue	Update issue state, assignee, or priority
linear_create_issue	Create a new issue, optionally as child or in a specific project

Commands

Command	Description
/linear-issues	Interactive project → milestone → issue browser

Default Behavior

• Unstarted only: linear_list_issues and linear_get_my_issues default to filtering for issues with state.type: "unstarted" (the stable category for Todo/New/Backlog states). Finished/completed issues are excluded from the work queue by default.
• PI Agent state: linear_update_issue without an explicit stateId transitions issues to a "PI Agent" completed state. This state is created automatically per team if it doesn't exist, giving a clear visual indicator that pi completed the work.

Example Workflow

User: What issues are assigned to me?
Agent calls: linear_get_my_issues
→ Shows 3 unstarted issues

User: Tell me about LIN-42
Agent calls: linear_get_issue(issueId: "LIN-42")
→ Shows full description, comments, sub-issues

User: Implement the fix described in LIN-42
Agent: [reads code, writes fix, runs tests]

Agent calls: linear_update_issue(issueId: "...")
→ LIN-42 transitions to PI Agent (Done)

Agent calls: linear_add_comment(issueId: "...", body: "...")
→ Posts summary of changes

Architecture

• Zero runtime dependencies — uses Node.js built-in fetch for GraphQL calls
• GraphQL-only — Linear's GraphQL API is the only integration surface
• API key from env — reads LINEAR_API_KEY on every call, never cached
• Tools-first — all Linear operations are pi tools the agent calls autonomously
• Composable — other skills/extensions can build on these tools

Error Handling

Scenario	Behavior
LINEAR_API_KEY not set	Clear error with setup instructions
Invalid API key	"Invalid Linear API key" with link to settings
Rate limited (429)	Error with retry-after info
Issue not found	"Issue not found"
Network timeout (10s)	"Linear API request timed out"

License

MIT