MathCode: The Secret Weapon Turning Plain Math Into Bulletproof Proofs

MathCode: The Secret Weapon Turning Plain Math Into Bulletproof Proofs

What if I told you that the most tedious, error-prone part of mathematics is about to disappear? Not the creativity. Not the insight. But the soul-crushing translation of beautiful mathematical intuition into machine-verifiable formal proofs.

Every mathematician, researcher, and developer who has touched Lean 4 knows the pain. You've solved the problem in your head. The proof is elegant, obvious even. But then comes the formalization slog—hours wrestling with syntax, hunting through Mathlib, debugging cryptic compiler errors that tell you failed to synthesize instance when you just wanted to prove something simple about even numbers.

What if you could simply type your problem in plain English and watch a tireless AI agent transform it into a formally verified Lean 4 theorem?

That's not science fiction. That's MathCode—a frontier mathematical coding agent that's already doing exactly this. And the results are exposing how broken our old workflows really were.

What is MathCode?

MathCode is a terminal-based AI coding assistant with a built-in mathematical formalization engine. Born from the AUTOLEAN project and now developed under the math-ai-org organization, MathCode represents a fundamental shift in how humans interact with proof assistants.

Unlike traditional theorem provers that demand you speak their language from minute one, MathCode meets you where you are. Plain language in, formal proof out.

The project is architected as a lightweight bootstrap repository that downloads its matching binary from GitHub Releases. This design choice matters: you get rapid updates without rebuilding from source, while the setup.sh script handles the messy toolchain bootstrapping that usually kills enthusiasm for Lean projects.

Why is MathCode trending now? Three converging forces:

• The Mathlib explosion: Lean 4's mathematical library has reached critical mass, making serious mathematics actually formalizable
• LLM capability inflection: Modern language models can finally bridge the natural-to-formal gap with usable accuracy
• Verification demands: From cryptographic protocols to aerospace software, industries increasingly require machine-checked proofs

MathCode sits at this intersection, automating the translation bottleneck that has blocked formal methods adoption for decades.

Key Features That Change Everything

Persistent Lean REPL: Sub-Second Proof Checking

MathCode's most transformative feature might be its persistent Lean REPL. After a one-time ~90 second warmup to import Mathlib, compile checks drop from ~30 seconds to ~0.4 seconds.

Think about what this means practically. When you're iterating on a proof, feedback loops shrink from "go get coffee" to "think and respond." The REPL automatically imports your theorem library and axiom library, so your accumulated knowledge is always available.

Theorem Library: Never Prove the Same Thing Twice

MathCode automatically stores proved theorems for reuse. Every successful proof gets named, appended to TheoremLib/Stored.lean, and made importable. The prover and planner can invoke these instead of re-deriving foundations.

This isn't just convenience—it's how mathematics actually works. Mathematicians build on previous results. MathCode makes that accumulation automatic.

Axiom Library: Conversational Assumptions, Formalized

Store assumptions from natural language as persistent, consistency-checked declarations:

/axiomatize "A is faster than B"

The system formalizes, stores, compile-checks, and auto-injects these into future prompts. Physics problems, chemistry constraints, narrative logic—any domain becomes formalizable.

Lean LSP Integration: Smarter Lemma Discovery

When enabled, MathCode searches leansearch.net and Loogle for verified Mathlib lemmas before planning. It uses structured LSP diagnostics instead of raw stderr, extracts proof goals at error locations for targeted repairs, and injects search results into planner and prover prompts.

Obsidian Theorem Graph: Visualize Mathematical Knowledge

Generate an Obsidian vault visualizing theorem dependencies as a knowledge graph. Each lemma stub includes the full Lean definition queried from Mathlib via #print. This transforms abstract proof libraries into navigable, explorable knowledge structures.

Agent-Mode and Tree-of-Subgoals Proving

For complex theorems, MathCode offers two powerful strategies:

• Agent-mode: Interactive chat where the agent iteratively searches, writes, compiles, and repairs proofs (up to 10 attempts per session)
• Tree-of-subgoals: Decompose theorems into independent subgoals, prove in parallel, stitch results back together

Multi-Planner Parallelism

Run multiple planners simultaneously for diverse proof strategies. Each proposes different approaches; all discovered lemmas save to the vault. The prover selects the best path.

Real-World Use Cases Where MathCode Dominates

Use Case 1: Academic Research Formalization

You're a number theorist with a new result. The paper is written, but reviewers demand formal verification. Instead of hiring a Lean expert for months, you feed MathCode your theorem statements. It generates skeleton proofs, suggests relevant Mathlib lemmas, and iterates toward completion. What took six months now takes days.

Use Case 2: Cryptographic Protocol Verification

Blockchain and zero-knowledge projects increasingly require formal security proofs. MathCode's axiom library lets you formalize protocol assumptions ("the hash function is collision-resistant"), while the tree-of-subgoals prover decomposes complex security properties into verifiable subclaims.

Use Case 3: Educational Mathematics

Students learning proof techniques struggle with syntax before understanding concepts. MathCode lets them express ideas naturally, see the formalization, and study how their intuition maps to Lean. The Obsidian graph reveals how theorems connect—turning isolated exercises into connected mathematical knowledge.

