Skip to main content
Evolve is the engine. Give it a goal it can score and it runs a campaign: propose a candidate, implement it on its own git branch, evaluate it, judge the result, and repeat with what it learned.

How does a campaign work?

The system works by:
  1. Receiving a goal: What you want to build (include success criteria in the goal)
  2. Initializing repo: From initial_repo, workflow search, or empty
  3. Gathering context: From the knowledge graph and repo memory
  4. Generating solutions: Via pluggable coding agents
  5. Asking you when only you can help: A session that needs a credential, access or a file only a person can provide records a request in the inbox; the campaign pauses and your reply continues that same session
  6. Running evaluation: Agent builds and runs evaluation in kapso_evaluation/
  7. Generating feedback: Feedback generator validates results and decides stop/continue

What are the pieces?

Orchestrator

Central coordinator that manages the experimentation loop, budget tracking, and component lifecycle

Search Strategies

The generic strategy: how candidates are generated, run and recorded

Coding Agents

Pluggable code generators: Claude Code, Codex, Gemini, OpenHands and more

Feedback Generator

Validates evaluation results and decides when to stop

Repo Memory

Tracks code understanding with file-level evidence

Inbox

Where a session asks you for what only you can provide, and how your reply resumes it

How do I run one?

How do I start from an existing repo?

When evolve() is called, the system initializes the workspace:

Configuration modes

Two ship, both running the generic strategy:
Each experiment runs on its own Git branch (generic_exp_N), so attempts stay isolated and every one can be checked out later — see Experiment lifecycle.

Workspace structure

After setup, the workspace looks like:

What does a campaign remember?

Evolve uses two memory systems:

Repo memory

Tracks understanding of the codebase:
  • Architecture — High-level structure and patterns
  • Key Claims — Important facts about the code
  • File Evidence — Which files support each claim

Experiment history

Learns from past experiments via MCP tools:
  • Top Experiments — Best scoring experiments
  • Recent Experiments — Most recent experiments
  • Similar Experiments — Semantic search for related experiments

How do I bound a campaign?

The Orchestrator tracks costs across all components:
Budget limits can be set via max_iterations or time/cost budgets in configuration.

Architecture

Deep dive into system architecture

Execution Flow

Detailed walkthrough of the execution process

Search Strategies

How tree search and linear search explore solutions

Experiment Lifecycle

Lifecycle of a single experiment
Related pages: Orchestrator · Search Strategies · Coding Agents · Feedback Generator · Repo Memory · Architecture · Execution Flow · Experiment Lifecycle Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.