Builder AI 🤖

A powerful command-line interface tool that integrates with Anthropic Claude and OpenAI to help developers build software more efficiently. Unlike other AI assistants, Builder AI focuses on automated workflows for specific development tasks, allowing teams to create repeatable, AI-powered processes.

Features

• 🔄 Workflow Automation: Create and run pre-built workflows for common tasks (unit tests, docs, refactoring)
• 🔌 MCP Integration: Connect workflows to external services via Model Context Protocol (Jira, GitHub, databases, etc.)
• 🚀 Interactive Chat: Have conversations with AI about your code and development tasks
• 📝 Code Generation: Generate code based on natural language prompts
• 🔍 Code Review: Get AI-powered code reviews and improvement suggestions
• 📚 Code Explanation: Understand complex code and concepts
• ⚙️ Flexible Configuration: Support for both Anthropic Claude and OpenAI models
• 🎯 Project Context: AI understands your project structure and dependencies
• 🔐 Secure: API keys are stored securely using system keychain
• 📦 Team-Ready: Share workflows across your team by committing .builder/ directory

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Install from source

# Clone the repository
git clone <repository-url>
cd builder-ai

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Install globally

npm install -g builder-ai

Quick Start

1. Initialize with API Key

   builder init --provider anthropic --token "your-api-key"

   Or for OpenAI:

   builder init --provider openai --token "your-api-key"

   This will:

   • Create a .builder/ directory with pre-built workflows
   • Generate a builder.json file with your project configuration
   • Auto-detect your framework, language, and styling approach

2. Run a Workflow

   builder workflow list              # See available workflows
   builder workflow run unit-tests    # Generate unit tests for your code
   builder workflow run docs          # Generate documentation
   builder workflow run refactor      # Get refactoring suggestions

3. Interactive Mode

   builder workflow                   # Select and run workflows interactively

4. Other Commands

   builder chat                       # Start an AI chat session
   builder generate "prompt"          # Generate code from a prompt
   builder review                     # Get code review

Commands

builder init

Initialize Builder AI with your provider and API key. Creates a .builder/ directory with pre-built workflows.

builder init --provider anthropic --token "your-api-key"
builder init --provider openai --token "your-api-key" --model "gpt-4"
builder init --provider anthropic --token "your-api-key" --temp 0.5 --max-tokens 2000

Options:

• -p, --provider: AI provider (anthropic|openai)
• -t, --token: API token/key (required)
• -m, --model: AI model name
• --temp: Temperature setting (0.0-1.0)
• --max-tokens: Maximum tokens

builder workflow

Run pre-built workflows for common development tasks.

# List available workflows
builder workflow list
builder workflow ls

# Run a specific workflow
builder workflow run unit-tests           # Generate unit tests
builder workflow run docs                 # Generate documentation
builder workflow run refactor             # Refactor code

# Run with options
builder workflow run unit-tests --files "src/utils.ts,src/api.ts"
builder workflow run unit-tests --output tests/
builder workflow run unit-tests --dry-run # Preview without making changes

# Get workflow information
builder workflow info unit-tests

# Interactive mode
builder workflow                          # Select workflow interactively

Pre-built Workflows

create-component - Create components from Jira tickets (MCP-powered)

• Fetches ticket information from Jira via MCP
• Generates components based on requirements and acceptance criteria
• Supports custom templates and patterns
• Variables: ticketId, componentPath
• Requires: Jira MCP server

unit-tests - Generate comprehensive unit tests

• Analyzes your code and generates test files
• Uses your project's testing framework (Jest, Mocha, Vitest, etc.)
• Follows existing test patterns in your codebase
• Output: {filename}.test.{ext} files

docs - Generate documentation

• Creates JSDoc/TSDoc documentation for your code
• Documents APIs, functions, and classes
• Includes usage examples

refactor - Refactor code for better quality

• Identifies code smells and improvement opportunities
• Suggests performance optimizations
• Improves readability and maintainability

sync-with-github - Sync with GitHub issues (MCP-powered)

• Fetches open issues from GitHub
• Analyzes for automation opportunities
• Requires: GitHub MCP server

