WidgetAI Migration Setup Guide

Minimum Machine Specs

Spec	Minimum	Recommended
RAM	16 GB	32 GB
Free disk	15 GB	25 GB
CPU	Any modern 64-bit	Apple Silicon or recent Intel/AMD
GPU	Not required	Apple Silicon (Metal) or NVIDIA (CUDA)
OS	macOS 12+, Windows 10+, Linux	macOS 13+ or Windows 11

The LLM model (Gemma 4 E4B) uses ~10 GB of RAM during generation. On a 16 GB machine it will work but may feel sluggish. 32 GB is comfortable.

What Gets Installed

Component	Size	Purpose
Node.js 18+	~100 MB	Required runtime (you may already have this)
Ollama	~40 MB	Local LLM server, manages and runs AI models
Gemma 4 E4B model	~9.6 GB	The AI model that generates React code (one-time download)
@customagile/widget-ai	~2 MB	The SDK + CLI tool (installed per-project via npm)

Total first-time download: ~10 GB (mostly the model). After initial setup, everything runs offline.

Setup: macOS

1. Install Node.js

If you don't have Node.js 18+:

# Option A: Homebrew (recommended)
brew install node

# Option B: Download installer from https://nodejs.org

Verify:

node --version   # Should show v18.x or higher
npm --version    # Should show 9.x or higher

2. Install Ollama

# Option A: Homebrew
brew install ollama

# Option B: Download from https://ollama.com, drag to Applications
# No admin rights needed for Option B

Start the server:

# Homebrew install:
brew services start ollama

# Manual install:
ollama serve

3. Pull the AI Model

ollama pull gemma4:e4b

This downloads ~9.6 GB on first run. Takes 3-5 minutes on a fast connection. Only happens once, the model is cached locally after that.

Verify:

ollama list
# Should show: gemma4:e4b    9.6 GB

4. Configure GitHub Packages Auth

The widget SDK is a private package on GitHub Packages. You need a GitHub Personal Access Token with read:packages scope.

Create a file at ~/.npmrc (your home directory):

//npm.pkg.github.com/:_authToken=ghp_YOUR_TOKEN_HERE
@customagile:registry=https://npm.pkg.github.com

Replace ghp_YOUR_TOKEN_HERE with your actual token. Ask your team lead if you don't have one.

5. Ready

That's it. Jump to Running a Migration below.

Setup: Windows

1. Install Node.js

Download the LTS installer from nodejs.org and run it. Defaults are fine.

Verify in Command Prompt or PowerShell:

node --version
npm --version

2. Install Ollama

Download from ollama.com and run OllamaSetup.exe.

No admin rights needed. It installs to %LOCALAPPDATA%\Programs\Ollama. The installer starts the Ollama service automatically.

3. Pull the AI Model

Open a new terminal (Command Prompt or PowerShell):

ollama pull gemma4:e4b

~9.6 GB download, 3-5 minutes. One time only.

Verify:

ollama list

4. Configure GitHub Packages Auth

Create a file at %USERPROFILE%\.npmrc:

//npm.pkg.github.com/:_authToken=ghp_YOUR_TOKEN_HERE
@customagile:registry=https://npm.pkg.github.com

5. Ready

Jump to Running a Migration.

Running a Migration

What You Need

A legacy Rally custom app in one of these formats:

App.txt, the built/deployed artifact from Rally (single file, contains all JS)
HTML file, an exported Rally Custom Page
Source directory, a folder containing the ExtJS source files (App.js, etc.)

The App.txt or HTML file is the most reliable input. It contains the complete concatenated source, so nothing is missed.

Run It

From any directory:

# Initialize a new widget project from a legacy app
WIDGET_AI_MODEL=gemma4:e4b npx @customagile/widget-ai migrate ./path/to/App.txt --name my-widget

On Windows (CMD):

set WIDGET_AI_MODEL=gemma4:e4b
npx @customagile/widget-ai migrate .\path\to\App.txt --name my-widget

On Windows (PowerShell):

$env:WIDGET_AI_MODEL="gemma4:e4b"
npx @customagile/widget-ai migrate .\path\to\App.txt --name my-widget

What Happens

Step 1/5: Extracting legacy source...        ← Parses the ExtJS code
  Source: HTML file (20 code blocks)
  App: my-legacy-app (CustomApp)
  Lines: ~844

