openevolve - Moses Yebei

The Problem

OpenEvolve is an open-source implementation of AlphaEvolve, an evolutionary coding agent that turns LLMs into autonomous code optimizers. The repository contains 465 files across three projects (examples, openevolve core, and scripts), with Python as the dominant language (214 files). The core challenge for anyone working with this codebase is navigating the cognitive load: two files exceed 1800 lines (openevolve/database.py and openevolve/process_parallel.py), three hub modules have 52+ dependent modules each, and 22 files exhibit deep nesting at 6+ levels. These structural properties mean that changes ripple widely and control flow is hard to follow.

What This Does

The repository provides an evolutionary system for automated code optimization and discovery. The openevolve core (42 files) defines the evolutionary algorithm, configuration, database management, and evaluation pipeline. Key entry points include openevolve/cli.py which reaches 400 functions, and openevolve/run_evolution for library usage. The examples directory (329 files) contains concrete problem instances—circle packing, affine transforms, eigenvalue problems, and math inequalities—each with initial programs, evaluators, and configs. The scripts directory (16 files) contains JavaScript-based tooling. The system resolves 222 internal modules with 200 import edges and 5 circular dependencies, and 20 functions call external models for inference while 66 functions read/write files.

How It Is Wired

Execution starts at openevolve/cli.py:174 (main) which reaches 400 functions and is called from 1 place. The call graph flows: main → parse_args → create_task_files → filesystem operations via output_dir.mkdir. The config module (openevolve/config.py) is called from 37 other files and defines resolveenv_var, __post_init__, update_model_params, rebuild_models—the database module (openevolve/database.py) is called from 30 files and handles safesum_metrics, safeavg_metrics, to_dict, from_dict, __init__, with file read/write operations. The evaluator (openevolve/evaluator.py) is called from 10 files and defines evaluate_program, processevaluation_result. A traced path from main to external effect: main → create_task_files [filesystem via output_dir.mkdir]. The config hub has instability 0.02 (Ca 52, Ce 1); the database module has instability 0.14 (Ca 30, Ce 5); the controller module has the highest instability at 0.53 (Ca 8, Ce 9), meaning small changes there have wide blast radius. Import cycles exist in the JavaScript tooling (scripts/static/js/graph.js, main.js, sidebar.js). The system makes 20 model calls for inference and 6 outbound network calls across its operation.

How To Use It

Setup: Install via pip: pip install openevolve. The Dockerfile uses python:3.12-slim; pin this by digest for reproducibility. The repository has a pyproject.toml but no committed lockfile—run the package manager once and commit the generated lockfile.

Configuration: Required environment variable OPENAI_API_KEY (the README notes Gemini can use OPENAI_API_KEY env var). Config files live in configs/ (default_config.yaml, early_stopping_example.yaml, island_config_example.yaml, island_examples.yaml). Example problem configs are under examples/alphaevolve_math_problems/ and examples/algotune/.

Running it: Command from the README:

python openevolve-run.py examples/function_minimization/initial_program.py \
  examples/function_minimization/evaluator.py \
  --config examples/function_minimization/config.yaml \
  --iterations 50

Library usage: from openevolve import run_evolution, evolve_function. The CLI entry point is openevolve/cli.py.

Code Health & Issues

The static analysis identified 125 findings (20 high, 105 medium, 0 low) across 8 kinds:

