linear

Linear Integration

Use the native linear_* tools to read and write Linear data through the Linear GraphQL API.

Critical Rules

• Never ask the user to paste a Linear API key in chat.
• Never expose the API key inline in shell commands.
• Before updating an issue or commenting, use linear_get_issue to verify the target.
• Before uploading a file to an issue comment, use linear_get_issue to verify the target.
• When IDs are unknown, use linear_workspace_metadata first.

Authentication

The tools read the key from an in-memory override, LINEAR_API_KEY, or ~/.pi/agent/auth.json at .linear.key.

If auth is missing, invalid, or expired, do not ask the user to paste the key in chat. Use the native linear_configure_auth tool or ask the user to run /linear-auth --force. The prompt is masked and the key is stored by the extension without returning it to the model.

Tool Workflow

• Use linear_configure_auth only when auth is missing, invalid, expired, or the user asks to update the key.
• Use linear_workspace_metadata first when team/project/state/label/user IDs are unknown.
• Use linear_search_issues for keyword lookup.
• Use linear_get_issue before updating or commenting.
• Use linear_get_issue to inspect Linear issues; Markdown images embedded in the issue description are automatically included when the active model supports image input.
• If linear_get_issue reports description images were skipped because the current model does not support images, ask the user to switch to a vision-capable model before interpreting screenshots.
• Use linear_list_issues for filtered issue lists by team, assignee, status, or limit.
• Use linear_create_issue to create issues once the team ID is known.
• Use linear_update_issue to change title, description, priority, state, or assignee.
• Use linear_create_comment to add Markdown context to an issue.
• Use linear_upload_file to upload a local image, video, or generic file and get a Linear asset URL.
• Use linear_upload_file_to_issue_comment to upload a local file and comment on a verified issue in one step.