go-linear

Go SDK, CLI, and MCP server for Linear.

Built for humans and AI agents who want to work with Linear without wrestling GraphQL.

Architecture

Linear GraphQL API
       ↓
   Go SDK (pkg/linear)     ← Type-safe client, generated from schema
       ↓
   CLI (go-linear)         ← Semantic commands, smart defaults
       ↓
   MCP Server              ← Same binary, JSON-RPC mode (via ophis)

Each layer adds value:

Installation

From Source

go install github.com/chainguard-sandbox/go-linear/v2/cmd/linear@latest

Note: go install names the binary linear. Examples below use go-linear (the name from make build).

Or:

git clone https://github.com/chainguard-sandbox/go-linear
cd go-linear && make build

Pre-built Binaries

Download from GitHub Releases.

Go SDK

go get github.com/chainguard-sandbox/go-linear/v2

Quick Start

MCP

claude mcp add --scope user --transport stdio go-linear \
  --env LINEAR_API_KEY=lin_api_xxx \
  -- /path/to/go-linear mcp start

Then ask Claude: "What are my urgent issues?" or "What did the team complete this week?"

See Claude Setup Guide for details.

CLI

export LINEAR_API_KEY=lin_api_xxx

go-linear issue list --assignee=me --priority=1
go-linear user completed --team=ENG --completed-after=7d
go-linear issue create --team=ENG --title="Fix bug" --priority=2

Common Tasks

See CLI Quick Start for all commands and Filters Guide for filter options.

SDK (Go Developers)

client, _ := linear.NewClient("lin_api_xxx")
defer client.Close()

issues, _ := client.Issues(ctx, nil, nil)
for _, issue := range issues.Nodes {
    fmt.Printf("%s: %s\n", issue.Identifier, issue.Title)
}

See SDK Documentation for production configuration.

Design Philosophy

For AI agents, the CLI provides a semantic interface to Linear's GraphQL API, keeping context clean.

Working directly with GraphQL consumes an agent's attention budget on low-signal work:

• Schema exploration
• Query composition
• Pagination management
• Response parsing

This causes context rot - as tokens accumulate, accuracy degrades.

The CLI operates at the right altitude: high enough to hide GraphQL mechanics, specific enough to express precise intent:

go-linear issue list --team=ENG --priority=1

One command, one response. The agent's context stays high-signal:

The CLI also ships with a Claude skill (~10 KB) - decision guides and workflows that provide just-in-time context for complex operations.

The MCP server is auto-generated from the CLI using ophis.

Documentation

Code Generation

The SDK is generated from Linear's GraphQL schema:

upstream/linear (git submodule)
       ↓
   schema.graphql
       ↓
   gqlgenc (code generator)
       ↓
   internal/graphql/models.go (~30k lines)
   internal/graphql/client.go
       ↓
   pkg/linear/ (public API)

To regenerate after schema updates:

make sync-upstream  # Fetch latest schema + regenerate

Project Info

Status: Stable. Semantic versioning.

Not official: This is a third-party client. Official Linear SDKs at https://github.com/linear

Security: mark.esler@chainguard.dev (72-hour acknowledgment). See SECURITY.md.

License: Apache 2.0

Built with:

• gqlgenc - GraphQL code generation
• ophis - Cobra to MCP server
• clog - Structured logging
• fido - Tiered caching (memory + filesystem)