Getting Started & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• demo-website/README.md
• plan.md
• src/test-smoke.ts
• src/engine/optimizationLoop.ts

Abee (also referred to as SynthCrowd) is a synthetic user testing and optimization platform designed to simulate high-volume user behavior on websites. By generating diverse AI personas based on an Ideal Customer Profile (ICP), the system navigates target URLs to identify friction points and propose code-level fixes to improve conversion rates.

This guide covers the necessary environment configuration, dependency installation, and execution steps required to initialize the Abee pipeline and its integrated demo environment.

Sources: README.md:1-10, plan.md:3-8

System Requirements & Prerequisites

Before setting up the project, ensure the following software is installed on your local machine:

• Node.js: Version 18 or higher.
• npm: Included with Node.js.
• Git: For repository cloning and version control operations.

Sources: README.md:200-205, demo-website/README.md:23-25

API Key Requirements

The platform integrates several third-party services for LLM reasoning, browser automation, and observability. You must obtain keys for the following:

Service	Purpose	Required Variable
Anthropic	LLM for ICP interpretation and report generation	ANTHROPIC_API_KEY
Browser Use	Autonomous browser agent runtime	BROWSER_USE_API_KEY
Convex	Real-time serverless database and dashboard events	CONVEX_URL
Laminar	Tracing and observability	LMNR_PROJECT_API_KEY
MongoDB	Persona persistence across optimization iterations	MONGODB_URI

Sources: README.md:214-220, plan.md:144-155, src/test-smoke.ts:18-70

Installation & Environment Setup

The project is structured as a monorepo containing the core engine and a demo website for testing.

Core Engine Setup

1. Clone the repository:

   git clone <repo-url>
   cd YC2026
   

2. Install dependencies:

   npm install
   

3. Configure Environment Variables:
   Create a .env file in the root directory and populate it with your service keys.

   cp .env.example .env
   

Sources: README.md:207-220, package.json:1-25

Demo Website Setup

The demo-website is a Vite-based React application used as a target for synthetic testing.

cd demo-website
npm i
npm run dev

The site uses Tailwind CSS, shadcn-ui, and Framer Motion for its interface.

Sources: demo-website/README.md:34-40, demo-website/package.json:1-10

Core Architecture Overview

Abee operates through a 5-stage pipeline that transitions from natural language input to actionable site optimizations.

Running the Platform

Abee provides several entry points for testing and full optimization runs.

Smoke Testing

To verify that all integrated tools (Anthropic, Browser Use, Convex, Laminar, MongoDB, HUD, and Daytona) are configured correctly, run the smoke test:

npm run test:smoke

This script initializes tracing, interprets a sample ICP, generates a small population, and executes a single browser agent to verify end-to-end connectivity.

Sources: src/test-smoke.ts:1-135, package.json:7-15

Available Scripts

Command	Description
npm run test:pipeline	Tests the persona engine (NL to compiled personas) without launching browsers.
npm run test:population	Validates Gaussian population generation and trait variance.
npm run test:agent	Runs a single browser agent session using a specific persona.
npm run dev	Starts the Convex development server for real-time data persistence.

Sources: package.json:7-15, README.md:225-245

Database & Persistence Setup

The platform utilizes two distinct database systems to handle different data lifecycles:

1. Convex: Handles real-time events, agent telemetry, and live dashboard updates. It tracks runs, personas, agent events, and results.
2. MongoDB: Used for session-long persistence. It stores persona configurations by session_id to ensure that the same personas are used across different iterations of the optimization loop, preventing statistical drift.

Sources: plan.md:135-140, README.md:274-290, src/engine/optimizationLoop.ts:178-185

Conclusion

Setting up Abee requires configuring a suite of AI and infrastructure providers. Once the environment variables are set and dependencies installed, users can utilize the provided test scripts to validate the pipeline before engaging the full optimization loop against local or remote target websites.

Sources: README.md:295-305, plan.md:160-170