Optimizing

run

This is the primary command for starting the optimization process. It takes several arguments to configure how Weco should optimize your code.

Command Arguments

Required:

Optional:

Evaluation Requirements

The command specified by --eval-command is crucial for the optimization process. It must:

1. Execute the modified code from your source file(s)
2. Assess its performance
3. Print the metric you specified with --metric along with its numerical value to the terminal

For example, if you set --metric speedup, your evaluation script should output a line like:

speedup: 1.5

Weco will parse this output to extract the numerical value (1.5 in this case) associated with the metric name ('speedup').

For detailed guidance on creating effective evaluation scripts, see Writing Good Evaluation Scripts.

resume

If your optimization run is interrupted (network issues, restart, etc.), resume from the most recent node:

# Resume an interrupted run
weco resume <run_id>

# For example
weco resume 0002e071-1b67-411f-a514-36947f0c4b31

# Resume a completed run with 50 more steps
weco resume <run_id> --steps 50

# Automatically apply the best solution without prompting
weco resume <run_id> --apply-change

# Resume with custom API keys
weco resume <run_id> --api-key openai=your-openai-key gemini=your-gemini-key

The model, log directory, save-logs behavior, and evaluation timeout are all inherited from the original run.

Resume Command Options

derive

A derived run branches off an existing run at a specific step. The code and metric value from that step become the baseline (step 0) of the new run — no re-evaluation, no wasted compute — and a fresh optimization loop continues from there with new LLM context.

Use this to steer the optimizer in a new direction (e.g. "now focus on memory, not speed"), add constraints partway through, explore an alternative branch from a known-good solution, or extend a completed run with more steps. The parent run is stopped by default so you don't pay for two loops at once.

All runs created by derive share a lineage with their parent — the original (non-derived) run is the lineage root, and every derive from it (or from any of its descendants) belongs to the same lineage. The dashboard shows the full tree.

# Derive from the best step seen anywhere in the lineage (default)
weco run derive <run_id>

# Derive from the best step in the specified run only
weco run derive <run_id> --from-step run-best

# Derive from a specific step number
weco run derive <run_id> --from-step 7

# Add steering instructions
weco run derive <run_id> -i "Focus on memory efficiency instead of speed"

# Override the step budget for the derived run
weco run derive <run_id> -n 50

Derive Command Options

Review mode

Pass --require-review to weco run to approve every proposed change before it is evaluated. Each candidate solution waits in a pending-approval state until you (or your agent) inspect it, optionally rewrite it, and submit it for evaluation — only then does the optimizer propose the next step.

# Start a run that waits for your approval at each step
weco run --source model.py \
     --eval-command "python eval.py" \
     --metric accuracy \
     --goal maximize \
     --require-review

# From another terminal: list nodes awaiting approval (includes the proposed code)
weco run review <run_id>

# Optionally replace a pending node's code with your own edit
weco run revise <run_id> --node <node_id> --source model.py

# Approve: evaluate the pending node and unlock the next proposal
weco run submit <run_id> --node <node_id>

weco run status shows the same pending list without code, and weco run diff is handy for inspecting a pending change against the baseline.