Home

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/requirements.md
• 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/prompts/workflowAnalysisPrompts.ts
• packages/core/src/tools/README.md
• packages/core/src/utils/persistence/README.md
• packages/mcp-server/README.md
• packages/shared/README.md
• packages/tools/PROBLEM_STATEMENT.md
• tests/README.md

The Lucky project is an autonomous workflow engine designed for the evolutionary optimization of multi-agent systems. It addresses the challenge of manual workflow design by treating agentic workflows as evolvable data structures. The system discovers and refines effective agent collaboration patterns by applying genetic programming and iterative improvement algorithms, aiming to create workflows that are progressively cheaper and more successful.

Key technical contributions include evolutionary workflow optimization, a JSON-based workflow specification that enables programmatic manipulation, and comprehensive execution observability for tracking performance across accuracy, cost, and latency. The framework serves as an experimental platform for studying the evolutionary optimization of non-sandboxed multi-agent systems that perform real-world tasks.

Sources: README.md:1-15, apps/web/requirements.md:3-5

Core Concepts

The system is built on several foundational principles that enable its self-improving capabilities.

Agentic Workflows as Directed Acyclic Graphs (DAGs)

Workflows are represented as directed acyclic graphs (DAGs) where nodes are AI-powered agents and edges represent the flow of structured messages between them. This graph structure allows for complex patterns like branching for parallel processing and merging results.

Sources: README.md:118-120, packages/core/src/prompts/workflowAnalysisPrompts.ts:3-7

The diagram below illustrates a sample workflow structure.

JSON-Based Workflow Specification

Workflows are defined as JSON data structures, which makes them programmatically manipulable. This is crucial for the evolutionary algorithms, which perform crossover and mutation operations directly on the JSON, eliminating the need for manual coding of agent interactions.

A workflow configuration consists of a list of nodes (agents) and an entry point. Each node has an ID, a description, a model, tools, a system prompt, and a list of possible next nodes (handOffs).

{
  "nodes": [
    {
      "nodeId": "requirement_analyzer",
      "description": "Analyzes the task requirements...",
      "modelName": "openrouter#openai/gpt-4.1-mini",
      "mcpTools": [],
      "codeTools": ["runInspector"],
      "systemPrompt": "You are a requirement analysis specialist...",
      "handOffs": ["task_output_analyzer"],
      "memory": {}
    },
    {
      "nodeId": "task_output_analyzer",
      "description": "Analyzes the specific output requirements...",
      "modelName": "openrouter#openai/gpt-4.1",
      "mcpTools": [],
      "codeTools": ["runInspector"],
      "systemPrompt": "You are a task output analysis specialist...",
      "handOffs": ["technical_analyzer"],
      "memory": {}
    }
  ],
  "entryNodeId": "main"
}

An example snippet of a workflow defined in JSON.

Sources: README.md:11-13, apps/web/src/lib/workflow_setup_examples/my-workflow-judge.json

Evolutionary Optimization

The core of the project is its ability to automatically optimize workflows using two primary strategies: Iterative Improvement (Cultural Learning) and Genetic Programming.

System Architecture

The project is a monorepo with a clear separation of concerns between applications and reusable packages.

Monorepo Layout and Build Order

The repository is structured to enforce a strict dependency flow, ensuring that foundational packages are built before the packages that depend on them.

Core Execution Engine (@lucky/core)

The @lucky/core package is the heart of the system, containing the workflow execution engine, node system, tool framework, and evolution module. It is organized into five architectural layers.

Layer	Description
Agent Network	Manages autonomous nodes (agents), message routing, and tool coordination.
Execution Engine	Orchestrates DAG-based workflow execution with a three-phase pipeline (Prepare → Execute → Process).
Evolution System	Implements both Cultural Learning and Genetic Programming for self-improvement.
Memory & Persistence	Handles large data with chunked storage, AI summarization, and multi-backend support.
Validation & Quality	Provides multi-layer validation for configurations and outputs, including AI-powered quality assessment.

Sources: packages/core/README.md:10-37

Persistence Layer

