🤖 Claude Linear Integration

Automate your development workflow with AI-powered issue analysis and code fixes

📋 Table of Contents

🎯 Overview

The Claude Linear Integration is an intelligent automation system that connects your Linear issues with Azure DevOps repositories, powered by Claude AI. It analyzes bug reports, creates implementation plans, and can even execute fixes automatically.

💡 What makes this special? Unlike traditional automation tools, this integration understands context, analyzes code, and creates human-readable plans that you can review and discuss before execution.

✨ Key Features

🔍

Smart Analysis

AI-powered analysis of Linear issues with context from comments and related tickets

📋

Detailed Plans

Creates comprehensive implementation plans with testing considerations

💬

Interactive Discussion

Discuss and iterate on plans directly in Linear comments

⚡

Automated Execution

Execute approved plans and automatically create pull requests

🌿

Branch Management

Flexible branch targeting with support for custom source and target branches

📁

Folder Scoping

Focus analysis on specific folders/applications within monorepos and multi-app repositories

🔗

Full Integration

Works seamlessly with Linear, Azure DevOps, and Zoho Service Desk

🔄 Typical Workflow

🐛

1. Report Issue

Create an issue in Linear with details about the bug or feature request

→
🤖

2. Request Plan

Comment with claude-fix [repo-url] to generate an implementation plan

→
💬

3. Review & Discuss

Use claude-plan to discuss and refine the plan as needed

→
⚡

4. Execute

Comment with claude-execute to implement the changes and create a PR

→
💬

5. PR Review

Use claude-discuss in Azure DevOps PR for code reviews and questions

💬 Available Commands

claude-fix

Creates a detailed implementation plan for your issue.

claude-fix [repository-url] claude-fix [repository-url] --from feature-branch claude-fix [repository-url] --from develop --to main claude-fix [repository-url]#branch-name claude-fix [repository-url] --folder path/to/folder claude-fix [repository-url] --folder "frontend apps/dashboard" --from develop

What it does:

  • Clones the repository and analyzes the codebase
  • Focuses on specific folders/applications when using --folder
  • Understands the issue context and requirements
  • Creates a step-by-step implementation plan
  • Identifies testing requirements and potential risks

claude-plan

Discuss and iterate on implementation plans.

claude-plan Can you add error handling for edge cases? claude-plan What about performance considerations? claude-plan Please update the plan to use TypeScript

What it does:

  • Maintains conversation context across multiple comments
  • Updates plans based on your feedback
  • Answers questions about the implementation
  • Tracks plan versions automatically

claude-execute

Execute the approved plan and create a pull request.

claude-execute

What it does:

  • Implements all changes according to the plan
  • Creates a new branch with descriptive name
  • Commits changes with clear messages
  • Creates a pull request in Azure DevOps
  • Handles branch conflicts and retries

claude-help

Get help and documentation links directly in Linear.

claude-help

What it does:

  • Shows available commands and their usage
  • Provides links to complete documentation
  • Includes branch specification examples
  • Perfect for new team members or quick reference

claude-complete

Mark work as complete and clean up temporary files.

claude-complete

What it does:

  • Removes plan files and conversation history
  • Cleans up branch configuration files
  • Provides cleanup summary report
  • Marks the issue as ready for closure

claude-discuss

Azure DevOps only: Have conversations directly in pull request comments.

claude-discuss What are the security implications of this change? claude-discuss Can you review the performance of this algorithm? claude-discuss Please explain this complex logic

What it does:

  • Works directly in Azure DevOps PR comments
  • Provides code reviews and explanations
  • Maintains conversation context in PR threads
  • Integrates with Linear ticket context when available
💡 Note: This command only works in Azure DevOps pull requests, not in Linear issues. Use claude-plan for Linear discussions.

🌿 Advanced Branch & Folder Support

The integration supports flexible branch management and folder scoping to fit your team's workflow:

Branch Specification Methods

1. URL Fragment (GitHub-style)

claude-fix git@ssh.dev.azure.com:v3/org/project/repo#feature-branch

Use the branch specified in the URL fragment as the source branch.

2. Command Line Flags

claude-fix [repo-url] --from develop --to main claude-fix [repo-url] --branch feature-branch claude-fix [repo-url] --from "branch with spaces"

Specify source and target branches explicitly using flags.

3. Folder Scoping

