Skip to main content
A build takes tens of minutes to hours. Launch it detached, follow it with kapso watch, and come back for the summary block.

Before the launch

Every required row must read [OK ]. These are the checks the build runs itself before it spawns a session, so a missing login fails here in seconds rather than an hour in. See Install.

Launch

--detach prints what you need to follow the run and nothing else:
The run outlives the shell that started it, a coding agent’s tool call included; no nohup or setsid is needed. Without --detach the build runs in the foreground and prints the summary block when it returns. A detached launch also leaves a receipt beside the log, campaign.launch.json, so a watch started before the status file exists can tell a campaign still starting from one that died first. The same from Python, which blocks until the build returns:

Watch

The status file appears within seconds of the launch, in phase setup while the workspace is seeded and repo memory is bootstrapped (minutes), then ideation, implementation, evaluation, feedback, one round per experiment. The header names the harness and the sources from the first second; kapso watch shows the phase, the iteration, the best and the latest score, the budget bar, and the last lines of output. DEAD means the process is gone; STALLED means three heartbeats were missed. Both are resumed the same way, see Resume and budgets. A campaign that failed shows its error line. Before the status file exists, a detached launch’s receipt tells the two cases apart: starting (pid 41213, launched 9s ago; log: …) while the child lives, and stopped before writing a status; the log says why: /home/me/trading/campaign.log once it is gone (exit 1; --follow stops waiting). With no argument, kapso watch lists the campaigns the launch registry knows that are alive or waiting on you, and the learns and ingests running, one line each; --all lists every campaign with its state. When the build has returned, kapso trace campaign lays the record out: every attempt with its sessions and runs, the lessons served, what was voided and on what evidence, the sessions that failed, the delivered candidate. See Read the record.

The summary block

A build ends in one of two blocks:
Stopped is goal_achieved, max_iterations, or budget_exhausted with the dial that ran out; Candidate says none succeeded when no candidate produced a valid measurement. Or:
A session needed something only you can provide. The campaign has paused, not failed (the exit code is 0); see The inbox.

What is in the campaign directory

One git branch per experiment, generic_exp_N; main is the seed. See Review the result and Read the record.

The inbox

When the campaign waits on you

Review the result

The Solution and the record

Read the record

Every attempt, session and run, after the fact

Resume and budgets

Continue a build, give it more
Related pages: The inbox · Review the result · Read the record · Resume and budgets · CLI reference 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.