Use Case 4: Industrial Safety-Critical Systems

Aerospace and automotive industries need verified algorithms. MathCode accelerates the formalization of control theory proofs, signal processing bounds, and probabilistic safety claims. The persistent REPL enables rapid regression checking as specifications evolve.

Use Case 5: Cross-Domain Modeling

Physics-informed machine learning, computational chemistry, narrative logic for game design—MathCode's axiomatization accepts any domain. Store "friction is negligible" or "character A knows character B's secret" as formal assumptions, then build proofs atop them.

Step-by-Step Installation & Setup Guide

MathCode's installation is deliberately streamlined. Here's the complete path from zero to proving:

Prerequisites

• macOS (arm64) or Linux (x86_64)
• Sufficient disk space for the bundle, Lean toolchain, and Mathlib caches (several GB)
• codex CLI for the default backend
• Python^{↗ Bright Coding Blog} 3.12+ (optional, only for analysis tools in tools/)

Quick Start Commands

# Clone the lightweight bootstrap repository
git clone https://github.com/math-ai-org/mathcode.git

# Enter the project directory
cd mathcode

# Run the setup script—this is where the magic happens
bash setup.sh

What setup.sh actually does under the hood:

# Downloads the matching mathcode-vX.Y.Z-<os>-<arch>.tar.gz from GitHub Releases
# Verifies SHA256SUMS.txt when shasum or sha256sum is available
# Creates .env from .env.example when needed
# Bootstraps Lean locally when lean/lake are missing
# Creates skills/, tools/, plugins/ extension directories

Authentication and Launch

# Authenticate with OpenAI's Codex backend
codex auth login

# Launch MathCode
./run

Optional Setup Commands

# Check binary and tooling health
bash setup.sh --status

# Clean install artifacts while preserving your proofs and vault data
bash setup.sh --clean

# View all setup flags
bash setup.sh --help

The --clean flag is particularly valuable—it preserves your accumulated work in LeanFormalizations/ and vault data while giving you a fresh start.

Environment Configuration

Create a .env file (auto-generated from .env.example by setup.sh) to enable advanced features:

# Enable persistent Lean REPL for ~0.4s compile checks
MATHCODE_LEAN_REPL=1

# Enable Lean LSP for smarter lemma discovery
MATHCODE_USE_LSP=1

# Enable agent-mode interactive proving
MATHCODE_AGENT_PROVE=1

# Enable tree-of-subgoals decomposition
MATHCODE_TREE_PROVE=1
MATHCODE_MAX_TREE_DEPTH=2

# Run multiple planners in parallel
MATHCODE_NUM_PLANNERS=3

Shell-exported variables override .env settings, useful for temporary experiments.

Alternative Backend: Anthropic

# Switch from OpenAI/Codex to Anthropic
MATHCODE_USE_OPENAI=0
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-5

# Also disable codex exec for math tools
AUTOLEAN_USE_CODEX=0

REAL Code Examples from the Repository

Let's examine actual usage patterns from MathCode's documentation, with detailed explanations of what each accomplishes.

Example 1: Basic Theorem Invocation

The simplest possible MathCode session—proving a fundamental number theory property:

./run -p "prove that the square of an even number is even"

This single command triggers the entire pipeline: natural language parsing, formalization into Lean 4 syntax, proof planning, and attempted verification. MathCode outputs progress to your terminal and writes the final formalization to LeanFormalizations/.

What's happening behind the scenes:

• The planner decomposes "square of an even number" into formal Lean: ∀ n : ℕ, Even n → Even (n^2)
• It searches Mathlib for Even definitions and relevant lemmas
• The prover attempts a constructive proof using Even as ∃ k, n = 2*k
• The REPL compiles and verifies, or returns errors for repair

Example 2: Piped Input for Programmatic Use

echo "hello" | ./run -p

This pattern enables Unix-style composability. Integrate MathCode into larger workflows: generate problems from scripts, pipe theorem statements from other tools, or batch-process formalization requests. The -p flag tells MathCode to treat piped input as a proof prompt.

Example 3: Enabling Theorem Storage for Cumulative Knowledge

/theorem-store on     # enable persistent storage (writes to .env)
/theorem-store sync   # backfill all proved-but-unstored theorems
/theorem-store status # show stored count and vault info

These interactive commands transform MathCode from a one-shot prover into a growing mathematical knowledge base. When enabled, every successful proof automatically:

1. Receives a generated name based on its content
2. Gets appended to TheoremLib/Stored.lean
3. Becomes importable via standard Lean import statements

The sync command is crucial for existing work—it retroactively processes your LeanFormalizations/ directory, ensuring nothing is lost.

Example 4: Axiom Management for Domain-Specific Reasoning

/axiomatize "A is faster than B"     # formalize and store assumption
/axiomatize list                     # display all active axioms
/axiomatize check                    # run consistency review
/axiomatize remove <name>            # eliminate a declaration

This is where MathCode transcends pure mathematics. The axiom system:

