@locusai/locus-linear

Linear integration for Locus — sync issues, AI-powered workflows, and bidirectional project management.

Setup

locus install @locusai/locus-linear

1. Authenticate

locus pkg linear auth

Opens your browser for Linear OAuth. After authorization, the package auto-detects your team, workflow states, and labels.

2. Set team (if multiple teams)

locus pkg linear team ENG

3. Verify configuration

locus pkg linear auth --status
locus pkg linear mapping

Commands

Authentication

locus pkg linear auth              # Complete OAuth flow (opens browser)
locus pkg linear auth --status     # Show current auth status
locus pkg linear auth --revoke     # Revoke OAuth token

Team

locus pkg linear team              # Show current team
locus pkg linear team ENG          # Set active team

Import (Linear → GitHub)

locus pkg linear import                       # Import all matching issues
locus pkg linear import --cycle               # Import from active cycle only
locus pkg linear import --project "Backend"   # Import from specific project
locus pkg linear import --dry-run             # Preview without creating issues
locus pkg linear import --enrich              # AI-enrich issues during import

Export (GitHub → Linear)

locus pkg linear export              # Export status updates to Linear
locus pkg linear export --dry-run    # Preview without updating Linear

Sync (Bidirectional)

locus pkg linear sync              # Import + export in sequence
locus pkg linear sync --dry-run    # Preview both directions

AI-Powered Issue Creation

locus pkg linear create "Add rate limiting to the API"    # AI-enriched issue
locus pkg linear create "Fix login bug" --no-ai           # Plain issue

The AI analyzes your codebase to generate a detailed description, acceptance criteria, priority, and labels.

Query Issues

locus pkg linear issues                # List issues from configured team
locus pkg linear issues --cycle        # List issues in active cycle
locus pkg linear issues --limit 25     # Limit number of results
locus pkg linear issue ENG-123         # Show full issue details

Field Mappings

locus pkg linear mapping    # Show state, label, and priority mappings

Configuration

Configuration is stored in .locus/config.json under packages.linear:

{
  "packages": {
    "linear": {
      "auth": { ... },
      "teamKey": "ENG",
      "stateMapping": {
        "Backlog": "backlog",
        "Todo": "todo",
        "In Progress": "in-progress",
        "Done": "done"
      },
      "labelMapping": { ... },
      "userMapping": { ... },
      "importFilter": {
        "states": [],
        "priorities": []
      }
    }
  }
}

Mappings are auto-detected during locus pkg linear auth and can be manually edited in the config file.

Requirements

• Node.js >= 18
• GitHub CLI (gh) — for import/export commands
• A Linear account with OAuth access