The system uses a comprehensive persistence layer, with an adapter for Supabase, to track every aspect of workflow definition and execution. This includes versioning with full evolutionary genealogy.

The database schema is designed to capture the relationships between workflows, their versions, individual executions (invocations), and the execution of each node within a workflow.

Tool Architecture

The framework supports two types of tools to provide agents with capabilities: Code Tools and MCP Tools. This hybrid approach allows for both tightly-integrated, type-safe internal functions and flexible, language-agnostic external processes.

Feature	Code Tools	MCP Tools
Implementation	TypeScript functions within the monorepo.	External servers communicating via Model Context Protocol (MCP).
Registration	Explicitly in codeToolsRegistration.ts.	In mcpToolsRegistration.ts via mcp-secret.json.
Examples	csvReader, todoWrite, humanApproval.	tavily, firecrawl, playwright.
Use Case	Core business logic, file I/O, direct data manipulation.	Web scraping, browser automation, third-party services.

Sources: README.md:92-107, packages/core/src/tools/README.md:10-16, packages/mcp-server/README.md:10-14

A key challenge identified is bridging the gap between tool configuration in the UI (stored in localStorage) and their use during backend workflow execution (read from mcp-secret.json).

Sources: README.md:109-120

How It Works

The system follows a distinct execution flow, from initialization to evolution.

Workflow Execution Flow

The execution of a workflow is an orchestrated process managed by the Core Engine.

Optimization Algorithms

The system employs two complementary strategies for self-improvement.

Iterative Improvement (Cultural Learning)

This method focuses on optimizing a single workflow through a cycle of analysis and targeted modification. An LLM evaluator analyzes performance traces, identifies the root cause of failures or inefficiencies, and suggests specific changes to prompts, tools, or structure. This process typically converges within 5-10 iterations.

Sources: README.md:162-167, packages/core/README.md:88-100

Genetic Programming

This is a population-based approach that evolves a group of 10-50 workflow "genomes" over 10 or more generations.

• Selection: Uses tournament selection (k=3) with elitism to choose the best-performing workflows.
• Crossover: A semantic crossover operator combines the valid structures of two parent workflows.
• Mutation: Randomly applies changes with a defined probability: prompt modification (40%), tool changes (30%), or structural changes (30%).
• Fitness: A multi-objective fitness function evaluates each workflow based on a weighted score of accuracy (0.7), cost (0.2), and time (0.1).

Sources: README.md:169-175, packages/core/README.md:63-86

Getting Started

Installation and Setup

The project requires Bun 1.2+ and Node 18+.

1. Clone and Install:

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

2. Configure Environment:

   # At the repo root
   cp .env.example .env.local
   # Edit .env.local with your API keys
   

3. Run the Web UI:

   cd apps/web && bun run dev
   

Sources: README.md:33-45

Running a Workflow

Workflows can be executed directly from the command line, using in-memory persistence to bypass the need for a Supabase setup.

• Run a single workflow execution:

  USE_MOCK_PERSISTENCE=true bun -C packages/core run once
  

• Train a workflow using iterative improvement:

  USE_MOCK_PERSISTENCE=true bun -C packages/core run iterative
  

Sources: README.md:188-194

Testing

The project includes a comprehensive testing suite divided into different types, managed by vitest.

• Smoke Tests: Fast, critical path validation. Run on pre-commit.
• Gate Tests: More comprehensive validation. Run on pre-push.
• Integration Tests: Test modules with external dependencies like databases.

A shared test infrastructure provides mock functions (setupGPTestMocks, mockRuntimeConstantsForGP) to streamline test setup and reduce boilerplate.

Sources: tests/README.md:16-43, apps/web/src/tests/shared/README.md:5-13

Summary

The Lucky project provides a robust and complete platform for building and optimizing autonomous agentic workflows. By representing workflows as evolvable JSON structures and applying both iterative and genetic optimization algorithms, it enables the automatic discovery of more efficient and successful agent collaboration patterns. Its modular architecture, comprehensive persistence layer, and hybrid tool system make it a powerful framework for research and development in the field of multi-agent systems.

Sources: README.md:1-8, packages/core/README.md:460-470