pi-linear

A Pi package that connects Pi to Linear through OAuth and exposes tools for:

• reading an issue and its comments (linear_get_issue)
• searching issues by text, assignee email, team, state, project, label, or priority (linear_search_issues)
• posting a comment (linear_comment_issue)

linear_get_issue includes up to 50 comments and 50 attachment links with their metadata. Tool output is compact by default in Pi’s TUI; expand a tool row to inspect its full JSON result.

Install

From a checkout:

pi install /path/to/pi-linear

For one run:

pi -e /path/to/pi-linear

Personal API key (recommended for local use)

Create a personal API key in Linear under Settings → Security & Access → Personal API keys, then start Pi with it:

export LINEAR_API_KEY="lin_api_..."
pi

The key is used directly by the Linear SDK and is never written to disk. It takes precedence over a stored OAuth token.

OAuth setup

Use OAuth when you can create a Linear OAuth application. Register a local callback, for example http://localhost:3000/oauth/callback. 2. Start Pi with its credentials in the environment:

export LINEAR_CLIENT_ID="..."
export LINEAR_CLIENT_SECRET="..." # optional for public OAuth applications
export LINEAR_REDIRECT_URI="http://localhost:3000/oauth/callback"
pi

3. Run /linear-login. Pi starts a temporary callback server, opens Linear in the browser, validates OAuth state, and uses PKCE (S256) when exchanging the authorization code.

The access token is stored only at ~/.pi/agent/linear.json with owner-only permissions. Set PI_LINEAR_CONFIG_PATH to use a different location. Run /linear-logout to remove it.

LINEAR_REDIRECT_URI must exactly match the application redirect URI and must be an http://localhost, http://127.0.0.1, or http://[::1] URL so the extension can safely receive the callback.

Development

npm install
npm run typecheck
npm test

To enable changelogger functionality, run:

npx changelogger install