agentleFS
chuang44-tiffchuang44-tiff/optivibe-mcp/AGENTS.md

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…

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
  1. Very specific:

    Uncomputable merit: If a wide-field / fast merit can't be evaluated (a corner ray won't trace at full pupil), apply corner vignetting …

    line 47
  2. Very specific:

    Snapshot the start: Before optimizing, save_snapshot (or save_candidate) the starting form — there is no reliable in-session undo.

    line 53
  3. Very specific:

    Save keepers: After each accepted optimize, save_candidate the result.

    line 56
  4. Distinctive:

    Do not guess an operand code, a glass name, or a typed member.

    line 62

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.ok and the read-back, not an exception. A tool that couldn't do what you asked tells you so in its envelope (often with a typed error_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_merit or your own operands), then dry_run to confirm readiness without opening the optimizer.
  • The stop must be free. optimize / dry_run default-refuse a glass-vertex aperture stop — run normalize_stop first (or pass auto_normalize). A front-vertex glass stop is also handled by normalize_stop (it inserts a zero-thickness dummy air stop ahead of the front glass); do not hand-build a dummy stop.
  • Call optimize once; 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 (or save_candidate) the starting form — there is no reliable in-session undo. optimize also auto-captures a per-pass .zmx trail.
  • Save keepers. After each accepted optimize, save_candidate the result; once you have a keeper, promote_best it. 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_merit authors a positive air-gap floor by default (min_air). The glass floor (min_glass) is authored only when you pass glass=true, so pass it or run check_clearance after optimizing. For a gradient-index surface, grin_dn_max authors 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 twice grin_dn_max. The post-optimize index audit is the authority on what the profile actually is.
  • check_clearance audits center/edge thickness and clearances after optimization; a gradient-index element is audited as a solid, at the glass floor.
  • save_candidate / promote_best gate 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) takes n0 as the base index squared — pass n0=2.25 for a medium of physical index 1.5; on Gradient3, n0 is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.