MathModelAgent: a SKILLS-driven agent for mathematical modeling papers

The problem MathModelAgent targets

A mathematical modeling contest gives you three days. Within that window a team has to read an open-ended problem, pick a model, write and debug the code, produce figures, and typeset a paper that follows a specific competition template. Most of the time goes to the plumbing: re-running a solver after a unit error, rebuilding a table, fighting LaTeX. MathModelAgent attacks that plumbing. Its README states the goal plainly: turn three days of competition time into one hour and generate a complete modeling paper. The audience is competition teams and, per the contributor section, developers who want to study how an agent is designed on top of a modern Harness. The repository describes the project as a demo in an experimental iteration phase, and the author notes he is busy and updates when he has time. The last push was on 2026-09-08, so the code is recent, but recency is not the same as stability.

Skills instead of a harness: how the pipeline is put together

The architectural decision that matters is what the project stopped doing. The README says the project has been distilled into something fully driven by SKILLS and no longer maintains a Harness layer. Each stage is an independent skill, so you can invoke only the analysis step or only the paper-writing step. The full run is one command, /1start-mathmodel, which chains problem analysis, modeling, coding, plotting, typesetting and acceptance without manual handoffs. Code execution runs either in a local Jupyter-backed interpreter, which saves work as notebooks you can reopen, or in a cloud interpreter through E2B or Daytona. Model access goes through litellm, and the README claims support for any provider litellm covers; it also describes setting a different model per agent, so the modeling agent and the writing agent need not share one endpoint. Output is Typst rather than LaTeX, with 17 templates for Chinese and international competitions (the README names 国赛, 华数杯, 华为杯 and MCM/ICM). The README also lists a nine-step acceptance pass covering text leakage detection, numerical consistency checks, Typst compilation and PDF visual inspection. Treat that list as a claim about intent, not a guarantee: nothing in the repository describes what happens when a check fails.

Installing the desktop build or the skills

The README recommends the desktop build first. It bundles Claude Code and the full skill set, so you do not install Python, Node.js or Redis, and you do not configure skills by hand. Download the matching file from the Releases page: mathmodel-<version>-arm64.dmg for Apple silicon, mathmodel-<version>-x64.dmg for Intel Macs, or mathmodel-<version>-x64.exe for 64-bit Windows. The macOS package is Developer ID signed and notarized by Apple. The Windows package is not signed, so SmartScreen may warn you on first run; the README tells you to choose More information, then Run anyway, and to download only from the official Releases page.

If you are a developer deploying it yourself, the README gives an install command for the skills:

npx skills add jihe520/MathModelAgent --all

That pulls the whole skill set into your Harness. The README then shows the run command for each supported Harness. For Claude Code:

claude --dangerously-skip-permissions

and inside the session you type the slash command with your task:

/1start-mathmodel 完成这个数学建模任务

For Codex the README gives codex --yolo and the $start-mathmodel command instead. Two auxiliary commands are listed: /doctor checks your environment configuration, and /typst-author returns Typst knowledge. Run /doctor before your first real task, because a missing interpreter or API key will otherwise surface midway through a run. The README does not state what /doctor prints on success.

Running the web stack with Docker

The repository also ships a web UI, and the README calls Docker the simplest and safest deployment. From the project folder, one command starts three services:

docker-compose up

The compose file defines redis on port 6379 with a named volume for persistence, backend on port 8000, and frontend on port 5173. The backend mounts ./backend/project/work_dir into the container so generated files survive a restart, and it loads variables from ./backend/.env.dev. The compose file notes that REDIS_URL in that env file must be redis://redis:6379/0, not localhost, because the backend reaches Redis by service name. Once the stack is up, the README points you to http://localhost:5173 for the UI and http://localhost:8000 for the API, and says to set your API key under the sidebar avatar menu. If you prefer a local install, the README requires Python, Node.js and Redis, uses uv sync in backend and pnpm i in frontend, and on Windows ships a win_start.bat you can double-click. The README also notes a CLI version on the master branch that is simpler to deploy but will not be updated.

Where MathModelAgent will let you down

Read the roadmap before you commit a competition to this. Several features advertised in the feature list are marked unimplemented in the same file. Human in the loop, described as pausing at key nodes with six decision actions, carries the note that the data model exists but workflow integration is incomplete. The RAG knowledge base is marked as configuration only, with the core retrieval logic not implemented. Web search is listed with a note that the originally planned Tavily API was not implemented and OpenAlex is used instead. Fallback hand-off with an evaluator shadow mode is marked as having neither configuration nor core logic, leaving only basic retry. The feedback loop is marked as core logic not implemented, with only a TODO comment in the agent base class. So the four-layer fault tolerance named in the feature list is, by the roadmap's own account, not all there. Two other constraints: the README says the project will only iterate on the SKILLS layer from now on, so anything outside it is effectively frozen, and it does not document rollback or what a partial failure leaves in the work directory. If you need a pipeline you can debug deterministically, this is the wrong tool today.

How it differs from a general coding agent or a multi-agent framework

The obvious alternative is to drive a general coding agent yourself: open Claude Code or Codex, paste the problem, and ask for a model and a paper. That works, and it is what MathModelAgent builds on, but you supply the structure. The project's contribution is the structure: a fixed stage order, a modeling knowledge base with a model selection decision tree covering AHP, TOPSIS, ARIMA and GA, competition scoring criteria, Typst templates matched to the competition, and a named acceptance pass. The other alternative is a self-contained multi-agent framework in the older style, where the framework owns the loop and the tooling. The README's author addresses this directly: two years ago he wrote his own agent framework, and he now argues that agent products are increasingly built on a Harness such as Codex, Claude Code or Pi plus skills. MathModelAgent is an instance of that argument, which is why it has no harness layer to maintain. It also splits scientific plotting and diagrams into a separate repository, jihe520/sci-box, installable with npx skills add jihe520/sci-box, so the figure templates are usable without the modeling pipeline.

Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-09-08, with v0.0.17 released the same day and v0.0.16 the day before. That is a fast release cadence, but the README's own caution about an experimental demo phase means you should expect behavior to shift between minor versions. Upgrading the skills is one command, npx skills add jihe520/MathModelAgent --all, and the desktop build checks for updates on launch; the README says macOS supports automatic updates while Windows waits on a code signing certificate. The Docker path rebuilds from source, and the compose file keeps a named volume for the backend virtualenv to speed up repeat builds when dependencies have not changed. On licensing, the repository lists no license. Without one, no rights are granted by default, so redistribution and reuse are legally unclear. The README does not address this, and it is worth resolving with the author before you ship anything built on the code. This is not legal advice; treat it as a question to answer before adoption.

Editorial conclusion

Adopt MathModelAgent if you are working under a competition deadline and already have a Harness such as Claude Code or Codex plus a model API key, because the desktop build bundles Claude Code and the full skill set with no Python, Node.js or Redis setup. Skip it if you need a stable, documented pipeline: the README marks the project as an experimental demo, several roadmap items are still unimplemented, and the repository carries no license file, so you have no granted right to redistribute or reuse the code. Before relying on it, run /doctor to confirm the environment, then check the generated Typst source and PDF yourself rather than trusting the nine-step acceptance pass.

Frequently asked questions

Official sources

1. Issues
2. jihe520/MathModelAgent on GitHub
3. Project website
4. README
5. Releases