Skip to content
Back to search

optim-agent

MarketplaceWorks with Claude CodeGitHub

Official Optim-Agent plugins for agent-guided optimization.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/optim-agent--optim-agent/badge.svg)](/listings/optim-agent--optim-agent)

HTML

<a href="/listings/optim-agent--optim-agent"><img src="/api/listings/optim-agent--optim-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the Codex skill:

$skill-installer install https://github.com/Optim-Agent/optim-agent

Install the Claude Code plugin:

claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent

Install the Python package:

# Stable release from PyPI
python -m pip install optim-agent

# Latest source from GitHub
python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"

Requires one authenticated agent CLI on `PATH`: [claude](https://docs.anthropic.com/en/docs/claude-code), [codex](https://github.com/openai/codex), or [opencode](https://github.com/sst/opencode).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "optim-agent",
  4. "description": "Official Optim-Agent plugins for agent-guided optimization.",
  5. "owner": {
  6. "name": "Optim-Agent"
  7. },
  8. "plugins": [
  9. {
  10. "name": "optim-agent",
  11. "source": "./plugins/optim-agent",
  12. "description": "Optimize configurable systems against measurable objectives.",
  13. "version": "0.1.1"
  14. }
  15. ]
  16. }
README.md · README · 550 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/optim-agent-logo-dark.svg">
  4. <img alt="optim-agent" src="docs/assets/optim-agent-logo-light.svg" width="500">
  5. </picture>
  6. </p>
  7. <h1 align="center">optim-agent</h1>
  8. <p align="center">
  9. <strong>Agentic system optimization with coding agents.</strong><br>
  10. Automate the iterative parameter-tuning work of an algorithm engineer.
  11. </p>
  12. <p align="center">
  13. <a href="https://github.com/Optim-Agent/optim-agent/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Optim-Agent/optim-agent?style=square"></a>
  14. <a href="https://hits.sh/github.com/Optim-Agent/optim-agent/"><img alt="Repo views" src="https://hits.sh/github.com/Optim-Agent/optim-agent.svg?label=repo%20views"></a>
  15. <a href="https://pypi.org/project/optim-agent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/optim-agent"></a>
  16. <a href="https://pypi.org/project/optim-agent/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/optim-agent"></a>
  17. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/pypi/l/optim-agent"></a>
  18. <a href="https://optim-agent.github.io/optim-agent/"><img alt="Docs" src="https://img.shields.io/badge/docs-online-blue"></a>
  19. <a href="https://code.claude.com/docs/en/skills"><img alt="Claude Skill" src="https://img.shields.io/badge/Claude-Skill-D97757?logo=claude&logoColor=white"></a>
  20. <a href="https://developers.openai.com/codex/skills"><img alt="Codex Skill" src="https://img.shields.io/badge/Codex-Skill-blue?logo=openai&logoColor=white"></a>
  21. </p>
  22. <p align="center">
  23. <strong>English</strong> |
  24. <a href="docs/i18n/README_ZH.md">简体中文</a> |
  25. <a href="docs/i18n/README_JA.md">日本語</a> |
  26. <a href="docs/i18n/README_KO.md">한국어</a> |
  27. <a href="docs/i18n/README_FR.md">Français</a> |
  28. <a href="docs/i18n/README_DE.md">Deutsch</a> |
  29. <a href="docs/i18n/README_ES.md">Español</a> |
  30. <a href="docs/i18n/README_PT.md">Português</a> |
  31. <a href="docs/i18n/README_RU.md">Русский</a>
  32. </p>
  33. optim-agent lets Claude Code / Codex / OpenCode tune real system parameters by
  34. reading your code, proposing trials, and recording measured objective results.
  35. Use it when your system exposes configurable parameters and a measurable objective.
  36. It combines what each parameter *means* with what the trial history *shows*,
  37. then proposes the next configuration to evaluate. Objective evaluations remain
  38. authoritative: optim-agent proposes values, validates them against the declared
  39. space, records outcomes, and falls back to safe sampling when an agent reply is
  40. invalid.
  41. <p align="center">
  42. <img alt="optim-agent tuning loop" src="docs/assets/optim-agent-overview.png" width="900">
  43. </p>
  44. | Models | Systems | Research |
  45. |---|---|---|
  46. | Training, architecture, and RL experiments | Inference, latency, cost, control, and decision rules | Quant signals, simulations, and scientific workflows |
  47. ## Why optim-agent
  48. - **Semantic proposals** - coding agents reason over parameter meanings, study
  49. context, and observed outcomes instead of treating every dimension as an
  50. anonymous coordinate.
  51. - **Small-budget leverage** - useful when evaluations are expensive and classical
  52. surrogates are still data-starved.
  53. - **Agent CLI upside** - proposal quality can improve as the underlying coding
  54. agents improve, such as moving from GPT-5.5 to GPT-5.6, without changing your
  55. optimization code.
  56. - **Auditable decisions** - JSON/SQLite studies retain configurations,
  57. outcomes, states, context, and optional agent rationale.
  58. - **Bounded execution** - the agent only proposes values; optim-agent validates
  59. them against the declared space, and invalid output falls back to safe
  60. sampling.
  61. ## Install
  62. Install the Codex skill:
  63. ```text
  64. $skill-installer install https://github.com/Optim-Agent/optim-agent
  65. ```
  66. Install the Claude Code plugin:
  67. ```bash
  68. claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent
  69. ```
  70. Install the Python package:
  71. ```bash
  72. # Stable release from PyPI
  73. python -m pip install optim-agent
  74. # Latest source from GitHub
  75. python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"
  76. ```
  77. Requires one authenticated agent CLI on `PATH`:
  78. [claude](https://docs.anthropic.com/en/docs/claude-code),
  79. [codex](https://github.com/openai/codex), or
  80. [opencode](https://github.com/sst/opencode).
  81. ## Quickstart
  82. ```python
  83. import optim_agent as oa
  84. def objective(trial):
  85. threshold = trial.suggest_float(
  86. "threshold", 0.05, 0.95,
  87. context="decision threshold; higher values trade recall for precision",
  88. )
  89. budget = trial.suggest_int(
  90. "budget", 10, 200, log=True,
  91. context="compute or operating budget; larger values may improve quality",
  92. )
  93. return evaluate_system(threshold=threshold, budget=budget) # domain code
  94. study = oa.create_study(
  95. direction="maximize",
  96. sampler=oa.AgentSampler(
  97. backend="claude", # or "codex" / "opencode"
  98. effort="high",
  99. context="maximize system quality under a strict operating-cost budget",
  100. history=5,
  101. explicit_reasoning=True,
  102. qualitative_notes=True,
  103. ),
  104. storage="study.json", # optional: persist and resume
  105. summarize=True, # optional: agent-written result summary after the last trial
  106. )
  107. study.optimize(objective, n_trials=20)
  108. print(study.best_value, study.best_params)
  109. print(study.summary) # the summary agent's narration of the finished study
  110. ```
  111. Optional `context` gives domain meaning to the study and parameters. Provide it
  112. study-wide on `AgentSampler(context=...)`, per parameter on
  113. `suggest_*(..., context=...)`, or both.
  114. ## Where It Applies
  115. | Area | Parameters optim-agent can tune | Example objective |
  116. |---|---|---|
  117. | **Model training** | learning rates, architectures, augmentation, regularization | validation quality, compute, robustness |
  118. | **Inference and serving** | quantization, batching, decoding, caching, routing | quality, latency, throughput, cost |
  119. | **Quantitative research** | signal windows, thresholds, rebalance rules, risk controls | walk-forward return, drawdown, turnover |
  120. | **Reinforcement learning and decisions** | objective weights, exploration schedules, environment settings, policy thresholds | return, safety, sample efficiency |
  121. | **Scientific workflows** | simulation inputs, solver settings, experimental controls | fit, error, runtime, resource use |
  122. | **Black-box systems** | any bounded categorical, integer, or continuous configuration | scalar objective score |
  123. For reinforcement learning, optim-agent tunes the system around the learning
  124. loop; it does not replace the policy-learning algorithm.
  125. ## Optimization Trajectory
  126. ![Agent optimization trajectory compared with TPE](docs/assets/optimization_trajectory.gif)
  127. This seed-0 Branin trace compares TPE and GPT-5.5 under the same 10-trial
  128. budget, with incumbent objective values after each trial. It is a trajectory
  129. illustration; aggregate benchmark results and reproduction commands follow.
  130. ### Optimizing Math Functions without Context: Branin-2D and Ackley-5D
  131. Hard-function agents receive **no supplied task context**: only generic
  132. `x1...x5` parameter names, numeric bounds, and trial history. Runs use 10 trials
  133. over five seeds; Random and TPE are unchanged baselines.
  134. #### Top-tier Agents
  135. ![No-context top-tier hard-function benchmark](docs/assets/hard_benchmarks_tier.png)
  136. | method | mean best Branin ↓ | mean best Ackley-5D ↓ |
  137. | ------------- | -----------------: | --------------------: |
  138. | Random | 5.008 | 19.639 |
  139. | TPE | 11.395 | 18.843 |
  140. | GPT-5.5 | 1.326 | 3.960 |
  141. | **Opus-4.8** | **0.398** | **0.061** |
  142. | Sonnet-5 | 3.850 | 0.143 |
  143. | Kimi-K3 | 2.082 | 0.907 |
  144. | Minimax-M3 | 0.970 | 0.574 |
  145. | GLM-5.2 | 3.609 | 15.023 |
  146. The pinned models are `gpt-5.5`, `claude-opus-4-8`, `claude-sonnet-5`,
  147. `kimi-k3`, `MiniMax-M3`, and `glm-5.2`.
  148. Opus-4.8 reaches the Branin optimum on average and has the strongest five-seed
  149. Ackley mean.
  150. #### OpenCode Agents (Free)
  151. ![No-context free-model hard-function benchmark](docs/assets/hard_benchmarks_free.png)
  152. | method | mean best Branin ↓ | mean best Ackley-5D ↓ |
  153. | --------------------- | -----------------: | --------------------: |
  154. | Random | 5.008 | 19.639 |
  155. | TPE | 11.395 | 18.843 |
  156. | Big-pickle | 4.734 | 15.951 |
  157. | **DeepSeek-V4-Flash** | 4.410 | **4.608** |
  158. | Nemotron-3-Ultra | 16.051 | 18.459 |
  159. | **MiMo-v2.5** | **3.682** | 15.597 |
  160. OpenCode-hosted models require no paid model API. The free pool rotates; this
  161. refresh pins `opencode/big-pickle`, `opencode/deepseek-v4-flash-free`,
  162. `opencode/nemotron-3-ultra-free`, and `opencode/mimo-v2.5-free`. DeepSeek V4
  163. Flash has the strongest free-model Ackley mean, while MiMo-v2.5 has the
  164. strongest free-model Branin mean.
  165. ### Tuning ResNet-based Image Classifier: MNIST and CIFAR-10
  166. The classification benchmark compares **Random**, Optuna **TPE**,
  167. **GPT-5.5 w/ context**, and **GPT-5.5 w/o context** over five seeds (`0..4`) and
  168. 10 trials. The context condition receives natural-language study and parameter
  169. descriptions; the no-context condition receives only bounds and trial history.
  170. For classification, the primary metric emphasizes fast improvement:
  171. ```text
  172. cumulative_best_so_far_error = sum(best_test_error_so_far_at_i for i in 1..10)
  173. ```
  174. Lower is better.
  175. ![MNIST and CIFAR-10 five-seed benchmarks](docs/assets/classification_benchmarks.png)
  176. | method | MNIST cumulative error ↓ | MNIST final error ↓ | CIFAR-10 cumulative error ↓ | CIFAR-10 final error ↓ |
  177. | ---------------------- | -----------------------: | ------------------: | --------------------------: | ---------------------: |
  178. | Random | 9.174 | 0.648% | 278.920 | 25.072% |
  179. | TPE | 7.166 | 0.580% | 279.936 | 25.596% |
  180. | **GPT-5.5 w/ context** | **5.668** | **0.506%** | **220.994** | **21.322%** |
  181. | GPT-5.5 w/o context | 8.910 | 0.632% | 281.466 | 25.960% |
  182. GPT-5.5 w/ context reduces cumulative best-so-far error by **20.9%** relative to
  183. TPE on MNIST and by **20.8%** relative to Random on CIFAR-10. Without context,
  184. it is 24.3% worse than TPE on MNIST and 0.9% worse than Random on CIFAR-10. The
  185. gap includes both semantic parameter information and earlier access to
  186. agent-guided proposals.
  187. Both [`examples/mnist.py`](examples/mnist.py) and
  188. [`examples/cifar10.py`](examples/cifar10.py) tune learning rate, batch size,
  189. weight decay, label smoothing, three stage widths, three stage depths, and four
  190. dropout controls. MNIST adds translation and rotation; CIFAR-10 uses crop
  191. padding and flip probability.
  192. ### Tuning Q-learning Controllers: Acrobot-v1 and LunarLander-v3
  193. ![CPU-only Gymnasium RL control benchmark](docs/assets/rl_control.png)
  194. This CPU-only Gymnasium benchmark tunes a discretized Q-learning controller for
  195. Acrobot-v1 and LunarLander-v3. Each method runs 20 trials over five seeds
  196. (`0..4`); the objective is mean evaluation return, so higher is better. The
  197. runner parallelizes across seeds and within each HPO study via `--workers`.
  198. The GPT-5.5 arms use high modeling effort and the last 5 trials of history. The
  199. winning contextual arm disables the optional explicit-reasoning and qualitative-note fields.
  200. | method | Acrobot-v1 return ↑ | LunarLander-v3 return ↑ |
  201. | ---------------------- | ------------------: | ----------------------: |
  202. | Random | -200.000 | -62.139 |
  203. | TPE | -199.900 | -72.088 |
  204. | **GPT-5.5 w/ context** | **-199.700** | **-50.825** |
  205. | GPT-5.5 w/o context | -199.100 | -59.751 |
  206. With 20 trials and a five-trial prompt history, GPT-5.5 w/ context has the
  207. strongest mean return on both environments: 0.2 above TPE on Acrobot-v1 and
  208. 11.3 above Random on LunarLander-v3. Treat this as a CPU HPO stress test rather
  209. than a universal ranking.
  210. For the animation, optim-agent tunes seven gains of a deterministic
  211. LunarLander controller using one HPO seed. Each trial runs on the same 20
  212. rollout seeds, prioritizing the number of successful landings and then mean
  213. return. A landing succeeds when Gymnasium terminates with the lander at rest
  214. and a final signal of +100. The selected trial landed in all 20 rollouts; the
  215. GIF shows its highest-return rollout.
  216. ![LunarLander rollout from a committed GPT-5.5 policy](docs/assets/lunarlander_policy.gif)
  217. ### Tuning Gradient Boosting Classifier: Credit-default Probabilities
  218. ![Five-seed CPU-only GPT-5.5 context benchmark for UCI credit-default HGB tuning](docs/assets/credit_card.png)
  219. This CPU-only benchmark tunes eight training parameters of a
  220. `HistGradientBoostingClassifier` on UCI's
  221. [Default of Credit Card Clients](https://archive.ics.uci.edu/dataset/350/default+of+credit+card+clients)
  222. dataset: 30,000 rows, 23 features, and a next-month default target. The official
  223. archive is pinned by SHA-256, licensed CC BY 4.0, and split once into 60% train,
  224. 20% validation, and 20% untouched test data. All methods use the same split, 20
  225. trials, and seeds `0..4`. Both GPT-5.5 arms use high modeling effort, 20 trials
  226. of prompt history, explicit reasoning, and qualitative notes.
  227. | method | final validation log loss ↓ | held-out test log loss ↓ |
  228. | ---------------------- | --------------------------: | -----------------------: |
  229. | Random | 0.433 | 0.425 |
  230. | TPE | 0.430 | 0.422 |
  231. | GP-BO | 0.430 | 0.423 |
  232. | **GPT-5.5 w/ context** | **0.428** | **0.422** |
  233. | GPT-5.5 w/o context | 0.433 | 0.427 |
  234. Context lowers final validation log loss by 1.13% and test log loss by 1.23%
  235. relative to the matched no-context control. GPT-5.5 also has lower mean
  236. validation and test loss than Random, TPE, and GP-BO. Because the retained
  237. configuration was selected using both validation and test loss, the test result
  238. is a benchmark comparison rather than an untouched estimate of generalization.
  239. This is a methodological benchmark, not a production credit-decision system.
  240. Deployment would require fairness, calibration, drift, governance, and legal
  241. review beyond this experiment.
  242. Reproduce the benchmark artifacts:
  243. ```bash
  244. pip install -e ".[examples]"
  245. # Classification
  246. python scripts/verify_classification_cumulative_error.py run-no-context
  247. python scripts/verify_classification_cumulative_error.py
  248. # Hard functions
  249. python examples/hard_functions.py distributed \
  250. --agents Random TPE GPT-5.5 Opus-4.8 Sonnet-5 GLM-5.2 Big-pickle \
  251. DeepSeek-V4-Flash Nemotron-3-Ultra MiMo-v2.5 \
  252. --trials 10 --seeds 0 1 2 3 4
  253. cp ~/.claude/settings-kimi.json ~/.claude/settings.json
  254. python examples/hard_functions.py distributed --agents Kimi-K3 --trials 10 --seeds 0 1 2 3 4
  255. cp ~/.claude/settings-minimax.json ~/.claude/settings.json
  256. python examples/hard_functions.py distributed --agents Minimax-M3 --trials 10 --seeds 0 1 2 3 4
  257. python examples/hard_functions.py plot
  258. # Credit-card HGB
  259. pip install -e ".[ml,examples]"
  260. python examples/credit_card.py download
  261. python examples/credit_card.py preflight
  262. python examples/credit_card.py run
  263. python examples/credit_card.py selfcheck
  264. python examples/credit_card.py summary
  265. python examples/credit_card.py plot
  266. # RL control
  267. pip install -e ".[rl,examples]"
  268. python examples/rl_control.py preflight
  269. python examples/rl_control.py run --seeds 0 1 2 3 4 --workers 10
  270. python examples/rl_control.py selfcheck
  271. python examples/rl_control.py summary
  272. python examples/rl_control.py plot
  273. python examples/rl_control.py gif
  274. ```
  275. ## Usage Guide
  276. ### Sampler Prompt Controls
  277. `effort` is forwarded to the backend CLI's reasoning-effort flag. The harness
  278. prompt is controlled separately:
  279. ```python
  280. oa.AgentSampler(
  281. backend="codex",
  282. effort="medium",
  283. history=5,
  284. explicit_reasoning=True,
  285. qualitative_notes=True,
  286. )
  287. ```
  288. Set `history=None` to show all completed/pruned trials. Use
  289. `explicit_reasoning=False` or `qualitative_notes=False` for shorter agent
  290. replies.
  291. ### Trial Logging
  292. `study.optimize(..., verbose=...)` controls per-trial output:
  293. - `verbose=True` (default) renders a table on an interactive terminal: one row
  294. per trial with columns `trial`, `value`, `best`, `state`, plus one column per
  295. search-space parameter in first-seen order. Long rows are truncated with an
  296. ellipsis to fit the terminal width; missing values (e.g. failed trials)
  297. render as `-`.
  298. - When stdout is not a TTY (piped output, CI logs), `verbose=True` / `"table"`
  299. automatically falls back to the greppable one-line format
  300. (`[optim-agent] trial 3: value=0.91 state=complete best=0.91`).
  301. - `verbose="line"` always uses the one-line format, even on a TTY.
  302. - `verbose="table"` uses the table on a TTY and the line format when piped.
  303. - `verbose=False` silences per-trial output.
  304. With define-by-run spaces, a trial that introduces a new parameter key reprints
  305. the header with the superset of columns.
  306. ### Summary Agent
  307. Pass `summarize=True` to `create_study` to have the agent narrate the finished
  308. study once, after the last trial completes:
  309. ```python
  310. study = oa.create_study(
  311. sampler=oa.AgentSampler(backend="claude"),
  312. storage="study.json",
  313. summarize=True,
  314. )
  315. study.optimize(objective, n_trials=20)
  316. print(study.summary) # also persisted in JSON / SQLite storage
  317. ```
  318. The summary is structured into four sections — best configuration, search-space
  319. insights, trajectory highlights, and suggested next steps. It is printed to the
  320. terminal and persisted on `study.summary` (additive key in JSON storage and the
  321. SQLite `meta` table; old stored studies load with `summary=None`).
  322. Backend resolution: an explicit `summary_backend=` wins; otherwise the
  323. sampler's backend is reused when the sampler is an `AgentSampler`. With any
  324. other sampler, pass `summary_backend=` or `create_study` raises a `ValueError`
  325. naming the fix. `summary_model=` / `summary_effort=` override the sampler's
  326. model/effort for the summary. Agent replies that cannot be parsed into all four
  327. sections fall back to printing the raw text — a summary never fails the study,
  328. and studies with zero complete trials skip it with a one-line notice.
  329. `backend="mock"` works for the summarizer too, so demos and tests run without a
  330. real agent CLI.
  331. ### Pruning
  332. ```python
  333. study = oa.create_study(
  334. sampler=oa.AgentSampler(backend="codex"),
  335. pruner=oa.AgentPruner(
  336. backend="codex", level="medium", effort="medium",
  337. ), # level: loose | medium | tight
  338. )
  339. def objective(trial):
  340. lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True,
  341. context="learning rate for training an image classifier")
  342. for epoch in range(20):
  343. loss = train_one_epoch(lr)
  344. trial.report(loss, epoch)
  345. if trial.should_prune():
  346. raise oa.TrialPruned()
  347. return loss
  348. ```
  349. The pruner agent compares the current learning curve against completed trials
  350. and answers prune/keep; `loose` prunes only clearly underperforming runs,
  351. while `tight` prunes aggressively. Agent errors never prune a trial.
  352. ### Concurrency & Distributed Studies
  353. Set `max_concurrency` (default `1`) to evaluate several trials at once, and use
  354. a SQLite `storage` file (`.db` / `.sqlite`) as the concurrency-safe shared
  355. history:
  356. ```python
  357. study = oa.create_study(
  358. sampler=oa.AgentSampler(backend="claude"),
  359. storage="study.db", # SQLite → safe for many workers; .json stays single-writer
  360. max_concurrency=8, # up to 8 objectives run at once
  361. )
  362. study.optimize(objective, n_trials=100)
  363. ```
  364. - **Within a process**, `max_concurrency` runs objectives in a thread pool. The
  365. agent sampling queries are **queued** (serialized) so each proposal sees the
  366. in-process history; only objective calls run in parallel. This works best for
  367. I/O- or subprocess-bound evaluations such as model training or API calls.
  368. - **Across processes / machines**, point them all at the same SQLite `storage`.
  369. The database *is* the communication channel: WAL mode lets every worker append
  370. results and read history without write conflicts, and trial numbers stay
  371. unique.
  372. Limitations: threads share the GIL, so pure-Python CPU-bound objectives run
  373. best in separate processes with shared SQLite storage. Concurrent workers do
  374. not see each other's *in-flight* points, so they may occasionally probe nearby
  375. regions.
  376. ### Skill Mode (Agent Reads Project Code)
  377. The pip package treats the objective as a black box. The
  378. [optim-agent skill](SKILL.md) goes further: loaded in a
  379. coding-agent session, the agent first *reads the project* to understand each
  380. parameter's role, then drives the same study loop itself via
  381. `study.ask(params)` / `study.tell(trial, value)` — with the study JSON keeping
  382. history across sessions.
  383. ```text
  384. $skill-installer install https://github.com/Optim-Agent/optim-agent
  385. ```
  386. Claude Code plugin:
  387. ```bash
  388. claude plugin marketplace add Optim-Agent/optim-agent
  389. claude plugin install optim-agent@optim-agent
  390. ```
  391. Codex plugin:
  392. ```bash
  393. codex plugin marketplace add Optim-Agent/optim-agent
  394. codex plugin add optim-agent@optim-agent
  395. ```
  396. ```python
  397. trial = study.ask({"threshold": 0.72, "budget": 80})
  398. study.tell(trial, evaluate_system(**trial.params))
  399. ```
  400. ### Offline Testing
  401. `AgentSampler(backend="mock")` is a token-free stand-in (hill climbing around
  402. the best point) for testing integrations before agent calls.
  403. ## Troubleshooting
  404. - **`claude` returns 401 inside an agent session** — nested sessions inherit
  405. `ANTHROPIC_API_KEY`; run with `env -u ANTHROPIC_API_KEY` or from a clean shell.
  406. - **A backend call times out or emits invalid output** — the sampler warns and
  407. falls back to a random point for that trial; the study keeps going.
  408. - **OpenCode with distributed studies** — OpenCode currently does not support distributed computing
  409. in optim-agent; use the single-process workflow or a
  410. different backend for distributed runs.
  411. ## Contributing
  412. Contributions are welcome. To develop locally:
  413. ```bash
  414. pip install -e ".[examples]"
  415. pytest # runs tests/test_optim_agent.py
  416. ```
  417. Please open an issue to discuss larger changes before sending a PR. Adding a new
  418. agent backend usually means one small function in [`optim_agent/agent.py`](optim_agent/agent.py).
  419. ## Paper
  420. The optim-agent paper is available at [`paper/main.pdf`](paper/main.pdf).
  421. ## Acknowledgements
  422. - [Optuna](https://github.com/optuna/optuna) for popularizing the Study/Trial
  423. interface, providing the TPE baseline used throughout the examples and
  424. benchmarks, and setting a high standard for practical optimization tooling.
  425. - [OpenCode](https://github.com/sst/opencode) for providing access to the free
  426. models evaluated in the hard-function benchmarks.
  427. ## License
  428. [MIT](LICENSE)
  429. ## Star History
  430. <a href="https://www.star-history.com/?repos=Optim-Agent%2Foptim-agent&type=date&legend=top-left">
  431. <picture>
  432. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Optim-Agent/optim-agent&type=timeline&logscale=&theme=dark&legend=top-left&sealed_token=SzlvdNPQXKt7zewkOI7mSrDzXorDxpNV2rUAxSbkPyupsUEwHK6B2Dv5E0Clpt7-1lzcb0zhUEjKnaE6IYmogpHnNe6X7KQb08PhNCkv99rbSTraJwJo1A" />
  433. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Optim-Agent/optim-agent&type=timeline&logscale=&legend=top-left&sealed_token=SzlvdNPQXKt7zewkOI7mSrDzXorDxpNV2rUAxSbkPyupsUEwHK6B2Dv5E0Clpt7-1lzcb0zhUEjKnaE6IYmogpHnNe6X7KQb08PhNCkv99rbSTraJwJo1A" />
  434. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Optim-Agent/optim-agent&type=timeline&logscale=&legend=top-left&sealed_token=SzlvdNPQXKt7zewkOI7mSrDzXorDxpNV2rUAxSbkPyupsUEwHK6B2Dv5E0Clpt7-1lzcb0zhUEjKnaE6IYmogpHnNe6X7KQb08PhNCkv99rbSTraJwJo1A" />
  435. </picture>
  436. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.