linear

Linear Reference (SDK)

# === Linear Skill Environment Check ===
BLOCKED=""

# Detect package manager
if [ -f "yarn.lock" ]; then
  PKG_MGR="yarn" PKG_ADD="yarn add" PKG_GLOBAL="yarn global add"
elif [ -f "pnpm-lock.yaml" ]; then
  PKG_MGR="pnpm" PKG_ADD="pnpm add" PKG_GLOBAL="pnpm add -g"
else
  PKG_MGR="npm" PKG_ADD="npm install" PKG_GLOBAL="npm install -g"
fi

# 1. API Key check
if [ -z "$LINEAR_API_KEY" ]; then
  BLOCKED="yes"
  echo "❌ BLOCKED: LINEAR_API_KEY not set"
  echo ""
  echo "STOP. Do not attempt Linear operations."
  echo "Ask user to set their API key:"
  echo "  export LINEAR_API_KEY=lin_api_..."
  echo ""
  echo "Get key from: Linear → Settings → API → Personal API keys"
else
  case "$LINEAR_API_KEY" in
    lin_api_*)
      echo "✓ Linear API key set (${LINEAR_API_KEY:0:12}...)"
      ;;
    *)
      # Non-standard format - warn but don't block (might still work)
      echo "✓ LINEAR_API_KEY set (${LINEAR_API_KEY:0:8}...)"
      echo "  ⚠️ Unexpected format (should start with lin_api_)"
      ;;
  esac
fi

# 2. Runtime check
if command -v tsx >/dev/null 2>&1; then
  echo "✓ tsx $(tsx --version 2>&1 | head -1)"
else
  BLOCKED="yes"
  echo "❌ BLOCKED: tsx not installed"
  echo "   Cannot execute scripts. Install with: $PKG_GLOBAL tsx"
fi

# 3. Package check
if [ -d "node_modules/@linear/sdk" ]; then
  VER=$(node -p "JSON.parse(require('fs').readFileSync('node_modules/@linear/sdk/package.json')).version" 2>/dev/null || echo "?")
  echo "✓ @linear/sdk@$VER"
elif command -v $PKG_MGR >/dev/null 2>&1 && $PKG_MGR list @linear/sdk 2>/dev/null | grep -q @linear/sdk; then
  echo "✓ @linear/sdk ($PKG_MGR)"
else
  BLOCKED="yes"
  echo "❌ BLOCKED: @linear/sdk not installed"
  echo "   Cannot execute scripts. Install with: $PKG_ADD @linear/sdk"
fi

# Final status (must exit 0 to not fail skill load)
if [ -z "$BLOCKED" ]; then
  echo ""
  echo "Ready to execute Linear operations."
fi

Uses @linear/sdk with tsx. Run inline scripts using heredocs for top-level await support:

tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });
// your code with top-level await
EOF

IMPORTANT: Use tsx << 'EOF' ... EOF heredoc syntax for inline execution with top-level await. The tsx -e flag does NOT support top-level await.

Decision Trees

Webhook Received

1. Is this from my bot?
   → if (webhook.data.user?.id === viewerId) return; // STOP - prevent loop

2. What type?
   → Issue:   webhooks/issue.md
   → Comment: webhooks/comment.md
   → Project: webhooks/project.md
   → Cycle:   webhooks/cycle.md

Responding to Mentions

1. Check if mentioned: /@claude\b/i.test(webhook.data.body)
2. Get issue context: await client.issue(webhook.data.issue.identifier)
3. Reply: await client.createComment({ issueId: issue.id, body: "..." })

Handling Assignment

