Getting Started

Relevant source files

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

• README.md
• apps/examples/definitions/browser-automation/README.md
• apps/examples/definitions/todo-manager/tool-todo-write.ts
• apps/web/src/tests/shared/README.md
• apps/web/src/app/components/agent-dialog/purpose-section.tsx
• apps/web/src/lib/api/README.md
• apps/web/src/lib/workflow_setup_examples/my-workflow-judge.json
• packages/adapter-supabase/REFACTORING.md
• packages/core/README.md
• packages/core/src/tests/TESTING.md
• packages/core/src/messages/api/tests/shared/testHelpers.ts
• packages/core/src/prompts/createSummary.p.ts
• packages/core/src/prompts/workflowAnalysisPrompts.ts
• packages/core/src/tools/README.md
• packages/core/src/utils/persistence/README.md
• packages/core/src/workflow/setup/tests/resultPersistence.test.ts
• packages/mcp-server/README.md
• packages/mcp-server/src/index.ts
• packages/shared/README.md
• tests/README.md

This guide provides instructions for setting up, configuring, and running the lucky project. The project is a framework for self-improving agentic workflows, which uses evolutionary optimization to discover effective collaboration patterns between AI agents. Workflows are defined as evolvable JSON data structures, optimized through genetic programming and iterative improvement algorithms.

The system represents workflows as directed acyclic graphs (DAGs) where nodes are AI agents and edges are message-passing connections. The core of the project lies in its ability to evolve these graph structures to improve performance on metrics like accuracy, cost, and latency.

Sources: README.md:8-12, README.md:104-107

Monorepo Structure

The project is organized as a monorepo with distinct applications and shared packages. Understanding the layout is key to navigating the codebase.

This diagram shows the main directories and the required build order for the packages.

Sources: README.md:23-39

Key Directories

Directory	Description
apps/web	The Next.js user interface for managing workflows, settings, and connectors.
apps/examples	Contains example tool definitions and workflow configurations.
packages/shared	The foundational package containing Zod contracts, types, and utilities. It must be built first.
packages/models	A multi-provider model registry for services like OpenAI and Anthropic.
packages/tools	The framework for both internal code tools and external MCP tools.
packages/core	The workflow execution engine, handling DAGs, nodes, and the evolution algorithms.
packages/adapter-supabase	The persistence layer for storing data in Supabase. It is optional and can be replaced with a mock adapter.
tests/e2e-essential	Contains smoke tests (run pre-commit) and gate tests (run pre-push).

Sources: README.md:23-39, packages/shared/README.md:6-11

Installation and Setup

Follow these steps to get the project running on your local machine.

Prerequisites

• Bun v1.2+
• Node.js v18+
• Git

Sources: README.md:43

Setup Flow

This diagram outlines the steps from cloning the repository to starting the development server.

Step-by-Step Instructions

1. Clone the repository:

   git clone https://github.com/eenlars/lucky.git
   cd lucky
   

   Sources: README.md:46-47

2. Install dependencies:
   This command installs all necessary packages for the monorepo and builds the required shared packages.

   bun install
   

   Sources: README.md:48

3. Configure your environment:
   Copy the example environment file and add your API keys.

   cp .env.example .env.local
   

   You must fill in your API keys (e.g., OPENROUTER_API_KEY or OPENAI_API_KEY) in the newly created .env.local file.
   Sources: README.md:50-51, README.md:126-127

4. Start the web interface:
   Navigate to the web app directory and start the development server.

   cd apps/web && bun run dev
   

   The application will be available at http://localhost:3000 or the next available port.
   Sources: README.md:53

Configuration

The system uses a dual environment system for managing secrets and configurations.

• Local Development (SDK/CLI): Configuration is loaded from .env and .env.local files at the project root.
• UI-Based Workflows (Production): API keys are encrypted and stored in a Supabase lockbox (lockbox.user_secrets).

For local development, the primary configuration file is .env.local.

