20-30 min setupBeginner friendly

Setup Guide

Complete setup instructions with troubleshooting for each step. This guide expands on the Quickstart with detailed help for beginners and troubleshooting when things go wrong.

This guide follows the same 3 steps as Quickstart:

1Create your repo
2Initialize & run
3Start building

Plus prerequisite setup (Steps 1-2) and optional customization (Step 7).

First time setting up a dev environment?

That's okay! Each step includes detailed instructions. Take your time — you only do this once.

Before You Begin

Make sure you have or can get the following:

✓ Required

  • A GitHub account (free)
  • Access to the Catalyst repository
  • A computer (Windows, Mac, or Linux)

○ Will be installed

  • Node.js (runs JavaScript)
  • VS Code (code editor)
  • Git (version control)
  • GitHub Copilot (AI assistant)

Don't have access to the repo?

Contact RIVER Group to get access.

Contact RIVER Group

Before you start

One-time setup for your machine

1

Install required software

Get the tools you need to run Catalyst.

2

Set up GitHub Copilot

Your AI coding assistant for Catalyst development.

AI-Powered Development

GitHub Copilot is your AI coding assistant. It understands the project context and helps you write code. Other options include Cursor, Windsurf, or Claude — but this guide focuses on Copilot.

Quickstart Step 1

Create your repo from the Catalyst template

3

Create your repo from template

Get your own copy of Catalyst — not a clone.

Never clone Catalyst directly — your commits would target the wrong repo. Always use the template to create your own repo.

Option A: GitHub Web (simplest)

  1. 1Open Catalyst on GitHub
  2. 2Click the green Use this template button → Create a new repository
  3. 3Name your project (e.g., my-project), choose visibility, and create
  4. 4Copy your new repo URL from the green Code button
  5. 5Clone your new repo:
git clone https://github.com/YOUR-ORG/my-project.git

Replace YOUR-ORG/my-project with your actual repo URL

or

Option B: GitHub CLI (one command)

Requires GitHub CLI — install with winget install GitHub.cli then gh auth login

gh repo create my-project --template WEARERIVER/catalyst-ai-dev-kit --private --clone

Don't have access to the repo?

Contact RIVER Group to get access.

Contact RIVER Group

Quickstart Step 2

Initialize & run your project

4

Install dependencies

Install project packages with pnpm.

cd my-project
pnpm install

5

Set up environment

Configure environment variables for your project.

copy .env.example .env.local

On Mac/Linux, use cp instead of copy

The .env.local file contains settings for your local environment. For a basic POC, the defaults work fine. If you're using Supabase authentication, you'll need to add your keys.

6

Start the dev server

Run the development server to see Catalyst in action.

pnpm dev

You should see:

Open localhost:3000 in your browser. You'll see the Catalyst landing page with links to Web, App, Docs, and Present surfaces.

Keep the terminal running!

The dev server needs to stay active while you work. Press Ctrl+C to stop it later.

Quickstart Step 3

Start building with AI

7

Customise your project

Optional

Make this project yours using AI prompts.

Now that everything is running, use AI to customise the project. For comprehensive design changes, see the Customisation guide.

Beyond just colour

Changing the primary colour alone won't differentiate your project. The Customisation guide covers personality presets that adjust radius, gray temperature, typography, and more.

Rename Project

Read AGENTS.md, then rename this project from "Catalyst" to "[YOUR PROJECT NAME]".

Update:
1. The app name in lib/config.ts
2. The page title in app/layout.tsx
3. The package name in package.json
4. The heading in AGENTS.md

Quick Colour Change

Read AGENTS.md, then change the primary colour from blue to [purple/green/orange].

Update all primary-50 through primary-900 values in app/globals.css.
Keep the same lightness and chroma patterns, just change the hue.

Full Customisation Guide
8

Start building with AI

Use the starter prompt for best results.

For the best AI experience, start each new chat by priming it with the starter prompt:

catalyst/prompts/codingai-1-starter.md

Attach or paste this file at the start of each AI chat

What the starter prompt does:

  • Sets guardrails for simple, maintainable code
  • Tells AI to read AGENTS.md for conventions
  • Establishes a collaboration pattern (confirm goals, phased work)
  • AI replies "Yes" when ready to proceed

Quick Reference

Keyboard Shortcuts

Open Copilot ChatCtrl+Shift+I
Command PaletteCtrl+Shift+P
Open TerminalCtrl+`
Save FileCtrl+S

Terminal Commands

pnpm devStart server
pnpm buildBuild for prod
pnpm lintCheck code
Ctrl+CStop server

Troubleshooting

Catalyst is about steering

Building proof, not production. Keep your first iteration POC-safe:

  • →Keep scope tight — aim for something steerable inside a week
  • →Mock data is fine — don't wire up production databases yet
  • →Book a steering session once the proof works

You're all set!

Your development environment is ready. Start building with AI and iterate fast.

Learn the approachUnderstand the workflowExplore the design systemSee more prompt examples