claude-fix [repo-url] --folder frontend/apps/dashboard claude-fix [repo-url] --folder "backend services/auth" --from develop claude-fix [repo-url] --folder data/pipelines/etl --to main

Focus analysis on specific folders/applications within multi-app repositories.

Branch Validation

⚠️ Branch Name Rules: Branch names must follow Git naming conventions:
  • Cannot contain spaces (unless quoted)
  • Cannot contain special characters: @ ~ ^ : \ ? * [
  • Cannot start or end with dots
  • Cannot have consecutive dots (..)

Folder Path Validation

⚠️ Folder Path Rules: Folder paths are validated for security:
  • Cannot contain dangerous sequences like ../
  • Cannot start with / or ~ (absolute paths)
  • Cannot contain control characters
  • Cannot use reserved Windows names (CON, PRN, AUX, etc.)

Examples

✅ Valid Branch Names

  • feature/new-feature
  • bugfix/issue-123
  • develop
  • release/v1.2.0

❌ Invalid Branch Names

  • feature branch (space)
  • bug@fix (@ symbol)
  • .hidden (starts with dot)
  • invalid..name (double dots)

✅ Valid Folder Paths

  • frontend/apps/dashboard
  • backend/services/auth
  • data/pipelines/etl
  • ml-models/training

❌ Invalid Folder Paths

  • ../dangerous (parent dir)
  • /absolute/path (absolute)
  • folder//double (double slash)
  • apps/CON/service (reserved name)

⚙️ Setup & Configuration

1. Linear Webhook Setup

Steps to Configure

  1. Go to Linear Settings → API → Webhooks
  2. Create a new webhook
  3. Set URL to: https://claude.hazcheck.ai/webhook/linear
  4. Select "Comments" under resource types
  5. Copy the webhook secret for configuration

2. Azure DevOps Service Hook (Optional)

For PR Discussions

  1. Go to your Azure DevOps project
  2. Navigate to Project Settings → Service hooks
  3. Create a new service hook subscription
  4. Select "Web Hooks" as the service
  5. Set URL to: https://claude.hazcheck.ai/webhook/azure-devops
  6. Select "Pull request commented on" as the event type

3. Environment Variables

# Required for Linear integration LINEAR_API_KEY=your_linear_api_key LINEAR_WEBHOOK_SECRET=your_webhook_secret # Optional for PR creation AZURE_DEVOPS_PAT=your_azure_pat_token # Optional for Zoho integration ZOHO_API_KEY=your_zoho_api_key
✅ Health Check: Visit https://claude.hazcheck.ai/health to verify your configuration.

📝 Examples & Use Cases

Example 1: Simple Bug Fix

Scenario

You have a bug in your authentication system that needs fixing.

Linear Issue

Title: "Login fails with 500 error when password is empty" Description: "When users submit the login form without a password, the server returns a 500 error instead of a proper validation message."

Comment

claude-fix git@ssh.dev.azure.com:v3/myorg/webapp/backend

Expected Result

Claude will analyze the authentication code, identify the missing validation, and create a plan to add proper error handling.

Example 2: Feature Development with Branch Strategy

Scenario

Adding a new feature to the develop branch, targeting a release branch.

Comment

claude-fix https://dev.azure.com/myorg/project/_git/frontend --from develop --to release/v2.0

Discussion

claude-plan Can you also add unit tests for the new component?

Execution

claude-execute

Example 3: Cross-Platform Issue with Zoho Context

Scenario

A customer reported an issue via Zoho Service Desk, which was then created as a Linear issue.

Linear Issue

Title: "Mobile app crashes on Android 12" Description: "Reported in Zoho ticket #12345. App crashes when accessing camera permissions on Android 12 devices."

Claude automatically detects the Zoho ticket reference and includes additional context from the customer support conversation.

Example 4: Azure DevOps PR Discussions

Scenario

After Claude creates a pull request, team members can discuss the implementation directly in Azure DevOps.

PR Review Process

# In the Azure DevOps PR comments: claude-discuss What are the security implications of this authentication change? # Claude responds with security analysis # Follow-up question in the same PR: claude-discuss Can you add input validation for the email field? # Claude provides detailed validation recommendations

Code-Specific Questions

# Commenting on a specific line of code: claude-discuss Why did you choose this algorithm over a hash table approach? # Or asking for explanations: claude-discuss Please explain this regex pattern and potential edge cases

Benefits:

  • Get instant code reviews and explanations
  • Discuss implementation details before merging
  • Maintain full context from the original Linear issue
  • Educational for team members learning the codebase

Example 5: Using Control Commands

Getting Help

claude-help

When team members need guidance on available commands or syntax.

Work Completion

claude-complete

After the pull request is merged and the issue is resolved, clean up temporary files and mark as complete.

Example 6: Folder Scoping for Multi-App Repositories

Scenario

You have a monorepo with multiple applications and want to fix a bug in the frontend dashboard component.

Repository Structure

myproject/ ├── frontend/ │ ├── apps/ │ │ ├── dashboard/ │ │ ├── admin/ │ │ └── mobile/ │ └── libs/ ├── backend/ │ ├── services/ │ └── shared/ └── data/ └── pipelines/

Focus on Dashboard App Only

claude-fix [repo-url] --folder frontend/apps/dashboard --from develop

Claude will focus analysis only on the dashboard application code, ignoring other parts of the large repository.

Multiple Use Cases

# Focus on backend authentication service claude-fix [repo-url] --folder backend/services/auth # Focus on data pipeline ETL process claude-fix [repo-url] --folder data/pipelines/etl --to main # Focus on shared frontend components claude-fix [repo-url] --folder "frontend/libs/shared components"

Benefits

  • ⚡ Faster Analysis: Claude focuses only on relevant code
  • 🎯 Better Accuracy: More targeted fixes for specific components
  • 🔇 Reduced Noise: Avoids analyzing unrelated parts of large repos
  • 👥 Team Efficiency: Different teams can work on different folders simultaneously

Real-World Workflow

Morning Standup

Team identifies priority bugs from Linear

→

Plan Generation

Use claude-fix to get implementation plans

→

Team Review

Discuss plans using claude-plan

→

Execution

Approved plans executed with claude-execute

🔧 Troubleshooting

Common Issues

❌ No Response from Claude

Possible Causes:

  • Webhook not configured correctly
  • Bot user doesn't have access to the Linear team
  • Command format is incorrect

Solutions:

  • Try claude-help to test if the bot is responding
  • Check webhook URL and secret
  • Verify bot permissions in Linear
  • Use exact command format from examples

🔐 Repository Access Denied

Possible Causes:

  • SSH key not configured for the repository
  • Azure DevOps PAT token missing or expired
  • Repository URL is incorrect

Solutions:

  • Verify repository URL format
  • Check Azure DevOps PAT permissions
  • Ensure repository is accessible

🌿 Branch Not Found

Possible Causes:

  • Specified branch doesn't exist
  • Branch name contains invalid characters
  • No access to the specified branch

Solutions:

  • Verify branch exists in repository
  • Check branch name validation rules
  • Use quotes for branches with spaces

🚀 PR Creation Failed

Possible Causes:

  • Azure DevOps PAT token insufficient permissions
  • Target branch is protected
  • PR already exists for the branch

Solutions:

  • Check PAT token permissions
  • Use manual PR creation link provided
  • Review branch protection rules

💬 claude-discuss Not Working in PRs

Possible Causes:

  • Azure DevOps webhook not configured
  • PR comment webhook not triggering
  • Bot user lacks PR access permissions

Solutions:

  • Verify Azure DevOps service hook setup
  • Check webhook endpoint is receiving events
  • Ensure bot user has repository access
  • Try the command in a new PR comment (not inline)

Debug Information

💡 Pro Tip: Check the task monitor for real-time progress and detailed logs of Claude's operations.

Getting Help

Useful Endpoints

  • Health Check: /health - Verify system status
  • Webhook Info: /webhook/info - Configuration details
  • Bot Info: /bot/info - Linear bot user status
  • Task Monitor: /monitor - Real-time task tracking

🔌 API Reference

Webhook Endpoints

Linear Webhook

POST /webhook/linear

Receives Linear webhook events for comment processing.

Azure DevOps Webhook

POST /webhook/azure-devops

Receives Azure DevOps webhook events for PR comment processing.

Monitoring API

Task Status

GET /api/tasks/:taskId

Get status and output for a specific task.

Recent Tasks

GET /api/tasks?limit=50

List recent tasks with their status.

Command Response Format

{ "success": true, "taskId": "task_123456", "plan": "Detailed implementation plan...", "branchName": "claude-fix/issue-123-1640995200000", "prUrl": "https://dev.azure.com/org/project/_git/repo/pullrequest/42" }