Skip to main content
By default, a parent is chosen, a branch is cut, and a coding agent implements the candidate and runs its evaluation in one session. The candidate branch and judged result remain available for inspection. With cost-aware selection, evaluation is deferred until the finalized candidate passes an estimate-based cost check. There is no separate debug loop: a failed evaluation surfaces in the session’s tags, the judge marks the evaluation invalid or writes corrective feedback, and the next iteration addresses it.

​
Git branch model

Each experiment runs in its own git branch, inheriting code from its parent experiment. This enables:
  • Isolation: Each experiment starts from a clean parent state
  • Inheritance: Child experiments build on parent solutions
  • Versioning: All code changes are tracked

​
Experiment session

The ExperimentSession manages a single experiment:

​
Default implementation flow

One session does the whole build. run_implementation renders the implementation prompt — the problem, the chosen solution, the knowledge context and the repo memory — and hands it to the coding agent with the budget’s deadline:
The agent is responsible for running the evaluation itself and reporting the result in its closing tags (<code_changes_summary>, <evaluation_script_path>, <evaluation_output>, <score>, <technical_difficulties>). Errors are not retried inside the iteration; they become feedback for the next one.

​
Cost-enabled implementation flow

When search_strategy.params.cost.enabled is true, the coding session builds the candidate and prepares evaluation without running either. After the branch is finalized and evaluator integrity is checked, the orchestrator estimates the materialized candidate’s platform cost. Kapso runs evaluation only if the estimate passes the candidate cap and remaining campaign budget. The feedback generator judges every finalized candidate: on the run’s captured output when a run happened, on the session’s output for a build that errored. Only a completed run can validate a score. A refused candidate is recorded with score = None, an invalid evaluation, and cost feedback for the next idea. It skips both internal evaluation and the optional external iteration evaluator. Exceeding the remaining campaign budget stops with cost_budget_exhausted. See Cost-aware selection for the contract, accounting rules, and the limits of the build-only instruction.

​
Result structure

Each experiment is recorded as a SearchNode — solution, branch, evaluation tags, judged feedback and score. The full field list is on the search strategies page.

​
Session finalization

After an experiment completes:
  1. Commit changes to the experiment branch
  2. Push to origin (available for child experiments)
  3. Record cost from coding agent
  4. Cleanup session folder
The session folder is the only copy of the experiment’s commits until the push succeeds. If origin rejects the push, close_session() raises SessionPushError, keeps the folder, and its message names the exact git push command that recovers the branch. Run that command before resuming: a resumed run rebuilds the node under the same branch name and replaces both the folder and the branch, so the recovered branch is for inspection or cherry-picking. A commit that fails for any reason other than an empty index (for example a pre-commit hook) also raises instead of being skipped.

Execution flow

The loop around one experiment

Coding agents

Who writes the code
Related pages: Execution flow · Coding agents · Orchestrator 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.