linear

Linear GraphQL

All Linear operations go through the linear_graphql client tool exposed by Symphony's app server. It handles auth automatically.

{
  "query": "query or mutation document",
  "variables": { "optional": "graphql variables" }
}

One operation per tool call. A top-level errors array means the operation failed even if the tool call completed.

Workpad

Maintain a local workpad.md in your workspace. Edit freely (zero API cost), then sync to Linear at milestones — plan finalized, implementation done, validation complete. Do not sync after every small change.

First sync — create the comment, save the ID:

Write the returned comment.id to .workpad-id so subsequent syncs can update.

Subsequent syncs — read .workpad-id, update in place:

Query an issue

The orchestrator injects issue context (identifier, title, description, state, labels, URL) into your prompt at startup. You usually do not need to re-read.

When you do, use the narrowest lookup for what you have:

For comments and attachments:

State transitions

Fetch team states first, then move with the exact stateId:

Attach a PR or URL

File upload

Three steps:

1. Get upload URL:

2. PUT file bytes to uploadUrl with the returned headers (use curl).
3. Embed assetUrl in comments/workpad as ![description](url).

Issue creation

Resolve project slug to IDs first:

Then create:

$input fields: title, teamId, projectId, and optionally description, priority (0–4), stateId. For relations, follow up with:

Input: issueId, relatedIssueId, type (blocks or related).

Rules

• No introspection. Never use __type or __schema queries. They return the entire Linear schema (~200K chars) and waste the context window. Every pattern you need is documented above.
• Keep queries narrowly scoped — ask only for fields you need.
• Sync the workpad at milestones, not after every change.
• For state transitions, always fetch team states first — never hardcode state IDs.
• Prefer attachmentLinkGitHubPR over generic URL attachment for GitHub PRs.