Stop Writing Proofs by Hand: RepoProver Automates Math Formalization

Stop Writing Proofs by Hand: RepoProver Automates Math Formalization

What if I told you that months of grueling, error-prone manual work—translating dense mathematical textbooks into machine-verified code—could collapse into days of fully automated orchestration? That entire graduate-level textbooks, the kind that take human mathematicians years to formalize, are now being consumed and verified by collaborative AI agents while you sleep?

This isn't science fiction. This is RepoProver, and it's about to fundamentally reshape how we think about mathematical knowledge in the digital age.

For decades, formalizing mathematics—translating pen-and-paper proofs into languages like Lean, Coq, or Isabelle—has been a brutal bottleneck. It's meticulous, slow, and demands rare expertise at the intersection of advanced mathematics and proof engineering. Projects like the Liquid Tensor Experiment took a team of experts months. Kevin Buzzard's Xena Project has spent years building libraries. The gap between what mathematicians know and what machines can verify yawns wider every day.

Meta's FAIR team just dropped a hydrogen bomb into that gap. RepoProver is a multi-agent scaffold that orchestrates large language models to collaboratively formalize entire mathematics textbooks in Lean—automatically, at scale, with quality enforcement built in. It already consumed a 300+ page graduate textbook on algebraic combinatorics and produced a working, building formalization. The implications? Explosive. For AI researchers, proof engineers, and mathematicians desperate to escape the manual formalization grind, this tool demands immediate attention.

Ready to see how it works—and why you should be using it yesterday?

What is RepoProver?

RepoProver is the research codebase for "Automatic Textbook Formalization" (Gloeckle, Rammal, Arnal, Munos, Cabannes, Synnaeve, Hayat, 2026), developed by Meta's Fundamental AI Research (FAIR) team. It represents a paradigm shift from single-model proof generation to multi-agent collaborative formalization—treating a mathematics textbook like a software project that multiple AI agents develop together.

At its core, RepoProver operates on a simple but radical insight: formalizing a textbook is structurally similar to developing a large codebase. You need architects (sketchers), implementers (provers), and quality gatekeepers (reviewers). You need project management (issue tracking), version control (git), and continuous integration (build verification). Why not apply the hard-won lessons of software engineering to mathematical formalization?

The system made waves by producing a complete automatic formalization of Darij Grinberg's graduate textbook "Algebraic Combinatorics"—a 300+ page tome covering symmetric functions, Young tableaux, and representation theory. This isn't a toy demo. This is serious mathematics, and RepoProver chewed through it with minimal human intervention.

Why is this trending now? Three converging forces: (1) LLMs have reached sufficient capability to generate plausible formal code, (2) Lean 4 and Mathlib have matured into a viable foundation for large-scale mathematics, and (3) the multi-agent paradigm—pioneered in software engineering contexts—proves surprisingly transferable to proof construction. The result is a system that doesn't just generate proofs; it manages the entire formalization lifecycle.

Key Features That Make RepoProver Insane

Multi-Agent Role Specialization

RepoProver doesn't throw a single LLM at the problem and hope. It deploys specialized agent roles with distinct responsibilities:

• Sketcher agents parse LaTeX definitions and theorem statements, translating mathematical concepts into Lean declarations. They're the architects, establishing the API surface of the formalization.
• Prover agents fill in the actual proof bodies, working within the framework sketched by their counterparts. They're the implementers, grinding through tactic sequences.
• Reviewer agents enforce quality via pull request reviews, catching logical errors, style violations, and build failures before they hit main.
• Maintainer agents manage the merge queue, ensuring the main branch always builds—a continuous integration principle applied to mathematical truth.

Filesystem-Based Issue Tracker

Forget Jira. RepoProver uses a lightweight issues/ directory of YAML files for coordination. Agents create issues to flag blockers, request refactorings, or coordinate cross-chapter dependencies. It's brutally simple, git-native, and requires zero external infrastructure.

Git-Native Workflow with Merge Queue

