linear-sync

Linear Sync

Alpha — This plugin is under active development. Expect rough edges, breaking changes, and incomplete docs. Feedback and issues welcome at crystal-peak/linear-sync.

A Claude Code plugin that keeps Linear and GitHub in sync. Automatic issue tracking, branch naming, commit enforcement, PR descriptions, GitHub issue sync, and progress updates — all through natural conversation.

Install via claude plugin install linear-sync@crystal-peak (after adding the Crystal Peak marketplace).

How It Works

Linear Sync registers hooks, a subagent, a skill, and scripts via the Claude Code plugin system. When you open Claude Code in any git repo, it detects whether the repo is linked to Linear and adapts accordingly.

flowchart TB
    subgraph "Claude Code Session"
        CC[Claude Code CLI]
        MA[Main Agent]
        SK["linear-sync skill<br/>(behavioral rules)"]
    end

    subgraph "Hooks Layer"
        H1["SessionStart<br/><code>linear-session-start.sh</code>"]
        H2["UserPromptSubmit<br/><code>linear-prompt-check.sh</code>"]
        H3["PreToolUse (Bash)<br/><code>linear-commit-guard.sh</code>"]
        H4["PostToolUse (Bash)<br/><code>linear-post-push-sync.sh</code>"]
        H5["PreToolUse (Bash)<br/><code>linear-api-allow.sh</code>"]
        H6["PreToolUse (Read|Write)<br/><code>linear-state-allow.sh</code>"]
    end

    subgraph "Subagent"
        SA["api subagent<br/>(Sonnet model)"]
    end

    subgraph "External Services"
        LIN["Linear GraphQL API"]
        GH["GitHub CLI (gh)"]
    end

    subgraph "Config Files"
        RC[".claude/linear-sync.json<br/>(committed to repo)"]
        LS["~/.claude/linear-sync/<br/>state.json<br/>(local credentials)"]
        MCP["~/.claude/mcp.json<br/>(API keys)"]
    end

    CC --> H1 & H2 & H3 & H4
    H5 & H6 -.->|auto-approve| MA
    H1 & H2 & H3 & H4 -->|additionalContext| MA
    SK -.->|loaded on trigger| MA
    MA -->|delegates| SA
    SA -->|"linear-api.sh"| LIN
    SA -->|gh CLI| GH
    SA --> RC & LS
    H1 & H3 --> RC & LS
    H4 -->|"sync-github-issues.sh"| GH & LIN
    SA -.->|reads API key| MCP

Architecture

Component Overview

Component	File	Purpose
Session Start Hook	hooks/scripts/linear-session-start.sh	Detects repo, resolves config, injects context at session start
Commit Guard Hook	hooks/scripts/linear-commit-guard.sh	Enforces issue IDs in commits, branches, PRs; cross-issue warnings
Prompt Check Hook	hooks/scripts/linear-prompt-check.sh	Detects issue ID mentions in dev prompts, triggers background fetch
Post-Push Sync Hook	hooks/scripts/linear-post-push-sync.sh	Runs GitHub sync after git push / gh pr create, injects comment reminder
API Auto-Approve Hook	hooks/scripts/linear-api-allow.sh	Auto-approves bash linear-api.sh commands (prevents permission prompts)
State Auto-Approve Hook	hooks/scripts/linear-state-allow.sh	Auto-approves Read/Write on state file and plugin paths
Subagent	agents/api.md	Handles Linear API queries, state persistence, config setup
Skill	skills/linear-sync/SKILL.md	Behavioral instructions loaded by the main agent on trigger
API Wrapper	scripts/linear-api.sh	Reads API key from mcp.json, calls Linear GraphQL API
GitHub Sync Script	scripts/sync-github-issues.sh	Bidirectional sync between GitHub Issues and Linear
Hook Config	hooks/hooks.json	Registers all hooks with Claude Code plugin system
JSON Schema	schema/linear-sync.json	Schema for the committed repo config file

Session Lifecycle

sequenceDiagram
    participant Dev as Developer
    participant CC as Claude Code
    participant SSH as SessionStart Hook
    participant MA as Main Agent
    participant SA as api Subagent
    participant Lin as Linear API

    Dev->>CC: Opens session in git repo
    CC->>SSH: SessionStart event
    SSH->>SSH: Check .claude/linear-sync.json
    SSH->>SSH: Check local state file