• Stores per-vault with full Lean formalization
• Compile-checks for immediate inconsistency detection
• Auto-injects into formalization and proving prompts
• Supports arbitrary domains through natural language parsing

The check command runs automated consistency review—catching contradictions before they poison your proof search space.

Example 5: Scheduled Agent Loops for Continuous Proving

/loop 10m check the deploy
/loop 1h /standup 1

MathCode includes recurring prompt scheduling out of the box. Short-lived loops handle reminders and monitoring. For persistent schedules across restarts, create durable schedules from interactive sessions.

This enables fascinating workflows: continuously attempt open conjectures with varying strategies, monitor proof progress, or coordinate multi-agent proving sessions.

Example 6: Obsidian Vault Generation

/obsidian on       # enable and generate from existing formalizations
/obsidian generate # force regeneration now

Once enabled, every formalization and proof auto-updates your Obsidian vault. Open it in Obsidian's Graph View to see theorem-to-lemma relationships as a navigable knowledge network. Each node contains the full Lean definition from Mathlib, making this a research tool, not just visualization.

Advanced Usage & Best Practices

Optimize Your REPL Warmup Strategy

The ~90 second Mathlib import is unavoidable—but schedulable. Start MathCode with MATHCODE_LEAN_REPL=1 before you need it, or keep a persistent terminal session alive. The sub-second checks afterward transform iterative proving from painful to fluid.

Compose Features for Maximum Power

The most effective MathCode configurations layer multiple features:

MATHCODE_LEAN_REPL=1        # Fast compilation
MATHCODE_USE_LSP=1          # Smart lemma discovery
MATHCODE_AGENT_PROVE=1      # Iterative repair
MATHCODE_TREE_PROVE=1       # Parallel subgoals
MATHCODE_NUM_PLANNERS=3     # Diverse strategies

With Obsidian enabled, the agent reads your vault for context—creating a self-improving proving environment.

Vault Hygiene for Long Projects

Regular /theorem-store sync and /obsidian generate ensure your accumulated knowledge stays accessible. For collaborative work, commit TheoremLib/ and LeanFormalizations/ to version control—MathCode's output is pure Lean, fully portable.

Extension Development

Drop .md files in skills/ for domain knowledge, Python scripts in tools/ for analysis, or full plugins in plugins/. The four included tools (axiom_checker, sorry_analyzer, proof_stats, lib_search) demonstrate the pattern.

Comparison with Alternatives

The verdict: Traditional proof assistants offer maximum control at maximum effort. Raw LLMs offer convenience without verification. MathCode occupies the critical middle ground—verified results with natural language accessibility.

FAQ: What Developers Ask About MathCode

Q: Do I need to know Lean 4 to use MathCode?

No—MathCode is designed for natural language input. However, reading the generated Lean helps you understand and verify the formalization. Over time, you'll absorb Lean syntax organically.

Q: How reliable are the automatically generated proofs?

All proofs compile through Lean's kernel—there's no trust gap. However, proof attempts may fail or require iteration. The agent-mode and tree-of-subgoals features specifically address this by enabling automatic repair and decomposition.

Q: Can I use MathCode without OpenAI/Codex?

Yes. Configure Anthropic models via .env, or set AUTOLEAN_USE_CODEX=0 to use alternative backends for math tools.

Q: What happens to my proofs if I update MathCode?

Your LeanFormalizations/ and vault data persist through setup.sh --clean. Theorem libraries are standard Lean files—future-proof and portable.

Q: Is MathCode suitable for production verification?

MathCode accelerates formalization, but final verification responsibility remains with practitioners. Use it to generate candidate proofs, then review and refine. The persistent REPL and LSP integration support rigorous validation.

Q: How does theorem storage handle naming conflicts?

MathCode auto-generates descriptive names. For manual control, edit TheoremLib/Stored.lean directly—it's standard Lean syntax.

Q: Can multiple users share a theorem library?

Yes. Commit TheoremLib/ to version control. Each user's MathCode instance can import shared theorems, enabling collaborative mathematical development.

Conclusion: The Future of Mathematical Formalization Is Here

MathCode represents something rare in developer tools: a genuine order-of-magnitude improvement in a workflow that has resisted automation for decades. The translation from mathematical intuition to machine-verifiable proof—historically a specialized, expensive bottleneck—is becoming as accessible as running a terminal command.

The implications extend far beyond individual productivity. As formal verification becomes economical for more projects, we'll see expanded adoption in security-critical software, verified compilation, provably correct hardware, and mechanized mathematics research.

Is MathCode perfect? No. Complex proofs still require human insight, and the agent's repair loops have limits. But it fundamentally changes the economics of formalization—shifting the question from "can we afford to verify this?" to "why wouldn't we?"

The repository is actively developed, with a growing community on Discord. The extension architecture (skills, tools, plugins) suggests ambitious roadmap plans.

My recommendation? Clone it today. Run bash setup.sh. Feed it a theorem you've been avoiding formalizing. Watch what happens.

The gap between thinking mathematics and proving mathematics is closing. MathCode is building that bridge.

👉 Get started now: github.com/math-ai-org/mathcode