Skip to content

README.md

Latest commit

 

History

History
177 lines (120 loc) · 6.3 KB

README.md

File metadata and controls

177 lines (120 loc) · 6.3 KB

pi-mono-linear

A pi extension and skill package that exposes native Linear GraphQL tools for issue, project, team, user, comment, file upload, cycle, label, workflow-state, and document workflows.

Tools

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_get_issue
  • linear_search_issues
  • linear_list_my_issues
  • linear_create_issue
  • linear_update_issue

Metadata and related records

  • 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

The package also bundles the linear skill under skills/linear/SKILL.md.

Authentication

The extension looks for a Linear API key in this order:

  1. in-memory key override created by /linear-auth --force or linear_configure_auth
  2. LINEAR_API_KEY environment variable
  3. ~/.pi/agent/auth.json at .linear.key

If no key is found, or if Linear rejects the key as invalid/expired, the native tools can prompt you with a masked local dialog and store the replacement key without returning it to the model.

Do not paste API keys into an LLM chat.

Recommended: native auth command

Run this in pi:

/linear-auth --force

The command shows the Linear API-key URL and required permissions, prompts for the key with masked input, and writes it to ~/.pi/agent/auth.json at .linear.key.

The same flow is available to the agent through the linear_configure_auth tool. That tool returns only metadata such as stored: true; it never returns the key.

If a normal linear_* request fails because the key is missing, invalid, or expired, the extension retries once after prompting you for a fresh key.

Option A: environment variable

For the current shell session:

export LINEAR_API_KEY="lin_api_xxx"

To persist it, add that export to your shell profile (~/.zshrc, ~/.bashrc, etc.) or your preferred secrets manager.

Option B: pi auth file

Create or update ~/.pi/agent/auth.json:

{
  "linear": {
    "key": "lin_api_xxx"
  }
}

Recommended file permissions:

mkdir -p ~/.pi/agent
chmod 700 ~/.pi/agent
chmod 600 ~/.pi/agent/auth.json

If the file already contains other credentials, merge the linear.key entry instead of overwriting the file.

Creating a Linear API key

  1. Open Linear.
  2. Go to Settings → Account → Security & Access.
  3. Under Personal API keys, click Create key.
  4. Name it something recognizable, for example pi-agent.
  5. Choose the minimum access level needed for your workflow.
  6. If your workspace supports team restrictions, restrict the key to only the teams pi needs.
  7. Copy the key once and store it via LINEAR_API_KEY or ~/.pi/agent/auth.json.

Required scopes / permissions

Use the least privilege that supports the tools you need:

  • Read is enough for read-only tools such as linear_workspace_metadata, linear_search_issues, linear_get_issue, list tools, and document/comment reads.
  • Write is required for mutation tools: linear_create_issue, linear_update_issue, linear_create_comment, linear_upload_file, and linear_upload_file_to_issue_comment.
  • Admin is not required for this extension's tools.

If you restrict the key to specific teams, the key must include the teams/projects/issues you want to query or mutate.

Linear API keys are sent in the Authorization header as the raw key value; do not prefix them with Bearer.

Usage tips

  • Use linear_workspace_metadata first when team/project/state/label/user IDs are unknown.
  • linear_create_issue accepts either a team UUID or a team key; keys are resolved to UUIDs before the Linear mutation.
  • Use linear_search_issues for keyword lookup.
  • Use linear_get_issue before updating an issue or creating a comment.
  • linear_get_issue automatically parses Markdown images embedded in the issue description. When the active model supports image input, private uploads.linear.app images are downloaded in memory with Linear auth and attached to the tool result; images are not written to disk.
  • If the active model does not support image input, linear_get_issue does not download images and returns a clear skipped-images note plus image metadata.
  • Use linear_list_issues for filtered issue lists by team, assignee, status, and limit.
  • Use linear_upload_file to upload a local image, video, or generic file and return a Linear asset URL.
  • Use linear_upload_file_to_issue_comment after linear_get_issue to upload a local file and post a Markdown comment. Images are rendered with image Markdown; other files use links.
  • File upload tool results return sanitized metadata and the stable Linear asset URL. They do not return local file bytes, signed upload URLs, or upload headers.

Issue description images

Linear issue screenshots embedded in descriptions are stored as Markdown image links, for example:

![Screenshot](https://uploads.linear.app/...)

These are part of the issue description Markdown, not GraphQL attachment objects. linear_get_issue reads them automatically when possible:

  • Vision-capable model: images are streamed into memory, base64-encoded, and returned as native image blocks alongside the Markdown description.
  • Text-only model: image downloads are skipped to avoid unnecessary network and payload work; the response includes a note explaining that a vision-capable model is required.
  • No files are saved locally by default.
  • The default safety limits are 10 description images and 10 MiB per image.

Troubleshooting

Missing auth key

Set LINEAR_API_KEY or add .linear.key to ~/.pi/agent/auth.json.

Permission errors

Confirm the key has the right access level:

  • Read-only workflows need Read.
  • Create/update/comment workflows need Write.
  • Team-restricted keys must include the relevant team.

Custom Linear endpoint

By default, the extension uses https://api.linear.app/graphql. Override it with:

export LINEAR_GRAPHQL_URL="https://api.linear.app/graphql"