Optimizer: exact optimisation for coding agents

A Claude Code plugin (and MCP server usable by any MCP-capable agent) that lets an agent solve optimisation problems with a real solver instead of guessing. Ask "plan the shifts for my five staff this week" or "how many chairs and tables should the workshop make" and the answer is computed by Google OR-Tools, proved optimal, and re-checked independently before the agent shows it.

Runs entirely on your machine. No API key, no LLM calls inside the plugin: the agent describes the problem, the solver decides, the verifier checks.

Why

Asked to optimise, coding agents tend to write a quick heuristic (a greedy loop, a random search) whose answer looks plausible but is not optimal, quietly drop a rule, or invent a plan when none exists. This plugin gives them:

The optimize skill tells the agent when to use which tool, to restate the rules before solving, and to report the solver's status honestly (OPTIMAL means proved best; FEASIBLE means valid but the time limit stopped the proof).

Related MCP server: CHUK MCP Solver

Example

From examples/small_shop.json: five staff, a week of morning and evening shifts, a busier Friday and Saturday evening, Sara off on Wednesday, Omar part-time.

• Status OPTIMAL in 0.03 s, verification passed.

• 23 shifts assigned, exactly what the needs add up to.

• Fairness gap of 2, the smallest possible: Omar is capped at 3, and the other 20 shifts split 5-5-5-5.

• All 4 preferences respected.

Make Friday impossible (Sara and Omar away, Karim unable to do evenings) and the tool answers with the four rules that clash, leaving out the irrelevant ones:

need: at least 3 on Fri evening
Karim unavailable Fri evening
Sara unavailable Fri evening
Omar unavailable Fri evening

How it works

• optimizer/model.py: the JSON model format (integer variables and coefficients, the form CP-SAT works on; decimals are scaled first).

• optimizer/solve.py: builds and solves the model with CP-SAT, then always runs the verifier on the answer.

• optimizer/verify.py: independent check, no solver involved.

• optimizer/explain.py: puts an on/off switch on every rule, asks the solver which switches make the problem impossible, then removes rules one by one while it stays impossible (deletion filter). The result is an irreducible infeasible subset: removing any single rule from it removes the conflict.

• optimizer/scheduling.py: turns a rota description into a model using four patterns (yes/no assignment, coverage, min-max fairness, weighted priorities).

• optimizer/server.py: the MCP server.

• scripts/launch.py: what the plugin starts. On first run it creates a private Python environment in the plugin's data folder and installs OR-Tools there (about a minute), then reuses it.

Testing

python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"   # bin/python on macOS and Linux
.venv/Scripts/python -m pytest

73 tests, including 60 random small problems where the solver's optimum is compared with brute-force enumeration of every possible assignment (infeasible cases included), and a check that every reported conflict is truly minimal.

Install

Requires Python 3.10 or newer, available as python.

claude --plugin-dir /path/to/optimization-plugin

Status and next steps

Version 0.1: the four tools, the optimize skill, tests. Next:

1. A benchmark measuring agents with and without the plugin on optimisation word problems with known answers (OptiBench and real cases), including a small local model.

2. More high-level tools: assignment, production planning, delivery routing, cutting stock.

3. Continuous variables (linear programming with HiGHS).