How does a campaign work?
The system works by:- Receiving a goal: What you want to build (include success criteria in the goal)
- Initializing repo: From
initial_repo, workflow search, or empty - Gathering context: From the knowledge graph and repo memory
- Generating solutions: Via pluggable coding agents
- 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
- Running evaluation: Agent builds and runs evaluation in
kapso_evaluation/ - 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?
Whenevolve() is called, the system initializes the workspace:
Configuration modes
Two ship, both running the generic strategy: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:max_iterations or time/cost budgets in configuration.
Related
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
pip install leeroo-kapso · Every page as plain text: llms.txt.