CRITICAL - Secrets in workflows: .github/workflows/claude.yml contains CLAUDE_CODE_OAUTH_TOKEN (publish or cloud scope); a PR becomes credential exfiltration risk. Fix: move secret-using steps into workflow_run job that never checks out PR code.
HIGH - Pin third-party GitHub Actions to commit SHAs: anthropics/claude-code-action@beta, pypa/gh-action-pypi-publish@release/v1, docker/setup-qemu-action@v3, docker/setup-buildx-action@v3 are unpinned. Fix: replace @vN with 40-char commit SHA.
HIGH - No lockfile beside pyproject.toml manifest. Fix: run package manager once and commit generated lockfile.
MEDIUM - Broad exception handling x21 across openevolve/prompt/sampler.py, openevolve/api.py, examples/algotune/affine_transform_2d/best_program.py. Fix: catch specific exceptions; re-raise or log the rest.
MEDIUM - Empty catch block in scripts/static/js/sidebar.js. Fix: handle, rethrow, or at least log the error.
MEDIUM - Deep nesting x22 in openevolve/config.py, openevolve/database.py, openevolve/evaluator.py. Fix: flatten with early returns/guard clauses; extract inner blocks.
MEDIUM - Oversized files: openevolve/database.py (1801 lines), openevolve/process_parallel.py. Fix: split into cohesive units by responsibility.
MEDIUM - Hub modules: openevolve/config.py (52 deps), openevolve/database.py (30 deps), openevolve/evaluation_result.py (19 deps). Fix: keep stable and small; move volatile logic out.
MEDIUM - Duplicated code: 2798 repeated 6-line blocks across 117 files in algotune examples. Fix: extract shared helpers.
MEDIUM - Dependency management: no Dependabot/Renovate configured across 2 manifests. Fix: commit .github/dependabot.yml covering repo ecosystems plus github-actions.
MEDIUM - Dockerfile uses mutable base python:3.12-slim. Fix: pin by digest; enable Dependabot docker ecosystem.
MEDIUM - GITHUB_TOKEN permissions not declared in workflows. Fix: add permissions: contents: read at top of workflows.
LOW - No job timeout-minutes on .github/workflows/claude.yml; 2 jobs can run to six-hour platform default. Fix: add realistic timeout-minutes per job.

The Bottom Line

This is a functional evolutionary code optimization system with a working AlphaEvolve implementation and substantial example coverage across math, GPU, and algorithm design domains. The codebase shows signs of rapid growth—large files, deep nesting, and many interdependencies—which makes modification higher-effort than a typical 465-file repo. The critical credential exposure risk in the GitHub Actions workflow and the absent lockfile are the most urgent SDLC fixes. Teams comfortable with LLM-driven optimization and willing to navigate the cognitive load of the core modules will find value here; others should expect a significant ramp-up period.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

465 files

Python214
YAML71
Markdown27
JSON21
Shell8
JavaScript8

Docker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["examples 130 modules"] g1["tests 52 modules"] g2["openevolve 28 modules"] g3["scripts 10 modules"] g4["(root) 2 modules"] g1 -->|100| g2 g0 -->|15| g2 g4 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 222, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_openevolve_config["config"] n1_openevolve_database["database"] n2_openevolve_evaluation_result["evaluation_result"] n3_openevolve_evaluator["evaluator"] n4_openevolve_prompt_sampler["sampler"] n5_openevolve_controller["controller"] n6_openevolve_llm_ensemble["ensemble"] n7_openevolve_utils_code_utils["code_utils"] n8_openevolve_process_parallel["process_parallel"] n9_scripts_static_js_graph["graph"] n5_openevolve_controller --> n0_openevolve_config n5_openevolve_controller --> n1_openevolve_database n5_openevolve_controller --> n3_openevolve_evaluator n5_openevolve_controller --> n6_openevolve_llm_ensemble n5_openevolve_controller --> n8_openevolve_process_parallel n5_openevolve_controller --> n4_openevolve_prompt_sampler n5_openevolve_controller --> n7_openevolve_utils_code_utils n1_openevolve_database --> n0_openevolve_config n1_openevolve_database --> n7_openevolve_utils_code_utils n3_openevolve_evaluator --> n0_openevolve_config n3_openevolve_evaluator --> n1_openevolve_database n3_openevolve_evaluator --> n2_openevolve_evaluation_result n3_openevolve_evaluator --> n6_openevolve_llm_ensemble n3_openevolve_evaluator --> n4_openevolve_prompt_sampler n6_openevolve_llm_ensemble --> n0_openevolve_config n8_openevolve_process_parallel --> n0_openevolve_config n8_openevolve_process_parallel --> n1_openevolve_database n8_openevolve_process_parallel --> n6_openevolve_llm_ensemble classDef cyc stroke:#ef4444,stroke-width:2px; class n9_scripts_static_js_graph cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

high2

medium6

low1

Keep secrets out of workflows a fork can triggercritical

.github/workflows/claude.yml

CLAUDE_CODE_OAUTH_TOKEN (publish or cloud scope)

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

anthropics/claude-code-action@beta, pypa/gh-action-pypi-publish@release/v1, docker/setup-qemu-action@v3, docker/setup-buildx-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/python-test.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/claude.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/claude.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.