Every agent works on branches. Every contribution goes through PR review. The merge queue guarantees that main always compiles—if a proof breaks, it doesn't get in. This is continuous integration for mathematics, and it's non-negotiable for scale.

Distributed Execution via SLURM

The stool launcher enables multi-node distributed runs. Snapshot the code, symlink the Lean project (avoiding slow copies of .lake/ and .git/), and submit to your compute cluster. Rank 0 coordinates; all ranks pull tasks. This isn't a prototype—it's engineered for institutional-scale compute.

Observable Agent Trajectories

The built-in trajectory viewer (repoprover.viewer) lets you inspect exactly what each agent did, when, and why. Debug, audit, or simply marvel at the emergent collaboration patterns.

Token-Efficient Orchestration

Analysis scripts break down token usage by agent type and outcome. You can optimize where your compute dollars go—are sketchers burning tokens on impossible theorems? Are provers stuck in tactic loops? The data is there.

Use Cases: Where RepoProver Absolutely Dominates

1. Graduate Textbook Formalization

The flagship use case: take a published mathematics textbook and produce a complete, building Lean formalization. RepoProver already proved this works with Algebraic Combinatorics. Universities could formalize their entire graduate curricula, creating verified digital libraries that students interact with directly.

2. Mathlib Gap-Filling

Mathlib, Lean's mathematical library, has coverage gaps. RepoProver can target specific chapters from reference texts, generating contributions that human maintainers review and merge. It's a force multiplier for library growth.

3. Formal Methods in Industry

Companies verifying cryptographic protocols, distributed systems, or hardware designs often need to formalize mathematical foundations (algebra, number theory, combinatorics). RepoProver automates the tedious translation of specification documents into proof assistant code.

4. AI Safety & Alignment Research

Formal verification of AI systems requires precise mathematical specifications. RepoProver could accelerate the formalization of theoretical frameworks—game theory, probability bounds, optimization guarantees—that underpin safety arguments.

5. Educational Content Generation

Imagine interactive textbooks where every theorem is not just stated but executable. RepoProver generates the backend; educators build the frontend. Students can explore proofs, modify hypotheses, and watch the verification machinery respond.

Step-by-Step Installation & Setup Guide

Prerequisites

• Python^{↗ Bright Coding Blog} 3.10+
• Lean 4 toolchain (elan installed)
• Git (with main as default branch)
• SLURM (optional, for distributed runs)

Install RepoProver

# Clone the repository
git clone https://github.com/facebookresearch/repoprover.git
cd repoprover

# Install in editable mode
pip install -e .

Prepare Your Lean Project

RepoProver operates on a Lean project with a specific structure. Here's the complete setup:

Step 1: Initialize a Mathlib project

# Create and build a new Lean project with Mathlib
lake init MyProject math
lake update
lake build

Step 2: Add LaTeX source files

Organize your textbook source under tex/, split by chapter for parallel agent assignment:

MyProject/
├── lakefile.lean
├── lean-toolchain
├── lake-manifest.json
├── MyProject.lean              # Root import file
├── MyProject/
│   └── tex/                    # LaTeX source chapters (READ-ONLY)
│       ├── all.tex             # Full textbook source (optional reference)
│       ├── Topic1/
│       │   ├── Chapter1.tex
│       │   └── Chapter2.tex
│       └── Topic2/
│           └── ...
├── manifest.json               # Chapter manifest (see below)
├── CONTENTS.md                 # Structure documentation (see below)
└── issues/                     # File-system issue tracker (empty initially)

Critical: tex/ files are read-only. Agents consume them but never modify source material—preserving the canonical mathematical text.

Step 3: Create CONTENTS.md

Document your project structure, proof status, and architecture notes. The coordinator generates an initial version; agents update it as the codebase evolves. This becomes your living project dashboard.

Step 4: Create manifest.json

List chapters to formalize with target theorems/definitions:

{
  "chapters": [
    {
      "id": "ch1",
      "title": "Symmetric Functions",
      "source_path": "MyProject/tex/Topic1/Chapter1.tex",
      "target_theorems": ["thm:schur-positivity", "def:monomial-basis"]
    }
  ]
}