1. Detect: webhook.updatedFrom?.assigneeId exists
2. Is it me? webhook.data.assignee?.id === viewerId
3. Acknowledge: update state + add comment (see sdk/issues.md#updating)

Tracking Status Changes

1. Detect: webhook.updatedFrom?.stateId exists
2. Get transition: webhook.updatedFrom.state.type → webhook.data.state.type
3. React based on new type (started, completed, etc.)

⚠️ Cleanup Requirements

IMPORTANT: All scripts use inline heredoc execution - no script files are created. No cleanup typically required.

Best Practice: Process API responses in memory, output results to console rather than files.

---

Critical Gotchas (Verified)

Issue	Reality	Fix
Bot loops	Your comments trigger webhooks	Check webhook.data.user.id === viewerId first
Unassigned check	SDK returns undefined, not null	Use !assignee or === undefined
State types	Multiple states can share same type	"canceled" may have "Canceled" AND "Duplicate"
SDK name field	viewer.name = email, not display name	Use viewer.displayName for display
issue.parent	Returns undefined for top-level	Webhooks send null, SDK returns undefined
State IDs	Team-specific	Re-lookup by state.type when moving issues between teams

Quick Lookups

Webhook → Reference

type	File
Issue	webhooks/issue.md
Comment	webhooks/comment.md
Project, ProjectUpdate	webhooks/project.md
Cycle	webhooks/cycle.md

Task → Reference

I want to...	File
Reply to comment/mention	sdk/comments.md#creating
Change issue status	sdk/issues.md#updating
Get issue details	sdk/issues.md#getting
Find workflow states	sdk/queries.md#teams
Find user IDs	sdk/queries.md#users

Webhook Detection

Pattern	Meaning
updatedFrom.assigneeId exists	Assignment changed
updatedFrom.stateId exists	Status changed
updatedFrom.labelIds exists	Labels changed
action: "create" + type: "Comment"	New comment

Field Values

priority: 1=Urgent, 2=High, 3=Normal, 4=Low, 0=None

state.type: backlog → unstarted → started → completed | canceled

Essential Patterns

Bot Loop Prevention (CRITICAL)

# Get viewer ID for loop prevention
tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

const viewer = await client.viewer;
const viewerId = viewer.id;  // Cache at startup
console.log("Viewer ID:", viewerId);
console.log("Display Name:", viewer.displayName);  // NOT viewer.name!

// In webhook handler - check FIRST:
// if (webhook.type === "Comment" && webhook.data.user?.id === viewerId) return;
EOF

Detect Mentions

# Check if @claude is mentioned in webhook body
WEBHOOK_BODY="Hello @claude please help" tsx << 'EOF'
const body = process.env.WEBHOOK_BODY || "";
const wasMentioned = /@claude\b/i.test(body);
console.log("Was mentioned:", wasMentioned);
EOF

Extract Issue References

# Extract issue identifiers like ENG-123, PROJ-456
TEXT="See ENG-123 and PROJ-456" tsx << 'EOF'
const body = process.env.TEXT || "";
const refs = [...new Set(body.match(/[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+/g) || [])];
console.log("Issue refs:", refs);
EOF

Find State by Type

# Find workflow state by type
ISSUE_ID="ENG-123" tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

const issue = await client.issue(process.env.ISSUE_ID!);
const team = await issue.team;
const states = await team?.states();
const inProgress = states?.nodes.find(s => s.type === "started");
console.log("In Progress state:", inProgress?.name, inProgress?.id);
// ⚠️ Multiple states may match - this returns first
EOF

Detect State Transition

// In webhook handler - detect completion
const wasCompleted =
  webhook.updatedFrom?.state?.type !== "completed" &&
  webhook.data.state?.type === "completed";

SDK Quick Start

Get Issue Details

ISSUE_ID="ENG-1234" tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

const issue = await client.issue(process.env.ISSUE_ID!);
const state = await issue.state;
console.log("Issue:", issue.identifier, issue.title);
console.log("State:", state?.name, state?.type);
EOF

Update Issue Status

ISSUE_ID="ENG-1234" STATE_ID="state-uuid" tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

await client.updateIssue(process.env.ISSUE_ID!, { stateId: process.env.STATE_ID });
console.log("Issue updated");
EOF

Add Comment

ISSUE_ID="ENG-1234" tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

const issue = await client.issue(process.env.ISSUE_ID!);
await client.createComment({ issueId: issue.id, body: "Done." });
console.log("Comment added");
EOF

Get Viewer ID (for loop prevention)

tsx << 'EOF'
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

const viewer = await client.viewer;
console.log("ID:", viewer.id);
console.log("Display Name:", viewer.displayName);  // NOT viewer.name!
EOF

Official Documentation

• SDK: https://developers.linear.app/docs/sdk/getting-started
• Webhooks: https://developers.linear.app/docs/graphql/webhooks
• API Reference: https://studio.apollographql.com/public/Linear-API