optivibe-mcp
AGENTS.md19 starsChanged 21 days agoApache-2.0View on GitHub
OptiVibe is an MCP server that lets you (the agent) drive Zemax OpticStudio for optical lens design. You reason about the design; the typed tools take the verified action against the ZOS-API. This file is your operating guide — read the session and trust models first, they change how you must interpret every tool result. For install and setup, see README.md. For data provenance and licensing, see PROVENANCE.md. - Single seat (N = 1). One OpticStudio engine, one design at…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- bench-catalogSkill
- design-aberration-reviewSkill
- design-compareSkill
- design-glass-matchingSkill
- design-reviewSkill
- design-tolerance-desensitizeSkill
- design-vision-reviewSkill
- optimize-loopSkill
- zos-api-debugSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
Uncomputable merit: If a wide-field / fast merit can't be evaluated (a corner ray won't trace at full pupil), apply corner vignetting …
- Very specific: line 53
Snapshot the start: Before optimizing, save_snapshot (or save_candidate) the starting form — there is no reliable in-session undo.
- Very specific: line 56
Save keepers: After each accepted optimize, save_candidate the result.
- Distinctive: line 62
Do not guess an operand code, a glass name, or a typed member.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OptiVibe — driving Zemax OpticStudio with Claude
OptiVibe is an MCP server that lets you (the agent) drive Zemax OpticStudio for optical lens design. You reason about the design; the typed tools take the verified action against the ZOS-API. This file is your operating guide — read the session and trust models first, they change how you must interpret every tool result.
For install and setup, see README.md. For data provenance and licensing, see PROVENANCE.md.
The session model — read this first
- Single seat (N = 1). One OpticStudio engine, one design at a time. Calls are serialized; do not assume concurrency.
- Lazy engine-open. The engine seat is taken on the first design-touching tool call, not at startup. Reference and lookup tools run "cold" with no engine open.
- Reaping is automatic. The engine is closed for you on shutdown — you never open or
connect it yourself. When you are done with engine work and something else needs the
seat, call
release_engine.
The trust model — proof, not absence-of-error
- A clean call is not proof of success. Trust the read-back value or the optimizer verdict the tool returns — never merely that the call did not raise.
- Tools return a uniform envelope and never raise. Inspect
result.okand the read-back, not an exception. A tool that couldn't do what you asked tells you so in its envelope (often with a typederror_family); handle that, don't assume success.
The design workflow
A typical session: load or build a starting point → set what's variable → build a merit function → preflight → optimize → assess → checkpoint. The discipline that keeps this honest:
Optimize discipline
- Preflight before you run. Set variables (
set_variable) and a merit function (build_meritor your own operands), thendry_runto confirm readiness without opening the optimizer. - The stop must be free.
optimize/dry_rundefault-refuse a glass-vertex aperture stop — runnormalize_stopfirst (or passauto_normalize). A front-vertex glass stop is also handled bynormalize_stop(it inserts a zero-thickness dummy air stop ahead of the front glass); do not hand-build a dummy stop. - Call
optimizeonce; it owns the loop. It runs monitored optimization internally and returns a verdict (improved/diverged/ …). Read the verdict — do not hand-run cycles. - Uncomputable merit. If a wide-field / fast merit can't be evaluated (a corner ray
won't trace at full pupil), apply corner vignetting (
set_vignetting), then rebuild the merit (build_merit) and re-seed from a gentler form before re-running.
Checkpoint discipline
- Snapshot the start. Before optimizing,
save_snapshot(orsave_candidate) the starting form — there is no reliable in-session undo.optimizealso auto-captures a per-pass.zmxtrail. - Save keepers. After each accepted
optimize,save_candidatethe result; once you have a keeper,promote_bestit. Reuse one design name so a design's candidates stay together.
Grounding — the reference layer
Do not guess an operand code, a glass name, or a typed member. Resolve them from intent through the reference tools:
lookup_operand— merit-function operands by intent.search_reference— full-text search over the OpticStudio manual.lookup_glass/find_glasses/find_glass_pair— glass by name, by property, or an achromatic pair.
The reference layer is session-free (it answers without taking the engine seat) and its data is built locally from your own licensed install. If a piece isn't built, the affected tool returns a typed "unavailable" envelope and the rest keeps working — treat that as "not built here", not a failure.
Manufacturability & judgment
The tools carry design judgment, not just API access — lean on it:
build_meritauthors a positive air-gap floor by default (min_air). The glass floor (min_glass) is authored only when you passglass=true, so pass it or runcheck_clearanceafter optimizing. For a gradient-index surface,grin_dn_maxauthors a per-point restoring box on the index profile: it pulls the profile back toward the envelope, it does not certify it — a satisfied box still admits a spread of up to twicegrin_dn_max. The post-optimize index audit is the authority on what the profile actually is.check_clearanceaudits center/edge thickness and clearances after optimization; a gradient-index element is audited as a solid, at the glass floor.save_candidate/promote_bestgate a keeper on clearance — a manufacturably-thin design can't be promoted silently.
Surface manufacturability as feedback to the user; the user owns the acceptance bands, not the tool.
What you can do
The harness spans a full sequential-design workflow:
- Lens data — surfaces, apertures, fields, wavelengths, stop, glasses and catalogs, per-surface apertures / obstructions.
- Geometry — coordinate breaks, fold mirrors, reflective surfaces, diffraction
gratings, even/odd/extended aspheres, radial and axial gradient-index media.
Gradient2(radial) takesn0as the base index squared — passn0=2.25for a medium of physical index 1.5; onGradient3,n0is the index itself. - Multi-configuration — zoom / focus / conjugate / array systems, config-spanning merit and optimization.
- Merit & optimization — the wizard and hand-authored operands, derived/relational operand math, DLS and Hammer optimization.
- Analysis — first-order, spot, MTF, wavefront, Strehl, distortion, relative illumination, axial/lateral color, collimation, gradient-index profile.
- Tolerancing — sensitivity and Monte-Carlo manufacturability verdicts.
- Figures — headless meridional layout rendering with per-field rays.
Skills
Reach for these Claude Code skills for common workflows — describe the task and the skill is selected:
design-review— assess a design against a spec.design-compare— rank designs side by side.design-vision-review— look at the rendered layout and report what the lens data does not show. ADVISORY: it observes and feeds back, it does not decide.design-aberration-review— read the ray fan and the field curvature / distortion plots and report how the aberrations are balanced. ADVISORY.optimize-loop— set up, preflight, and run optimization with checkpoints.design-glass-matching— the glass step for a settled lens: find the carrier elements, trial swaps against a control, keep one only when image quality improves.design-tolerance-desensitize— the last finishing stage: pick the push compensator, find the tolerance hotspots, and keep a change only when the as-built yield improves.bench-catalog— benchmark and rank a folder of lens designs against a target spec or each other.zos-api-debug— troubleshoot an OpticStudio connection / license error.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