See configs/example_manifest.json for the full algebraic combinatorics configuration.

Step 5: Initialize git and issue tracker

git init -b main
mkdir issues  # Empty directory for agent-created YAML issue files

REAL Code Examples from the Repository

Let's examine actual usage patterns from RepoProver's documentation, with detailed explanations of what's happening under the hood.

Example 1: Running the Coordinator

# Launch the main formalization orchestrator
python -m repoprover run /path/to/lean/project --pool-size 10

What's happening here? This single command launches the entire multi-agent ecosystem. The run module instantiates the coordinator loop, which spawns:

• A pool of 10 Lean REPL instances (--pool-size 10) for parallel proof checking
• Sketcher agents that pull chapters from the manifest and generate Lean declarations
• Prover agents that receive sketched theorems and attempt tactic-based proofs
• Reviewer agents that validate PRs against style and correctness criteria
• Maintainer agents that manage the merge queue and enforce main branch integrity

The project state persists in .repoprover/ inside your Lean project—checkpoints, agent trajectories, and metadata all live here. Use --clean to obliterate this state and restart fresh, or --verbose to watch the agent deliberations in real-time.

Example 2: Distributed Multi-Node Execution with SLURM

# Launch distributed run across SLURM cluster
python -m repoprover.stool \
  --name myrun \
  --project /path/to/lean/project \
  --nodes 4 \
  --pool-size 16 \
  --agents-per-target 2

Deep dive: The stool (SLURM tool) launcher is where RepoProver's engineering sophistication shines. Here's the sequence:

1. Snapshot: Copies RepoProver code to a dump directory (configurable, reusable with --dirs-exists-ok)
2. Symlink: Links the Lean project without copying .lake/ (gigabytes of compiled Mathlib) or .git/—avoiding hours of transfer time
3. Submit: Creates a SLURM job with 4 nodes
4. Coordinate: Rank 0 runs the coordinator in a background thread
5. Worker pool: All 4 nodes (including rank 0) run workers pulling tasks from the coordinator
6. Parallelism: 16 REPL instances per node × 4 nodes = 64 concurrent proof attempts, with 2 agents potentially attacking the same theorem from different angles (--agents-per-target 2)

The --prs-to-issues flag is crucial for resuming interrupted runs: pending PRs become trackable issues, preventing lost work.

Example 3: Smoke Testing with the Toy Project

# Setup: copy toy project, initialize git, fetch and build Mathlib
bash examples/toy_project/setup.sh /tmp/repoprover-toy-test

# Activate environment and run with minimal resources
source .venv/bin/activate
python -m repoprover run /tmp/repoprover-toy-test --pool-size 2 --verbose

Why this matters: Before burning compute on your 300-page textbook, verify the pipeline works. The toy project contains one chapter with 4 trivial targets—a definition and 3 theorems about doubling natural numbers. It's designed to complete in minutes, letting you validate:

• Environment setup correctness
• Git integration functionality
• Agent communication protocols
• Merge queue behavior
• Your SLURM configuration (if applicable)

The --verbose flag here is your friend: you'll see exactly how sketchers translate "the double of n is n + n" into Lean's def double (n : ℕ) : ℕ := n + n, how provers attack theorem double_eq_add_self, and how reviewers verify the PR.

Example 4: Post-Run Analysis

# Analyze token consumption patterns
python scripts/count_tokens.py /path/to/lean/project

# Generate efficiency visualization
python scripts/plot_agent_efficiency.py /path/to/lean/project --out ./plots

Operational intelligence: These scripts transform raw logs into actionable insights. count_tokens.py breaks down consumption by agent type (sketcher vs. prover vs. reviewer) and outcome (success, failure, timeout)—revealing whether you're burning budget on impossible theorems. plot_agent_efficiency.py shows learning curves: do agents get better over time, or are they stuck in local optima?

Example 5: Trajectory Inspection

# Launch web viewer for agent behavior analysis
python -m repoprover.viewer --dir /path/to/lean/project/runs --port 8080