builder setup

Configure your AI provider and API keys interactively.

builder setup

builder chat

Start an interactive chat session with the AI.

builder chat                    # Basic chat
builder chat --context          # Include project context

builder generate

Generate code based on a prompt.

builder generate "Create a REST API endpoint"    # Generate with prompt
builder generate -f src/api.ts                   # Save to specific file
builder generate --no-context                    # Skip project context

builder review

Review code for improvements and issues.

builder review                  # Review current directory
builder review src/main.ts      # Review specific file

builder explain

Explain code, concepts, or technologies.

builder explain "React hooks"                    # Explain concept
builder explain -f src/utils.ts                  # Explain specific file

builder config

View or modify configuration.

builder config                  # Show current config
builder config --show           # Show current config
builder config --edit           # Edit configuration
builder config --reset          # Reset to defaults

Configuration

Builder AI uses two types of configuration:

Global Configuration (AI Provider)

Stored securely in your system keychain:

• Provider: Choose between Anthropic Claude and OpenAI
• Model: Select specific AI models (Claude 3.5 Sonnet, GPT-4, etc.)
• Temperature: Control creativity vs. focus (0.0 - 1.0)
• Max Tokens: Set maximum response length
• API Key: Your provider's API key

Project Configuration (builder.json)

Stored in your project root and committed to version control:

{
  "name": "my-project",
  "version": "1.0.0",
  "framework": "nextjs",
  "language": "typescript",
  "styling": "tailwind",
  "testFramework": "jest",
  "paths": {
    "components": "src/components",
    "pages": "src/app",
    "tests": "__tests__"
  }
}

This configuration:

• Is auto-detected during builder init
• Can be customized for your project
• Is used by workflows to generate appropriate code
• Should be committed to share with your team

Supported AI Providers

Anthropic Claude

• Claude 3.5 Sonnet (recommended)
• Claude 3 Opus
• Claude 3 Haiku

OpenAI

• GPT-4 Turbo (recommended)
• GPT-4
• GPT-3.5 Turbo

Workflows

Creating Custom Workflows

Workflows are JSON files stored in .builder/workflows/. Each workflow defines a series of steps to automate a task.

Example workflow structure:

{
  "name": "custom-workflow",
  "description": "My custom workflow",
  "version": "1.0.0",
  "mcpServers": {
    "jira": {
      "name": "jira",
      "type": "remote",
      "url": "http://localhost:3000",
      "env": {
        "AUTH_TOKEN": "${JIRA_API_TOKEN}"
      },
      "timeout": 10000
    }
  },
  "variables": {
    "ticketId": "PROJ-123"
  },
  "steps": [
    {
      "type": "mcp",
      "description": "Fetch data from external service",
      "mcp": {
        "server": "jira",
        "tool": "get_issue",
        "params": {
          "issueKey": "${ticketId}"
        },
        "outputVar": "ticket"
      }
    },
    {
      "type": "generate",
      "description": "Generate output",
      "prompt": "Create code based on: ${ticket.fields.summary}"
    }
  ],
  "config": {
    "filePatterns": ["**/*.ts", "**/*.js"],
    "outputPattern": "{filename}.generated.{ext}",
    "temperature": 0.7,
    "maxTokens": 4000
  }
}

Step Types

• analyze: Gather information about files and project structure
• generate: Use AI to generate new content
• validate: Ensure output meets requirements
• transform: Modify existing code
• mcp: Call tools on MCP servers to fetch/update external data

MCP Integration

Builder AI supports the Model Context Protocol (MCP) for connecting workflows to external services:

• Jira: Fetch tickets, create issues, update statuses
• GitHub: Access issues, PRs, repositories
• Databases: Query and update data
• Custom Services: Any service with an MCP server

MCP Server Configuration

Configure MCP servers in your workflow:

{
  "mcpServers": {
    "myserver": {
      "name": "myserver",
      "type": "local|remote",
      "url": "http://localhost:3000",  // for remote servers
      "command": "npx",                 // for local servers
      "args": ["my-mcp-server"],       // for local servers
      "env": {
        "AUTH_TOKEN": "..."
      },
      "timeout": 10000
    }
  }
}

