What is OPAL?
OPAL (OPtimizer with an Agent in the Loop) wraps an existing torch.optim optimizer in one line. Every so often during training, a coding agent, Claude Code by default, reads the losses, gradient statistics and its own analysis reports, then decides whether to rewrite two small Python programs: the update rule that turns gradients into parameter updates, and the analysis code that measures what it wants to watch. It can change learning rates, schedules, momentum, preconditioning and clipping per parameter group, but is told not to touch the model, data, loss or evaluation.
It is the research code behind the paper Reactive Optimizers by Xingjian Bai, Jia-Hao Liang, Jayden Teoh and Vincent Sitzmann (arXiv 2610.33826), released as a usable package: pip install opal-optimizer, with a CLI for dry runs, cost estimates, live monitoring and an HTML report of every decision and code diff. An experimental Codex backend is included.
The repository was created on 21 October 2026, is MIT-licensed, has about 440 stars, and v0.3.10 shipped on 3 November 2026.
Is OPAL worth it?
OPAL is worth a look for anyone paying for training runs measured in hours, and of little use below that. The idea is that a fixed optimizer recipe is chosen before training and never revisited; OPAL lets an agent watch the run and rewrite the update rule mid-flight. Until the agent changes something, a wrapped run is bit-for-bit identical to the plain one, and the backend="keep" dry run proves it at no cost, which is the right first test to offer a sceptical engineer.
The authors' results are encouraging and thin. On SiT-B/2 at ImageNet 256 the FID-50K fell from 35.7 to 23.6, and on LightningDiT-B/1 from 3.22 to 2.31 with guidance, but each figure is one run per setting, self-reported, and the README notes that one modded-nanogpt run on version 0.2.0 ended worse than the record it started from. Because the agent decides differently each time, your numbers will vary.
The time cost is fixed per decision rather than per step. A decision takes about 40 s on average in the authors' runs, which added 0.49 h to a 3.75 h RAEv2-B run but turned 1 to 3 minute one-GPU scripts into 27 to 31 minutes. blocking=False lets training continue while the agent thinks, at the price of noisier behaviour.
Security deserves a plain sentence. The agent's shell runs in an OS sandbox with no network, but the optimizer code it writes runs inside your training process with your permissions and is not sandboxed. By default it also reads copies of your training script and model code, which go to Anthropic; share_code=False keeps them out. Every program version is kept on disk, so the final optimizer is Python you can read and reuse without the agent.
The limits are those of a three-week-old research package: single node only, no FSDP, DeepSpeed or multi-node, no rollback of training itself, and no spending cap unless you set max_cost_usd. As a way to find a better optimizer recipe for a model family you will train many times, it is more interesting than as a button to press on every job.
Where it earns its place
A PhD student training diffusion models on one 8x H100 node
Find a better learning-rate and optimizer schedule without a full sweep
Wrap AdamW, run the free keep dry run, then a capped agent run of a few hours. The authors' RAEv2-B run cost $13.30 in agent usage and added 0.49 h of waiting; the final program in programs/ can be reused on later runs.
An ML lead at a 15-person startup pretraining small language models
Judge whether an agent-tuned optimizer is worth adopting before committing compute
Run opal estimate first to see waiting time and cost, then compare a wrapped and plain run with opal compare. Expect run-to-run variation, so budget for at least two agent runs before drawing conclusions.
A university course teaching optimisation for deep learning
Show students how optimizer choices play out during a real run
The CPU MNIST example takes about 15 s per plain run; the agent version took 862 s and $2.70 in the authors' test. The HTML report shows each decision, its reasoning and the diff.
Before you commit
- Setup
- pip install opal-optimizer into your training environment (Python 3.10+, PyTorch 2.5+), run opal doctor, then wrap your optimizer with opal.wrap and a one-sentence goal. Claude Code must be installed and logged in on the rank-0 machine; a mailbox broker covers GPU nodes without internet.
- Integrations
- Any torch.optim optimizer and scheduler; Hugging Face Trainer through opal.hf.OpalTrainer; Accelerate after accelerator.prepare with limits. Claude Code is the default backend (claude-opus-5-5, high effort); Codex is experimental.
- Data and privacy
- The agent sees your goal, parameter names and shapes, losses, its own reports and, by default, read-only copies of your training script and model code, all sent to the model provider. Logged metrics stay local unless show_agent=True. Agent-written optimizer code runs in your process unsandboxed.
- Cost at scale
- Agent cost was $9.71 to $17.25 per multi-hour run in the authors' published examples, plus the extra GPU time while training waits, for example 0.66 h on a 6.13 h LightningDiT run. max_cost_usd caps Claude spending; it does not cap Codex.
- Limits
- Single node only; no FSDP, DeepSpeed or multi-node. It cannot roll back training, only fix its programs at the next decision. Short runs are dominated by agent waiting. Version 0.3.x and under active development.
What’s good
- Wrapped run is bit-for-bit identical until the agent acts
- Free dry run and cost estimate before any agent call
- HTML report with every rationale and code diff
- Runs on CPU, one GPU or DDP within one node
- Agent shell sandboxed with no network
What’s not
- Results are single, self-reported runs
- Agent-written optimizer code runs unsandboxed in your process
- No cost cap unless you set one
- No multi-node, FSDP or DeepSpeed support
Best for
ML researchers and small labs running multi-hour PyTorch jobs on one node who want to explore optimizer changes they would not have tried by hand.
OPAL alternatives
OPAL: common questions
- Is OPAL worth it?
- A clever, carefully instrumented way to let an agent tune a long training run as it goes, but the gains are single runs reported by the authors and it can make a run worse. We rate it 3.6 out of 5.
- How much does OPAL cost?
- Free under the MIT licence. Agent calls are billed to your Claude account; the authors' multi-hour runs cost $9.71 to $17.25 in agent usage.
- What are the downsides of OPAL?
- Results are single, self-reported runs; agent-written optimizer code runs unsandboxed in your process; no cost cap unless you set one; no multi-node, FSDP or DeepSpeed support.
- Who is OPAL best for?
- ML researchers and small labs running multi-hour PyTorch jobs on one node who want to explore optimizer changes they would not have tried by hand.
- How much does OPAL cost for a team or in production?
- Agent cost was $9.71 to $17.25 per multi-hour run in the authors' published examples, plus the extra GPU time while training waits, for example 0.66 h on a 6.13 h LightningDiT run. max_cost_usd caps Claude spending; it does not cap Codex.
- Is OPAL safe for company data?
- The agent sees your goal, parameter names and shapes, losses, its own reports and, by default, read-only copies of your training script and model code, all sent to the model provider. Logged metrics stay local unless show_agent=True. Agent-written optimizer code runs in your process unsandboxed.
- What are the best OPAL alternatives?
- The closest alternatives we have reviewed are The AI Scientist (v1, v2 and v3) and PyTorch.
Answers checked Nov 11, 2026.