MathCode: a terminal agent that checks Lean proofs as it writes them
MathCode: A Frontier Mathematical Coding Agent
At a glance
- What is it?
- MathCode wraps a shell-based setup around a terminal coding agent with built-in Lean support, so the agent can inspect goals, test candidate proofs and verify finished work. It is aimed at people doing formal mathematics on macOS arm64 or glibc Linux, and it assumes you already have the codex CLI and a lot of disk space.
- Who is it for?
- Adopt MathCode if you already work in Lean and want the agent loop to sit next to the proof checker rather than in a separate chat window, and if your machine is macOS arm64 or glibc Linux x86_64 with AVX2 and room for Mathlib caches. Skip it if you need Windows support, a backend other than codex, or a small dependency footprint.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap MathCode is trying to close
A general coding assistant can write Lean syntax. It cannot tell you whether the proof compiles, because it has no connection to the goal state. MathCode's stated purpose is to close that loop: the README says the agent can inspect goals, check candidates, search declarations, and verify a finished proof interactively. That is a different product from a chat window that emits Lean-looking text and leaves verification to you. The intended user is someone who already has Lean and Mathlib installed, or is willing to let setup.sh install them, and who wants the agent to iterate against a real checker. The repository's primary language is Shell, which is a fair signal about where the engineering effort sits: the distribution and toolchain plumbing, not a novel model. MathCode is a harness around existing pieces, and the README is candid about that by listing codex as the default backend and default math flow.
How the agent, the Lean workspace and the vault fit together
The architecture visible in the README has four moving parts. First, the CLI and a companion mathcode-webui binary, both shipped as prebuilt runtime assets and restored from a release archive when they are missing or fail verification. Second, a bundled ripgrep under vendor/ripgrep/ that MathCode uses for its internal search paths, so declaration search does not depend on a system rg. Third, the Lean side: a lean-workspace/lake-manifest.json pins the dependency graph, and setup materializes that locked graph without running lake update or rewriting the manifest. Fourth, extension points: tools/ and plugins/ directories, a bundled skills/ reference-doc directory, and project skills loaded from .mathcode/skills/<name>/SKILL.md. The data flow during a proof attempt is not spelled out in the README beyond the claim of interactive goal inspection and candidate checking, so the exact protocol between the agent and the Lean process is something you would have to read the source to confirm. What is clear is the boundary: setup materializes an empty managed VaultLibs/UserVaultLibs/ skeleton, and the README states that source-host local vault mirrors, test fixtures and scratch Lean files are not packaged. Your proofs and vault data live outside the release bundle, which is why --clean can remove install artifacts while keeping them.
Getting it running, and what setup.sh actually does on your machine
The documented path is four commands: git clone https://github.com/math-ai-org/mathcode.git, cd mathcode, bash setup.sh --with-lean, codex auth login, then mathcode. If you want a smaller install, bash setup.sh --without-lean skips Lean and Mathlib, and bash setup.sh --install-lean adds it later. Running bash setup.sh with no flag asks interactively and defaults to the full installation. On Linux, setup requires bwrap (package bubblewrap) and socat before it bootstraps the Lean workspace; that is a hard prerequisite, not a suggestion. If your shell has not reloaded its profile, ./run is the bundle-local fallback. Setup downloads the matching mathcode-vX.Y.Z-<os>-<arch>.tar.gz asset when bundled runtime files are missing, stale, unverified or invalid for the platform, verifies the current-platform SHA256SUMS.txt entry with shasum or sha256sum, and validates downloads before replacing a working install. It creates .env from .env.example, installs a user-local launcher in ~/.local/bin/ by default, and only overwrites launcher files it previously created. Two environment variables matter: MATHCODE_INSTALL_BIN_DIR redirects the launcher location, with relative paths resolved against the bundle root, and MATHCODE_SETUP_USE_SYSTEM_LEAN=1 makes setup capture your system lean and lake, record their absolute paths in .env, and preserve your existing ELAN_HOME. The README notes those managed values use base64: UTF-8 encoding so both Bun dotenv parsing and ./run shell sourcing preserve literal backslashes, quotes and backticks. That is an unusual amount of care for a path variable, and it tells you the authors have been bitten by shell quoting in the past.
Where the setup story gets thin
The maintenance commands are bash setup.sh --status, --clean, --install-lean and --help. --status checks that ./mathcode --version and its checksum match the release tag metadata, that ./mathcode-webui matches recorded metadata, that the bundled rg is executable and prints a version banner, and whether Lean support is ready, deferred, incomplete or not yet installed. That is a useful health check, but it is a release-integrity check, not a functional one. Nothing in the README claims --status verifies that a proof attempt actually succeeds end to end. The Lean bootstrapping is the riskiest step and the README is upfront about it: setup requires a local MathCodeLean readiness build after the optional Mathlib cache fetch, cache skips and download failures fall back to that build, and a build failure aborts setup. So a flaky Mathlib download turns into a full local build, and a broken build stops the install. The README also says setup repairs partial local elan tool-file installs before bootstrapping, which implies that failure mode is common enough to warrant code. There is no documented rollback beyond --clean, and no stated upper bound on disk use, only "enough disk space for the bundle, plus the Lean toolchain and Mathlib caches when Lean support is enabled." For a project whose value depends on a working Lean toolchain, the absence of a documented smoke test is the gap I would want closed first.
Platform and dependency constraints you cannot design around
MathCode supports macOS arm64 and glibc-based Linux on x86_64 with AVX2, built on Ubuntu 22.04. That is the whole list. Windows is not supported natively, though setup accepts lean.exe and lake.exe pairs from Git Bash or MSYS, which suggests people are trying. curl is required for setup and bootstrap downloads, and shasum or sha256sum is required for archive verification, so a minimal container without coreutils checksum tools will fail early. Python 3.12+ is optional and only needed for analysis tools under tools/. The default backend is the codex CLI, and the README frames it as needed "if you want the default backend and default math flow," which leaves open whether other backends are wired up. Nothing in the supplied material names an alternative backend or documents how to configure one, so treat codex as a requirement rather than a default you can swap. The AVX2 requirement on x86_64 rules out older server CPUs and some virtualized environments where the flag is masked, and that is a silent failure mode if you only read the macOS line.
How this differs from a general-purpose coding agent
The obvious comparison is a general terminal coding agent such as Aider or the codex CLI used on its own. Those tools edit files and run shell commands; you can point them at a Lean project and they will happily run lake build. The difference is what the agent can see. MathCode's README claims built-in Lean capabilities: inspecting goals, checking candidates, searching declarations, verifying a finished proof interactively. A general agent has to reconstruct the goal state from build output or from a file it writes and re-reads. Whether MathCode's integration is meaningfully better depends on how the goal-inspection channel is implemented, and the README does not describe it. The second difference is distribution. MathCode ships a checksum-verified release bundle with a pinned Lake manifest, a vendored ripgrep, and a setup script that manages the Lean toolchain for you. Aider and codex assume your environment is already correct. That is a real convenience if you want reproducibility across machines, and a real cost if you already have a working Lean setup you do not want touched. The MATHCODE_SETUP_USE_SYSTEM_LEAN=1 escape hatch exists precisely for that second group, and it is opt-in rather than the default.
Licence and the cost of staying current
MathCode is Apache-2.0. That permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes; it also includes an explicit patent grant. It does not grant trademark rights, and it is not a copyleft licence, so bundling MathCode into a proprietary internal tool does not force you to publish your own code. I am not a lawyer and this is not legal advice; check the LICENSE file in the checkout. On maintenance, the material shows a v0.3.0 release dated 2026-08-25 and a last push of 2026-09-09, so the project is active as of that window. Upgrades are not a simple git pull: setup.sh detects stale or unverified binaries by comparing against recorded release metadata, so moving to a new tag means re-running setup and letting it re-download and re-verify the runtime. The pinned lean-workspace/lake-manifest.json means a MathCode upgrade can move your Lean dependency graph, and the README states setup materializes that graph without running lake update. If you maintain proofs against a specific Mathlib revision, verify the manifest diff before you upgrade, because setup will not ask. The --clean flag preserves LeanFormalizations/ and vault data, so a clean-and-reinstall cycle is recoverable, but it also preserves the locked manifest, which means you cannot use --clean to reset the dependency graph.
Editorial conclusion
Adopt MathCode if you already work in Lean and want the agent loop to sit next to the proof checker rather than in a separate chat window, and if your machine is macOS arm64 or glibc Linux x86_64 with AVX2 and room for Mathlib caches. Skip it if you need Windows support, a backend other than codex, or a small dependency footprint. Before committing, run bash setup.sh --without-lean, then bash setup.sh --status, and confirm that ./mathcode --version matches the SHA256SUMS.txt entry for the release tag you cloned.
Community notes