Your coding agent moonlighting as a hyperparameter optimizer

What it does

optim-agent plugs into the agent CLI you already have—Claude Code, Codex, or OpenCode—and puts it in charge of the propose-evaluate-record loop. You define parameters with natural-language context, run your objective function, and the agent suggests the next configuration based on what each parameter means and what prior trials showed. The framework validates every proposal against your declared bounds and falls back to safe sampling if the agent hallucinates an invalid value.

The interesting bit

The README’s benchmarks show GPT-5.5 with natural-language context beating TPE on MNIST and CIFAR-10 cumulative error, while the same model stripped of context falls behind TPE on MNIST and barely matches random search on CIFAR-10—suggesting the win comes from semantics, not raw model horsepower.

Key highlights

• Semantic proposals: the agent reasons over natural-language parameter descriptions and observed outcomes rather than treating dimensions as anonymous coordinates.
• Bounded execution: the agent only proposes values; optim-agent validates them against the declared space and falls back to safe sampling on invalid replies.
• Audit trail: studies are stored as JSON or SQLite, retaining configurations, outcomes, states, and optional agent rationale.
• Agent-agnostic backend: works with Claude Code, Codex, or OpenCode, and the authors note proposal quality should improve as the underlying agents improve without changing your optimization code.
• Broad scope: supports training pipelines, inference serving, quantitative research, RL controller tuning, and scientific workflows.

Caveats

• Requires a locally authenticated agent CLI (claude, codex, or opencode); it is not a standalone optimizer.
• The README’s benchmarks show that stripping away natural-language context makes GPT-5.5 underperform TPE and random search on image-classification tasks, so the semantic annotations are not optional window dressing.
• Free-model availability through OpenCode rotates, so reproducibility with zero-cost tiers may vary.

Verdict

Try it if you already run an agent CLI locally and your objective evaluations are expensive enough that ten semantic trials beat ten random draws. Skip it if your search space is cheap to sample densely or if you need guaranteed reproducibility from free-model pools that rotate.