ai-build-tool

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

• Generates stories — Asks clarifying questions, creates a PRD with user stories, acceptance criteria, and tasks
• Pushes to Linear — Creates a project with parent issues (stories) and child issues (tasks), labels, and priorities
• 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:

• Ask for your Linear API key (from Linear Settings > Security & Access > Personal API keys)
• Ask for your Anthropic API key (optional — only needed for standalone CLI)
• Ask for your default Linear team ID (optional)
• Write a .env file with your credentials
• Configure the Linear MCP server for Claude Code (.mcp.json)
• 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:

• Uses Linear MCP to fetch stories with the ai-build label (or a specific issue)
• Fetches child tasks and acceptance criteria for each story
• Asks you to confirm which issues to process
• 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
• Creates a git branch per story (linear/<issue-identifier>)
• 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