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:

Parallel evaluation

--parallel K keeps up to K candidates in flight at once: the backend proposes up to K ideas concurrently, and the CLI evaluates them in K isolated slots — separate checkouts of your project, never your working tree. Speedup can approach K× when evaluation is the bottleneck and the host/provider can sustain the added load; generation latency and shared resources can reduce it. K is chosen once per run, applies to the whole run lineage (derived runs share the same K pool), and cannot be changed mid-run.

How slots are built:

• Git projects use git worktree snapshots plus your uncommitted changes and untracked files; .env is copied per slot, and .venv/venv/node_modules are shared symlinks that evaluation commands must treat as read-only. Non-git projects fall back to plain directory copies.

• Each slot gets its own TMPDIR, XDG_CACHE_HOME, TORCH_EXTENSIONS_DIR, and TRITON_CACHE_DIR (so parallel CUDA/Triton JIT builds don't corrupt each other), plus WECO_SLOT (the slot index) and WECO_PORT_OFFSET (index × 10) for your eval script to disambiguate ports or other shared resources.

• Things git doesn't track (datasets, writable dirs) can be declared in .weco/parallel.toml:

  [slots]
  # provider = "worktree"   # or "copy"; omitted = worktree for git projects
  copy = [".env.test"]       # copied into every slot (per-slot private)
  symlink = ["data"]         # symlinked (shared, read-mostly)

Your eval command must be safe to run concurrently: no fixed ports, no shared writable databases or files, no absolute-path writes into the project. Prove it with weco slots verify -c "<fast smoke eval>" before a long run — it provisions slots and requires two overlapping evaluations to succeed. weco slots clean removes slot directories left behind by crashed runs. If fewer than two isolated slots can be provisioned, the run falls back to serial (K=1). At K>1 a per-evaluation timeout is enforced (your --eval-timeout, or 3600s if unset) so a wedged evaluation can't pin a slot forever.

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.

Web search

Pass --enable-web-search to weco run to have the optimizer research your problem on the web before it starts proposing changes. After the baseline (step 0) evaluation, Weco generates a handful of targeted search queries from your code, metric, and instructions, retrieves recent papers, competition write-ups, and open-source implementations, and synthesizes them into a structured research report with ranked exploration directions.

weco run --source model.py \
     --eval-command "python eval.py" \
     --metric accuracy \
     --goal maximize \
     --enable-web-search

The report is visible to the agent at every subsequent step, with stage-dependent weighting: exploration (draft) steps treat it as a primary source of ideas, improvement steps only borrow small targeted enhancements from it, and debugging steps ignore it. You can read the report yourself in the dashboard's run view, under your instructions dialog.

A few things to know:

• The search runs once per run, between the baseline evaluation and the first proposed change, and adds roughly 30–60 seconds to that first step. If you set a custom --submit-timeout, make sure it accommodates this.
• The search fee and the (small) LLM cost of query generation and report synthesis are billed to your credits.
• The feature degrades gracefully: if the search fails or returns nothing useful, the run simply proceeds without a report.
• Derived runs (weco run derive) inherit the parent run's report instead of searching again.