Using MCP Steps

Call MCP tools in workflow steps:

{
  "type": "mcp",
  "description": "Fetch Jira ticket",
  "mcp": {
    "server": "jira",
    "tool": "get_issue",
    "params": {
      "issueKey": "${ticketId}"
    },
    "outputVar": "ticket"
  }
}

Variable Interpolation

Use ${varName} to reference variables in:

• MCP parameters: "issueKey": "${ticketId}"
• AI prompts: "Generate code for: ${ticket.fields.summary}"
• Output paths: "outputPattern": "${componentPath}/${filename}.tsx"

Variables can come from:

• Workflow definition (variables section)
• Command line arguments
• MCP tool responses (outputVar)

Sharing Workflows

Commit the .builder/ directory to your repository to share workflows with your team:

git add .builder/
git commit -m "Add custom workflows"
git push

Team members who run builder init will get the shared workflows automatically.

Development

Project Structure

src/
├── commands/           # CLI command implementations
│   ├── init.ts
│   ├── setup.ts
│   ├── chat.ts
│   ├── generate.ts
│   ├── review.ts
│   ├── explain.ts
│   ├── config.ts
│   └── workflow.ts     # Workflow management
├── services/           # Core services
│   ├── ai-provider.ts  # AI integration
│   ├── config.ts       # Configuration management
│   ├── project-context.ts # Project analysis
│   └── workflow.ts     # Workflow execution
├── types/              # TypeScript type definitions
│   └── index.ts
└── index.ts           # Main entry point

Available Scripts

npm run build          # Build the project with tsup
npm run dev            # Watch mode with tsup
npm run dev:local      # Build, link, and watch for local testing
npm run start          # Run built version
npm run test           # Run tests
npm run lint           # Lint code
npm run format         # Format code
npm run clean          # Clean build artifacts

Local Development

For local development and testing:

# Install dependencies
npm install

# Start development mode with local linking
npm run dev:local

# In another terminal, test the CLI
builder --help
builder init --provider anthropic --token "test-token"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review the configuration guide

Examples

Create Component from Jira Ticket

# Set up environment variables
export JIRA_MCP_URL="http://localhost:3000"
export JIRA_API_TOKEN="your-jira-token"

# Run the workflow with custom variables
builder workflow run create-component

The workflow will:

1. Connect to your Jira MCP server
2. Fetch ticket PROJ-123 (or your specified ticket)
3. Extract requirements and acceptance criteria
4. Generate a React component based on the ticket
5. Save to src/components/

Custom Workflow with Multiple MCP Calls

{
  "name": "feature-from-ticket",
  "mcpServers": {
    "jira": { "type": "remote", "url": "http://localhost:3000" },
    "github": { "type": "remote", "url": "http://localhost:3001" }
  },
  "steps": [
    {
      "type": "mcp",
      "mcp": {
        "server": "jira",
        "tool": "get_issue",
        "params": { "issueKey": "${ticketId}" },
        "outputVar": "ticket"
      }
    },
    {
      "type": "generate",
      "prompt": "Implement: ${ticket.fields.summary}"
    },
    {
      "type": "mcp",
      "mcp": {
        "server": "github",
        "tool": "create_pull_request",
        "params": {
          "title": "${ticket.fields.summary}",
          "body": "Implements ${ticketId}"
        }
      }
    }
  ]
}

Roadmap

• [x] Workflow automation system
• [x] Pre-built workflows (unit-tests, docs, refactor)
• [x] MCP (Model Context Protocol) integration
• [x] Workflow variables and interpolation
• [ ] Support for more AI providers (Google Gemini, etc.)
• [ ] Integration with popular IDEs
• [ ] Workflow marketplace for sharing workflows
• [ ] Workflow conditions and loops
• [ ] Custom prompt templates
• [ ] Team collaboration features
• [ ] CI/CD integration for automated workflows
• [ ] Workflow versioning and dependencies
• [ ] Pre-built MCP server connectors