Debugging emergent behavior: When agents collaborate, unexpected patterns emerge. The viewer exposes the full decision tree—what each agent saw, what it tried, why it failed, and how it adapted. Essential for understanding (and publishing about) multi-agent dynamics in formal reasoning.

Advanced Usage & Best Practices

Manifest Design Determines Success

Your manifest.json is the project blueprint. Invest heavily in target_theorems granularity—too coarse and agents drown; too fine and coordination overhead dominates. The algebraic combinatorics example shows intermediate granularity: chapter-level grouping with individual theorem targets.

Git Hygiene is Non-Negotiable

RepoProver assumes clean git history. Pre-commit hooks, branch protection rules, and clear main branch policies aren't optional—they're how the merge queue functions. Treat this like production software engineering.

Token Budget Allocation

Use count_tokens.py outputs to dynamically adjust --pool-size and --agents-per-target. Early in a project, sketchers dominate token consumption; later, provers do. Rebalance as your codebase matures.

Issue Tracker as Control Plane

Don't ignore the issues/ directory. Human overseers can inject guidance via manually created YAML issues—"Refactor using Finset instead of Set" or "Priority: complete Chapter 3 before Chapter 5 dependencies." The agents read these and adapt.

Resume with Confidence

Long formalization runs fail—nodes die, SLURM preempts, bugs manifest. The --prs-to-issues resume pattern, plus .repoprover/ state persistence, means you lose minutes, not days. Design your runs with interruption in mind.

Comparison with Alternatives

Why RepoProver wins: It's the only solution that combines autonomous operation at textbook scale with software-engineering-grade quality assurance. Manual formalization doesn't scale. Single-LLM tools lack coordination and review. Traditional automation handles local proof search, not global project architecture.

FAQ

Q: What Lean version does RepoProver require? A: Lean 4 with Mathlib, initialized via lake init MyProject math. The lean-toolchain file in your project pins the exact version.

Q: Can I use RepoProver with Coq or Isabelle? A: Not directly. The architecture is Lean-specific, particularly the REPL pool and Mathlib integration. Porting would require substantial adapter work.

Q: How much does a full textbook formalization cost in API tokens? A: The algebraic combinatorics case study consumed significant compute, but exact figures aren't published. Use count_tokens.py to project costs from your toy project runs.

Q: What if agents generate incorrect proofs? A: Reviewer agents and the merge queue provide defense in depth. However, formal correctness is guaranteed only by Lean's kernel—all agent output is ultimately machine-checked. The risk is wasted compute, not accepted falsehoods.

Q: Can humans intervene during a run? A: Yes, via the issues/ directory and direct git operations. The system is designed for oversight, not fully unsupervised deployment.

Q: Is the algebraic combinatorics formalization complete? A: It's a substantial automatic formalization, but coverage varies. Check the blueprint website and GitHub repository for current status.

Q: How does this relate to AlphaProof or other AI math systems? A: AlphaProof targets competition mathematics (IMO-style problems). RepoProver targets systematic formalization of existing mathematical knowledge—different problem, different scale, different solution architecture.

Conclusion

RepoProver isn't just a tool. It's a declaration of intent—that the formalization bottleneck, the decades-long drag on machine-verified mathematics, is solvable through intelligent system design. By applying software engineering discipline to AI agent orchestration, Meta's team has built something that genuinely scales.

The algebraic combinatorics formalization proves it works on hard, real mathematics. The distributed SLURM execution proves it works at institutional scale. The git-native, review-enforced workflow proves it's engineered for reliability, not just demos.

If you're in formal methods, mathematical AI, or simply exhausted by manual proof translation, you need to try this now. Start with the toy project. Read the paper. Inspect the algebraic combinatorics output. And then ask yourself: what textbook in your domain could you formalize next?

The future of mathematical knowledge is machine-verified, searchable, and composable. RepoProver is the pipeline that gets us there. Don't watch from the sidelines.

→ Explore RepoProver on GitHub

→ Read the Automatic Textbook Formalization Paper

→ Browse the Algebraic Combinatorics Formalization