Sources: README.md:73-82

Environment Variables

The following table lists some of the key environment variables you may need to configure in your .env.local file.

Variable	Description	Default/Example	Source File
LUCKY_API_KEY	API key for the Lucky cloud service. Required for the MCP server when not self-hosted.	fc-YOUR_API_KEY	packages/mcp-server/README.md:104
LUCKY_API_URL	Custom API endpoint for self-hosted instances.	https://lucky.your-domain.com	packages/mcp-server/README.md:108
USE_MOCK_PERSISTENCE	If true, runs the core engine with in-memory storage instead of Supabase.	true	README.md:128
OPENROUTER_API_KEY	API key for OpenRouter, used for accessing various LLMs.	sk-or-v1-abc...	.env.example:2
OPENAI_API_KEY	API key for OpenAI.	sk-...	.env.example:3
MCP_SECRET_PATH	Path to the mcp-secret.json file for configuring MCP servers locally.	./mcp-secret.json	README.md:85

Common Tasks

The project uses bun scripts defined in package.json for common development tasks.

Command	Description
bun run build	Builds all packages and applications in the correct order.
bun run tsc	Runs TypeScript type checking across the entire monorepo.
bun run format	Formats all code using Biome.
bun run test:smoke	Runs fast smoke tests, executed on pre-commit hooks.
bun run test:gate	Runs more comprehensive gate tests, executed on pre-push hooks.

Sources: README.md:56-66, README.md:99-100

Running Workflows from the CLI

You can run and optimize workflows directly from the command line, which is useful for development and testing without the UI.

• Run a single workflow execution:
  This command runs the default workflow once. Setting USE_MOCK_PERSISTENCE=true allows it to run without a Supabase connection by using in-memory storage.

  USE_MOCK_PERSISTENCE=true bun -C packages/core run once
  

  Sources: README.md:128

• Train a workflow iteratively (Cultural Evolution):
  This command starts an iterative training process to optimize a single workflow.

  USE_MOCK_PERSISTENCE=true bun -C packages/core run iterative
  

  Sources: README.md:131

Testing

The repository contains a comprehensive testing setup with unit, integration, and end-to-end tests.

Test Directory Structure

• packages/{package_name}/src: Unit tests are co-located with the source files they test.
• tests/integration: Integration tests that verify interactions between modules and external services.
• tests/e2e-essential: End-to-end tests that validate complete workflow execution. These are split into smoke and gate tests.

Sources: tests/README.md:5-15

Running Tests

Command	Description
bun run test	Runs all unit tests.
bun run test:smoke	Runs critical path smoke tests (fast, run on commit).
bun run test:gate	Runs comprehensive gate tests (slower, run on push).
bun run test:integration	Runs only the integration tests.
bunx vitest run <path_to_test_file>	Runs a specific test file.

Sources: tests/README.md:20-26

Writing Tests

A shared test infrastructure provides helper functions to simplify test setup. The setupCoreTest() function is a common starting point.

Here is a basic template for a new test file:

import { describe, it, expect, beforeEach, vi } from "vitest"
import {
  setupCoreTest,
  mockRuntimeConstantsForGP,
  createMockGenome,
  createMockWorkflowConfig,
} from "@core/utils/__tests__/setup/coreMocks"

describe("MyFunction", () => {
  beforeEach(() => {
    setupCoreTest() // Always include this
    // Add mockRuntimeConstantsForGP() if your function uses CONFIG.*
  })

  it("should do something", async () => {
    // Your test here
  })
})

This template demonstrates the use of setupCoreTest and how to mock runtime constants for tests involving genetic programming.

Sources: packages/core/src/tests/TESTING.md:4-19

Summary

This guide provides the essential information to get started with the lucky project. By following the installation and configuration steps, you can set up a local development environment. From there, you can run and test the evolutionary workflow system, either through the web interface or directly via the command line. For more in-depth information, refer to the README.md files within each package directory.