Linear Task Queue

Linear Task Queue orchestrates Opencode sessions to work through Linear project backlogs. For every repository defined in ~/.config/linear-task-queue/config.json, the service spins up a local Opencode server, fetches Todo issues for the configured Linear project, and prompts Opencode to resolve each ticket within the matching local Git checkout.

Quick Start

Hybrid Mode (Default)

The system runs both webhook and polling for maximum reliability:

1. Install dependencies: npm install.
2. Configure environment variables in .env:

   LINEAR_API_KEY=your_linear_api_key
   # Optional: Enable webhooks for real-time processing
   WEBHOOK_URL=https://your-domain.com/webhook
   WEBHOOK_PORT=3000
   # Optional: Configure logging level (debug, info, warn, error)
   LOG_LEVEL=info

3. Create ~/.config/linear-task-queue/config.json describing the repositories to manage:

   {
     "repos": [
       {
         "name": "example-service",
         "localPath": "/home/me/code/example-service",
         "linear": {
           "team": "team-id",
           "project": "Website Revamp"
         }
       }
     ]
   }

4. Run the application:

   # Development with auto-reload
   npm run dev
      
   # Production
   npm run build
   npm start

Smart Mode Detection: The application automatically detects available features:

• Webhook + Polling: If WEBHOOK_URL is configured (recommended)
• Polling Only: If only LINEAR_API_KEY is set

Development

• Development Mode: Use npm run dev for hybrid mode with live reload
• Build: npm run build compiles the project to dist/
• Configuration: Config is loaded at startup, restart to apply changes
• Logging: Set LOG_LEVEL=debug for verbose development logging

API Endpoints (When Webhooks Enabled)

• GET /status - Comprehensive system status including component health, queues, and webhook registration
• POST /webhook - Linear webhook endpoint (automatically configured)

Features

Architecture

• Hybrid Processing: Real-time webhooks with polling fallback for maximum reliability
• Structured Logging: Winston-based logging with configurable levels and contextual metadata
• Unified Configuration: Single source of truth with automatic validation
• Error Handling: Comprehensive error recovery with timeout protection and graceful shutdown
• Health Monitoring: Component-level health checks with centralized status reporting

Operational Excellence

• Zero-Downtime: Graceful shutdown handling for all deployment scenarios
• Monitoring: Detailed status endpoint for operational visibility
• Security: Webhook signature verification and request validation
• Scalability: Modular architecture supporting horizontal scaling

Deployment

PM2 (Recommended)

PM2 provides process management and automatic restart capabilities:

1. Build the TypeScript output:

   npm run build

2. Start the process with the included configuration:

   pm2 start ecosystem.config.cjs --env production

   The ecosystem.config.cjs file runs the compiled dist/index.js entry point with NODE_ENV=production.
3. Register PM2 with your init system so it restarts on boot, then persist the process list:

   pm2 startup
   pm2 save

   Run the command that pm2 startup prints before executing pm2 save so the process list is stored for resurrection.
4. Use pm2 status and pm2 logs linear-task-queue to inspect the process, and apply config or code changes by rebuilding (npm run build) and running pm2 restart linear-task-queue.

Environment Variables

• LINEAR_API_KEY - Required: Linear API key with team access
• WEBHOOK_URL - Optional: Public HTTPS URL for webhook endpoint
• WEBHOOK_PORT - Optional: Port for webhook server (default: 3000)
• LOG_LEVEL - Optional: Logging level (debug, info, warn, error, default: info)
• NODE_ENV - Optional: Environment mode (development, production)