Linear

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: ['20', '22']
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - run: npm ci

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Build
        run: npm run build

      - name: Verify dist output
        run: |
          test -f dist/linear-ops.js || { echo "Missing dist/linear-ops.js"; exit 1; }
          test -f dist/query.js || { echo "Missing dist/query.js"; exit 1; }
          test -f dist/setup.js || { echo "Missing dist/setup.js"; exit 1; }
          node dist/linear-ops.js help > /dev/null

      - name: Smoke tests
        run: npm test


# Linear Skill for Claude Code

A comprehensive [Claude Code](https://claude.ai/code) skill for managing Linear issues, projects, and teams. Provides patterns for MCP tools, SDK automation, and GraphQL API access.

## Features

- **esbuild Pre-compilation** — 18x faster CLI startup (~50ms vs ~1s) with transparent tsx fallback via shared `scripts/run.sh`
- **Label Taxonomy System** — Domain-based labels for consistent categorization and agent routing
- **First-Time Setup Check** — Automatic configuration validation with actionable guidance
- **High-Level Operations** — Simple commands for initiatives, projects, and status updates
- **Sub-Issue Management** — Create and manage parent-child issue relationships
- **Discovery Before Creation** — Mandatory checks to prevent duplicate projects/issues
- **MCP Tool Integration** — Simple operations via Linear MCP server
- **SDK Automation** — Complex operations with TypeScript scripts
- **GraphQL API** — Direct API access for advanced queries
- **Project Management** — Content, descriptions, milestones, resource links
- **Bulk Sync** — Synchronize code changes with Linear via CLI, agents, or hooks
- **Image Uploads** — Upload images to Linear's S3 storage and attach to issues
- **Smoke Tests** — Automated verification of build output and CLI behavior
- **`lin` CLI Integration** — Optional fast-path via [aaronkwhite/linear-cli](https://github.com/aaronkwhite/linear-cli) Rust binary with silent SDK fallback

## Quick Start (New Users)

### 1. Install the Skill

```bash
git clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear
cd ~/.claude/skills/linear && npm install
```

### 2. Run Setup Check

```bash
npm run setup
```

This checks your configuration and tells you exactly what's missing.

### 3. Get Your API Key (If Needed)

1. Open [Linear](https://linear.app) in your browser
2. Go to **Settings** → **Security & access** → **Personal API keys**
3. Click **Create key** and copy it (starts with `lin_api_`)
4. Add to your environment:

```bash
# Add to shell profile
echo 'export LINEAR_API_KEY="lin_api_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

### 4. Verify It Works

```bash
npm run ops -- whoami
```

You should see your name and organization.

### 5. Build for Faster Startup (Optional)

```bash
npm run build
```

Pre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).

### 6. Start Using It

```bash
# Create an initiative
npm run ops -- create-initiative "My Project"

# Create a project
npm run ops -- create-project "Phase 1" "My Project"

# Create a sub-issue under a parent
npm run ops -- create-sub-issue ENG-100 "Add tests" "Unit tests for feature"

# Set parent-child relationships for existing issues
npm run ops -- set-parent ENG-100 ENG-101 ENG-102

# Update issue status
npm run ops -- status Done ENG-123 ENG-124

# See all commands
npm run ops -- help
```

---

## Installation

```bash
# C