Overview
Kapso provides a CLI for running experiments without writing Python code.
Basic Usage
kapso evolve --goal "Your problem description"
Options
Goal Specification
| Option | Short | Description |
|---|
--goal | -g | Goal/problem description (inline) |
--goal-file | -f | File containing goal description |
# Inline goal
kapso evolve --goal "Build a classifier for Iris dataset"
# From file
kapso evolve --goal-file problem.txt
Basic Options
| Option | Short | Default | Description |
|---|
--iterations | -i | 10 | Maximum experiment iterations |
--output | -o | auto | Output directory for solution |
kapso evolve --goal "..." --iterations 10 --output ./my_solution
Configuration Options
| Option | Short | Description |
|---|
--mode | -m | Configuration mode (GENERIC, MINIMAL) |
--coding-agent | -a | Coding agent (aider, gemini, claude_code, openhands) |
kapso evolve --goal "..." --mode GENERIC --coding-agent claude_code
Directory Options
| Option | Default | Description |
|---|
--eval-dir | None | Directory with evaluation files (copied to kapso_evaluation/) |
--data-dir | None | Directory with data files (copied to kapso_datasets/) |
--initial-repo | None | Initial repository (local path or GitHub URL) |
kapso evolve --goal "..." \
--eval-dir ./my_evaluation/ \
--data-dir ./my_data/ \
--initial-repo https://github.com/owner/repo
List Commands
| Option | Description |
|---|
--list-agents | List available coding agents |
Examples
Simple Usage
kapso evolve \
--goal "Build a random forest classifier for the Iris dataset"
With Evaluation and Data
kapso evolve \
--goal "Build a classifier with accuracy > 0.9" \
--eval-dir ./evaluation/ \
--data-dir ./data/
Full Options
kapso evolve \
--goal-file problem.txt \
--iterations 20 \
--mode GENERIC \
--coding-agent claude_code \
--initial-repo https://github.com/owner/starter-repo \
--eval-dir ./evaluation/ \
--data-dir ./data/ \
--output ./my_solution
Output
============================================================
EVOLVING: Build a random forest classifier for the Iris dataset
============================================================
Max iterations: 10
Coding agent: from config
Running experiments...
Experiment 1: Developer agent implementing solution...
Experiment 1: Running evaluation in kapso_evaluation/...
Experiment 1: Feedback generator validating results...
Experiment 1 completed with cumulative cost: $0.125
####################################################################################################
Experiment with score 0.92:
# Solution: Random forest with GridSearchCV hyperparameter tuning...
# Feedback: Good progress! Accuracy 0.92 meets the > 0.9 target. Goal achieved.
####################################################################################################
============================================================
Evolution Complete
============================================================
Solution at: ./my_solution
Experiments run: 1
Total cost: $0.125
Stopped reason: goal_achieved
Goal achieved: True
============================================================
COMPLETED
============================================================
Solution: ./my_solution
Goal achieved: True
Final score: 0.92
Cost: $0.125
Stopped reason: goal_achieved
Environment Variables
The CLI loads environment variables from .env:
OPENAI_API_KEY=your-openai-api-key
GOOGLE_API_KEY=your-google-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
Available Coding Agents
$ kapso --list-agents
Available Coding Agents:
==================================================
aider: Git-centric pair programming with diff-based editing
gemini: Google Gemini SDK for code generation
claude_code: Anthropic Claude Code CLI for complex refactoring
openhands: OpenHands agent with sandboxed execution
Exit Codes
| Code | Meaning |
|---|
0 | Success |
1 | Error (missing arguments, failed experiment) |
Tips
Use kapso --list-agents to discover available coding agents.
API keys are required. Set them in .env or as environment variables.
