emanuelcasco/pi-mono-extensions/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.

Available Tool Groups

Workspace and users

• linear_whoami
• linear_workspace_metadata
• linear_list_teams
• linear_get_team
• linear_list_users
• linear_get_user

Issues

• linear_list_issues
• linear_search_issues
• linear_get_issue
• linear_list_my_issues
• linear_create_issue
• linear_update_issue

Projects, states, labels, cycles, documents

• linear_list_projects
• linear_get_project
• linear_list_issue_statuses
• linear_get_issue_status
• linear_list_labels
• linear_list_cycles
• linear_list_documents
• linear_get_document

Comments

• linear_list_comments
• linear_create_comment
• linear_configure_auth

Files

• linear_upload_file
• linear_upload_file_to_issue_comment

Issue Description Images

• Linear issue screenshots embedded in descriptions are Markdown images, not necessarily GraphQL attachment objects.
• linear_get_issue parses description Markdown image links like ![Screenshot](https://uploads.linear.app/...).
• When the active model supports image input, linear_get_issue downloads private Linear image URLs in memory with Linear auth and attaches native image blocks to the result.
• When the active model is text-only, image downloads are skipped and the tool returns a note plus image metadata.
• Description images are not written to disk by default.

File Upload Notes

• Upload tools accept local file paths only; they do not read folders recursively.
• Tool results include sanitized metadata and the Linear asset URL, not file bytes, signed upload URLs, or upload headers.
• Images are suitable for Markdown image embeds: ![alt text](assetUrl).
• Videos and other files should generally be linked: [filename](assetUrl).
• linear_upload_file_to_issue_comment creates image Markdown automatically for image content types and link Markdown for other content types.
• commentBody may include {url} or {markdown} placeholders; otherwise generated file Markdown is appended to the comment body.

Priority Values

Issue Status Types