Step 2/5: Connecting to LLM...               ← Checks Ollama is running
  Provider: Ollama (gemma4:e4b)

Step 3/5: Analyzing legacy code...            ← LLM reads the ExtJS, identifies
  Purpose: Tracks release progress...           components, queries, settings,
  Complexity: complex                           custom fields
  Queries: 2 WSAPI, 0 Lookback
  Settings: 1
  UI Components: 7
  Custom Fields: c_EAEpic

Step 4/5: Generating React widget...          ← LLM generates React/TypeScript
  Generated 6 files                             code following SDK patterns

Step 5/5: Writing project...                  ← Scaffolds project, writes
  TypeScript: 0 error(s)                        generated files, installs deps,
                                                validates TypeScript
Migration complete: my-widget

The whole process takes 3-8 minutes depending on app complexity and machine speed.

Output

A complete widget project:

my-widget/
  src/
    App.tsx                    ← Main component
    types.ts                   ← TypeScript interfaces
    data-provider.ts           ← Data provider (production Rally calls)
    data-loader.ts             ← WSAPI query logic
    mock-data.ts               ← Test data for dev mode
    main.tsx                   ← Entry point with mock/live context switching
    components/                ← Sub-components (for complex apps)
  node_modules/
  package.json
  tsconfig.json
  vite.config.js
  index.html

After Migration

cd my-widget
npm run dev          # Start dev server with mock data (localhost:5173)
npm run build        # Production build for Rally
npm run storybook    # Component explorer

The generated code is a starting point. It correctly uses the SDK's components, data layer, types, and patterns. You will need to review and refine:

Verify the data queries match the original app's behavior
Check that mock data covers the important scenarios
Test edge cases (empty states, errors, loading)
Polish the layout and styling
Add any complex business logic the LLM simplified

Troubleshooting

"fetch failed" or connection refused

Ollama isn't running. Start it:

Mac: brew services start ollama or ollama serve
Windows: Start Ollama from the Start Menu, or run ollama serve

"Model not found"

Pull the model first: ollama pull gemma4:e4b

"Failed to parse generated code JSON"

The model's output was truncated. This happens with very complex legacy apps (1000+ lines). The SDK should have num_predict: 128000 set. If you're on an older SDK version, update: npm install @customagile/widget-ai@latest

npm install fails with 404

GitHub Packages auth isn't configured. See the .npmrc setup in your platform section above.

TypeScript errors after generation

The generated code may have minor type issues. Common fixes:

Missing imports, add them based on the error messages
any types, replace with proper interfaces from @customagile/widget-ai/types/rally-artifacts
Non-existent SDK exports, the LLM sometimes hallucinates import paths. Check node_modules/@customagile/widget-ai/components/index.ts for available components.

Slow generation

Normal. The LLM generates several thousand tokens of code. On CPU (no GPU):

Analysis: 30-60 seconds
Generation: 2-5 minutes for complex apps

Apple Silicon Macs are fastest (Metal GPU acceleration). Windows with NVIDIA GPUs also get acceleration. CPU-only machines work but are slower.

Model Alternatives

The default model is qwen2.5-coder:7b but we recommend Gemma 4 E4B for better results:

Model	RAM	Download	Quality	Set with
qwen2.5-coder:7b	~6 GB	4.7 GB	Fair, sometimes produces invalid JSON	Default (no env var)
gemma4:e4b	~10 GB	9.6 GB	Good, correct JSON, proper SDK patterns	`WIDGET_AI_MODEL=gemma4:e4b`
gemma4:26b	~18 GB	18 GB	Best, needs 32 GB RAM minimum	`WIDGET_AI_MODEL=gemma4:26b`

To use a different model:

# Pull it first
ollama pull gemma4:e4b

# Then set the env var when running migrate
WIDGET_AI_MODEL=gemma4:e4b npx @customagile/widget-ai migrate ./App.txt --name my-widget

Quick Reference

# One-time setup (Mac)
brew install node ollama
brew services start ollama
ollama pull gemma4:e4b

# One-time setup (Windows)
# Install Node.js from nodejs.org
# Install Ollama from ollama.com
ollama pull gemma4:e4b

# Migrate a legacy app
WIDGET_AI_MODEL=gemma4:e4b npx @customagile/widget-ai migrate ./App.txt --name my-widget

# Run the generated widget
cd my-widget
npm run dev