Linear AI Build

Generate user stories from feature descriptions, push them to Linear, then have AI agents build the code — all from Claude Code.

What It Does

1. Generates stories — Asks clarifying questions, creates a PRD with user stories, acceptance criteria, and tasks
2. Pushes to Linear — Creates a project with parent issues (stories) and child issues (tasks), labels, and priorities
3. Builds from Linear — Pulls labeled stories back from Linear and orchestrates Claude Flow agents to plan, implement, test, and review the code

Quick Start

Install

npm install linear-ai-build

Configure

npx linear-ai-build init

This will:

1. Ask for your Linear API key (from Linear Settings > Security & Access > Personal API keys)
2. Ask for your Anthropic API key (optional — only needed for standalone CLI)
3. Ask for your default Linear team ID (optional)
4. Write a .env file with your credentials
5. Configure the Linear MCP server for Claude Code (.mcp.json)
6. Install the Claude Code commands

Prerequisites for Building

Install Claude Flow globally:

npm install -g claude-flow@alpha

Usage

Generate Stories

Create stories and tasks in Linear from a feature description.

CLI:

npx linear-ai-build generate "Add user authentication with OAuth" TEAM-abc123
npx linear-ai-build generate "Add user authentication with OAuth" TEAM-abc123 "Auth Epic"

Claude Code:

/linear:generate-stories "Add user authentication with OAuth" TEAM-abc123
/linear:generate-stories "Add user authentication with OAuth" TEAM-abc123 "Auth Epic"

The third argument is an optional project name. If provided, issues are created under that Linear project (existing projects with the same name are reused). If omitted, the PRD title is used as the project name.

Options:

| Flag | Description | |---|---| | --dry-run | Preview the generated PRD without creating anything in Linear | | --cycle <id> | Assign issues to a specific cycle (defaults to active cycle) | | --assignee <id> | Assign issues to a specific user (defaults to you) | | --no-cycle | Skip cycle assignment | | --no-assignee | Skip assignee assignment | | --skip-questions | Skip clarifying questions, generate PRD directly |

Build From Linear

Pull labeled stories from Linear and have Claude Flow agents implement the code.

Claude Code:

/linear:build-from-linear
/linear:build-from-linear WIC-42
/linear:build-from-linear --label ai-build

This command:

1. Uses Linear MCP to fetch stories with the ai-build label (or a specific issue)
2. Fetches child tasks and acceptance criteria for each story
3. Asks you to confirm which issues to process
4. Uses Claude Flow MCP to orchestrate agents:
   • Planner — analyzes the story and creates an implementation plan
   • Implementers — build each task in parallel
   • Tester — writes and runs tests against acceptance criteria
   • Reviewer — reviews all changes, fixes issues
5. Creates a git branch per story (linear/<issue-identifier>)
6. Updates Linear with progress comments and moves issues to "In Review"

Watch Mode (CLI)

Alternatively, poll Linear and auto-process issues without Claude Code:

npx linear-ai-build watch
npx linear-ai-build watch --project "My Project"

Or process a single issue:

npx linear-ai-build build WIC-42

How It Works

Feature Description
        |
        v
  /linear:generate-stories
        |
        v
  Linear (stories + tasks created)
        |
  Label with "ai-build"
        |
        v
  /linear:build-from-linear
        |
        v
  Claude Flow Agents
    Plan → Implement → Test → Review
        |
        v
  Git branch + PR ready
  Linear issues moved to "In Review"

Environment Variables

| Variable | Required | Description | |---|---|---| | LINEAR_API_KEY | Yes | Linear API key | | LINEAR_TEAM_ID | Yes | Default team ID or key (e.g., WIC) | | ANTHROPIC_API_KEY | For CLI | Anthropic API key (not needed for Claude Code plugin) | | TARGET_REPO_PATH | No | Where agents write code (default: current directory) | | TARGET_BRANCH | No | Base branch for new branches (default: main) | | POLL_INTERVAL_MS | No | Watch mode polling interval (default: 30000) | | AI_BUILD_LABEL | No | Linear label to watch for (default: ai-build) |

MCP Servers

Configured in .mcp.json:

| Server | Purpose | |---|---| | linear | Linear API — fetch/create/update issues, comments, projects | | claude-flow | Claude Flow — agent swarm orchestration, task management |

Project Structure

linear-ai-build/
  bin/
    cli.ts                  # CLI entry point (init, generate, watch, build)
    init.ts                 # Interactive setup
  commands/
    generate-stories.md     # /linear:generate-stories command
    build-from-linear.md    # /linear:build-from-linear command
  src/
    generate-sdk.ts         # PRD generation + Linear SDK integration
    index.ts                # MCP-based alternative
    bridge/
      index.ts              # Watch/build entry point
      watcher.ts            # Linear polling loop
      executor.ts           # Claude Flow workflow executor
      transformer.ts        # Issue → workflow builder
      reporter.ts           # Linear status updates
      linear-helpers.ts     # Shared Linear SDK helpers
      config.ts             # Bridge configuration
      state.ts              # Deduplication tracking
      types.ts              # TypeScript types
  .env.example
  .mcp.json                 # MCP server config (Linear + Claude Flow)
  package.json
  tsconfig.json

Troubleshooting

"Missing LINEAR_API_KEY environment variable"

Make sure .env exists and contains your key, or export it directly:

export LINEAR_API_KEY=lin_api_...

"Team ID not found"

Verify your team ID:

curl -X POST https://api.linear.app/graphql \
  -H "Authorization: lin_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { teams { nodes { id name key } } } }"}'

Claude Flow MCP not connecting

Re-register the MCP server:

claude mcp add claude-flow -- npx -y claude-flow@alpha mcp start

"Failed to parse PRD JSON after retry"

Claude occasionally produces unparseable output. Try running again or simplifying the feature description.

License

MIT