stitch-ab-tester

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

stitch-ab-tester

★ 1 Open GitHub ↗

Stitch A/B Tester is a high-performance CLI tool designed for developers and designers who want to rapidly prototype and test UI variations. Powered by the Google Stitch SDK and Vercel AI SDK, it uses autonomous agents to orchestrate the generation of a base design and multiple A/B variations, serving them in a beautiful, interactive dashboard.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Stitch A/B Tester CLI

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/stitch-ab-tester.svg)](https://www.npmjs.com/package/stitch-ab-tester)

**Stitch A/B Tester** is a high-performance CLI tool designed for developers and designers who want to rapidly prototype and test UI variations. Powered by the **Google Stitch SDK** and **Vercel AI SDK**, it uses autonomous agents to orchestrate the generation of a base design and multiple A/B variations, serving them in a beautiful, interactive dashboard.

---

## Features

- **Autonomous Orchestration**: Uses the Vercel AI SDK to automatically handle project creation and screen generation.
- **Prompt-to-UI**: Generate full UI designs from simple natural language descriptions.
- **Automated A/B Variants**: Create up to 5 distinct variations focusing on layout, color, and imagery.
- **Configurable Aesthetics**: Support for `SQUARE`, `LANDSCAPE`, and `PORTRAIT` aspect ratios.
- **Interactive Dashboard**: Automatically generates a local HTML dashboard to compare variants side-by-side.
- **Developer Friendly**: Built with TypeScript, bundled with esbuild, and ready for `npx`.

---

## Tech Stack

- **Core Engine**: [Google Stitch SDK](https://www.npmjs.com/package/@google/stitch-sdk)
- **AI Orchestration**: [Vercel AI SDK](https://sdk.vercel.ai/)
- **LLM Provider**: [Google Gemini](https://ai.google.dev/)
- **Language**: TypeScript
- **CLI Framework**: [Commander.js](https://github.com/tj/commander.js)
- **Interactive UI**: [Inquirer.js](https://github.com/SBoudrias/Inquirer.js)
- **Logging**: [Winston](https://github.com/winstonjs/winston)
- **Bundling**: [esbuild](https://esbuild.github.io/)
- **Dashboard Styling**: [Tailwind CSS](https://tailwindcss.com/)

---

## Architecture

```mermaid
graph TD
    A[User Input: Prompt + Options] --> B[CLI Logic: Commander.js]
    B --> C{Auth Check}
    C -- Missing --> D[Inquirer Prompt]
    C -- Exists --> E[AI SDK Orchestration]
    D --> E
    E --> F[LLM calls create_project]
    F --> G[LLM calls generate_screen_from_text xN]
    G --> H[Extract IDs from Tool Results]
    H --> I[Fetch HTML/Image Assets]
    I --> J[Generate HTML Dashboard]
    J --> K[Open Browser: Dashboard]
```

---

## Getting Started

### Prerequisites

- Node.js (v18 or higher)
- A Google Stitch API Key

### Installation

Run directly via `npx`:
```bash
npx stitch-ab-tester "A modern dashboard for a crypto wallet"
```

Or install globally:
```bash
npm install -g stitch-ab-tester
```

## Setup

Stitch is a **Remote MCP server** that lives in the cloud. It requires a secure “handshake” to ensure that the AI agent acting on your behalf has permission to modify your designs.

### API Keys vs OAuth

### Option 1: API Key (Fastest)
1. Go to your **Stitch Settings** page.
2. Scroll to the **API Keys** section.
3. Click on **“Create API Key”**.
4. Set it in your environment:
   ```bash
   export STITCH_API_KEY=your_api_key
   export GOOGLE_GENERATIVE_AI_API_KEY=your_gemini_api_key
   ```

### Option 2: OAuth (Secure/Temporary)
Stitch relies on the `gcloud` CLI for secure authentication.

1. **Install Google Cloud SDK**:
   ```bash
   brew install --cask google-cloud-sdk
   ```
2. **Double-Layer Authentication**:
   ```bash
   # User Login
   gcloud auth login
   # Application Default Credentials (ADC) Login
   gcloud auth application-default login
   ```
3. **Configure Project**:
   ```bash
   gcloud config set project "[YOUR_PROJECT_ID]"
   ```
4. **Generate Secrets**:
   ```bash
   export STITCH_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
   export GOOGLE_CLOUD_PROJECT=[YOUR_PROJECT_ID]
   export GOOGLE_GENERATIVE_AI_API_KEY=your_gemini_api_key
   ```

---

### Usage

```bash
stitch-ab "Your UI Prompt" [options]
```

---

## Available Tools (Stitch MCP)

This CLI utilizes the following Stitch MCP tools:

- **Project Management**: `create_project`, `list_projects`, `get_project`.
- **Screen Management**: `list_screens`, `get_screen`.
- **Design**: `generate_screen_from_text`.

---

## Contributing

We welcome contributions! Whether it's a bug fix, a new feature, or improved documentation.

### How to Contribute

1. **Fork** the repository.
2. **Clone** your fork: `git clone https://github.com/harishkotra/stitch-ab-tester.git`
3. **Install dependencies**: `npm install`
4. **Create a branch**: `git checkout -b feature/amazing-feature`
5. **Build the project**: `npm run build`
6. **Test your changes**: `npm run ab-test -- "Test prompt"`
7. **Commit your changes**: `git commit -m 'Add some amazing feature'`
8. **Push to the branch**: `git push origin feature/amazing-feature`
9. **Open a Pull Request**.

### Ideas for New Features
- [ ] **Export to Code**: Add an option to download the generated HTML/CSS locally.
- [ ] **Multi-Device Testing**: Generate variants for Mobile and Desktop simultaneously.
- [ ] **Custom Themes**: Allow users to pass a JSON theme file to guide the generation.
- [ ] **History Command**: A command to view previously generated projects.

stitch-ab-tester

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README