GitHub - HarleyCoops/Math-To-Manim: Create Epic Math and Physics Animations & Study Notes From Text and Images. · GitHub

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

HarleyCoops

/

Math-To-Manim

Public

Notifications
You must be signed in to change notification settings

Fork
239

Star
2.1k

Code

Issues
0

Pull requests
0

Actions

Projects

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Projects

Security and quality

Insights

HarleyCoops/Math-To-Manim

 mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History324 Commits324 Commits.github/workflows.github/workflows  .hermes.hermes  docsdocs  environments/math_to_manimenvironments/math_to_manim  evalsevals  examplesexamples  hermes/skills/hermes-learns-manimhermes/skills/hermes-learns-manim  legacy/Math-To-Manimlegacy/Math-To-Manim  math_to_manimmath_to_manim  promptsprompts  scriptsscripts  tests/unittests/unit  toolstools  .gitignore.gitignore  AGENTS.mdAGENTS.md  Hero.jpgHero.jpg  README.mdREADME.md  disk-space-audit.ps1disk-space-audit.ps1  instructions.mdinstructions.md  pyproject.tomlpyproject.toml  requirements-system.txtrequirements-system.txt  zzzz.mdzzzz.md  View all filesRepository files navigationREADME

Math to Manim
Ask a question -> get a reasoned movie

Motion showcase · Architecture · Prime RL · Roadmap · Agent guide

Math-To-Manim turns serious math and physics prompts into Manim explainer videos and the reusable artifacts that produced them: intent, prerequisite graphs, lesson plans, math packets, storyboards, scene specs, generated code, validation reports, render evidence, review notes, and stage traces.
Browse the local GIF gallery →

Code-grounded workflow: every run stays inspectable from prompt to artifacts to render.

What this is
Math-To-Manim started on the morning of Donald Trump's second inauguration. Around 4:30 a.m. my time on January 20, 2025, DeepSeek, a Chinese AI lab, released R1 on Hugging Face. I read the timing as deliberate: a Sputnik-style signal that open reasoning models were now a geopolitical fact. My first move was to clone R1 and point it at math reasoning.
The interesting part was not just that a reasoning model could solve math; it was that the path to a good explanation could be made visible. A topic could become prerequisites, then a teaching order, then equations, then screen beats, then Manim code, then a movie.
M2M2 is the pipeline that grew out of that experiment. A teacher, tutor, parent, student, researcher, or agent can bring a short question, a lesson idea, or a dense technical note and get back an inspectable explanation: the concept, the missing prerequisites, the order of ideas, the screen beats, the generated Manim code, and optionally the rendered video.
The render can be a strong first pass at a four-to-five-minute explainer, with real mathematical and physical notation in LaTeX instead of decorative pseudo-math. The product is not only the MP4. Each run bundle preserves the reasoning artifacts and math that led to the scene, which makes the output useful for debugging, agent handoff, and reinforcement-learning work such as the Prime Intellect repair environment.
The next direction is recursive editing. Inspired by Recursive Language Models, the goal is to treat a finished movie and its run bundle as an environment an agent can inspect and revise. A request like, "rerender this, but tilt the camera so the equations are easier to read," should route back through the scene plan and Manim code, recompute the right change, validate it, render again, and leave a new trace that can train the next policy.
This repo is the build log for that loop: agents learning to reason through complex topics, preserve their work, and turn the reasoning into visual explanations.

Christian

Today, that means a durable agent pipeline with:

audience-aware request artifacts, from grade-school intuition to advanced notation;
a prerequisite-story pipeline inspired by the original reverse knowledge tree;
typed Pydantic artifacts between every stage;
OpenAI Agents SDK-compatible adapters for planning and generation;
optional Codex CLI-backed codegen for subscription-authenticated iteration;
a reproducible runs/<run_id>/ bundle for every generation;
static validation, render metadata, review artifacts, and manifests that are easy to inspect in CI or by another agent.

The design principle is simple: story before symbols, geometry before algebra, artifacts before side effects.

Reverse reasoning pipeline
A normal text-to-code demo jumps from request to Python. Math-To-Manim takes the long way on purpose: it reasons backward from the final concept to the prerequisites, then walks forward through a teachable visual sequence.
The code path is explicit in math_to_manim/pipeline/runner.py. AnimationPipeline.generate() runs a fixed stage chain: IntentAgent, PrerequisiteGraphAgent, CurriculumAgent, MathAgent, StoryboardAgent, SceneSpecAgent, ManimCodeAgent, StaticReviewAgent, RenderAgent, VideoReviewAgent, and PublisherAgent.

Stage
Why it exists
Artifact

Intent
Clarify what the learner is really asking.
intent.json

Reverse prerequisites
Build the knowledge graph needed before the target idea.
knowledge_graph.json

Curriculum
Turn the graph into a teachable order.
curriculum.json

Math packet
Select definitions, equations, assumptions, and examples.
math_packet.json

Storyboard
Decide the screen beats before code exists.
storyboard.json

Scene spec
Compile the visual plan into Manim objects, animations, timing, and camera notes.
scene_spec.json

Code, validation, render, review
Generate runnable Manim, gate it with static checks, render when allowed, and package the evidence.
generated_scene.py, reports, manifest

That gives every run a memory: JSON contracts, generated code, render results, review notes, and a manifest. The output is not just a video; it is an inspectable path from question to understanding to animation.
For current editable-video status and the planned prompt/spec/code edit loop, see the roadmap.

Prime Intellect RL repair loop
Math-To-Manim is also becoming a Prime Intellect reinforcement-learning environment. The first RL target is not "make the whole video in one shot." It is the repair move that matters most when generated animation code fails: take the typed scene plan, the broken generated_scene.py, and validation/render evidence, then return corrected Manim Python that is safe, sparse, and more likely to render.

Run bundle as environment
Reward function as critic
Policy update as repair engine

The current hub environment is harleycooper/math-to-manim. A repair task carries the original prompt, typed scene_spec, generated Manim Python, static-validation report, and render/recovery evidence when available. The model must return one strict GeneratedCode JSON block. The Verifiers reward checks whether the proposed code parses, defines the expected Manim scene, avoids unsafe imports and calls, preserves expected math terms, and reduces obvious text/layout crowding hazards.
generated_scene.py + scene_spec + validation/render evidence
-> Prime Intellect Verifiers environment
-> model proposes corrected GeneratedCode JSON
-> static reward checks parseability, scene shape, safety, terms, layout
-> hosted RL updates the repair policy
-> corrected, renderable Manim Python flows back into M2M2 recovery

That keeps the fast RL loop text-and-AST based while the slower Manim renderer remains the audit gate. The intended result is a model that learns the house style of this repo: cinematic but readable scenes, sparse formulas, staged captions, safe Manim code, and scripts that are much more likely to render on the first recovery attempt.
Current hosted-training status: the environment action passes on Prime, the hub package is published as harleycooper/math-to-manim@0.1.1, a 1-step smoke completed, and a 25-step W&B-enabled pilot has been launched on Qwen/Qwen3.5-35B-A3B.
See the full integration notes in docs/PRIME_INTELLECT_RL.md.

Clone and run
1. Clone
Windows PowerShell:
git clone https://github.com/HarleyCoops/Math-To-Manim.git
cd Math-To-Manim
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest
macOS / Linux / WSL:
git clone https://github.com/HarleyCoops/Math-To-Manim.git
cd Math-To-Manim
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest
2. Run a no-API smoke test
This proves the CLI, artifact contracts, and validators are wired before you spend model or render time:
math-to-manim generate "Explain why derivatives are slopes" --deterministic --no-render
Equivalent module form:
python -m math_to_manim.cli generate "Explain why derivatives are slopes" --deterministic --no-render
3. Generate with model calls
Set an OpenAI key and choose a model if desired:
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4.1"
math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render
PowerShell:
$env:OPENAI_API_KEY = "sk-..."
$env:OPENAI_MODEL = "gpt-4.1"
math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render
4. Install render extras when you want MP4 output
Python render dependency:
python -m pip install -e ".[dev,render]"
System render dependencies are also needed for real Manim output, especially FFmpeg and LaTeX for MathTex. On Debian/Ubuntu/WSL:
./scripts/bootstrap-render.sh
The package list lives in requirements-system.txt.

Codex CLI codegen path
Math-To-Manim can keep the typed planning pipeline while sending the Manim codegen and repair loop through a locally authenticated Codex CLI session.
Check Codex first:
codex --version
codex exec "Say ready from inside this repo"
Then route codegen through Codex:
math-to-manim generate "Explain derivatives as slopes with a cinematic tangent-line reveal" \
--codegen-provider codex-cli \
--codex-full-auto \
--style cinematic \
--quality l
Earlier planning stages remain on the typed adapters; only the generated-code and repair stages move first. That makes the migration incremental instead of all-or-nothing.

What lands on disk
A generation writes a self-contained run bundle:
runs/<run_id>/
request.json
intent.json
knowledge_graph.json
curriculum.json
math_packet.json
storyboard.json
scene_spec.json
generated_code.json
generated_scene.py
validation_report.json
render_result.json
review_report.json
trace.jsonl # stage-boundary events when tracing is enabled
recovery_manifest.json # after recover-render
draft_review/
draft_review.md
contact_sheet.png
frames/
animation_package.json
manifest.json

After editing generated_scene.py inside a run bundle, rerun the recovery path:
math-to-manim recover-render runs/<run_id> --quality l
That command refreshes validation, render, review, draft-review assets, and
recovery_manifest.json without regenerating upstream planning artifacts.
Package layout:
math_to_manim/
agents/ # stage adapters
schemas/ # versioned artifact contracts
tools/ # graph, validation, rendering, video, artifact helpers
pipeline/ # orchestration, tracing, repair loop
rendering/ # Manim and FFmpeg wrappers
review/ # static and visual review scoring

Hermes Agent
Hermes is the contributor/operator agent around this repository. It is not imported by Math-To-Manim and is not a runtime dependency; it uses the repo the way a developer would: read files, search code, patch docs and code, run terminal checks, inspect generated artifacts, review frames or GIFs, track todos, delegate larger work, and preserve stable context through skills.
That makes Hermes useful for maintaining the reverse-reasoning pipeline without becoming part of it. A Hermes session can inspect AGENTS.md, pyproject.toml, schemas, tests, and runs/<run_id>/ bundles; run pytest, CLI smoke commands, Manim, FFmpeg, and git checks; then verify that docs, code, and showcase media still match the artifact contracts.
Repo-local Hermes skills live under hermes/skills/. The old Claude ./skill path is historical; current contributor guidance is in AGENTS.md, with launch notes in docs/HERMES_LEARNS_MANIM.md.

Motion showcase
Sixteen curated GIFs are tracked under docs/showcase/assets/ as the art direction target for Math-To-Manim's visual explanations.

Geometry as spectacle
Topology as choreography
Chaos as intuition

See the full gallery with descriptions: docs/showcase/README.md.
Make a README-sized GIF from a render
MP4="media/videos/your_scene/480p15/YourScene.mp4"

ffmpeg -y -ss 95 -t 24 -i "$MP4" \
-vf "fps=12,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" \
docs/showcase/assets/your-clip.gif
Adjust -ss and -t to capture the teaching beat you want.

License
MIT.

About

Create Epic Math and Physics Animations & Study Notes From Text and Images.

Resources

Readme

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

2.1k
stars
Watchers

16
watching
Forks

239
forks

Report repository

Releases
1

v1.0.0 - Math-To-Manim Claude Code Plugin

Latest

Jan 24, 2026

Packages
0

Uh oh!

There was an error while loading. Please reload this page.

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python
98.6%

Other
1.4%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

Math-To-Manim is a system designed to transform complex mathematics and physics prompts, derived from text and images, into detailed explainer videos and associated reusable artifacts. The core methodology involves establishing a code-grounded workflow where the reasoning process is made visible, allowing the relationship between the initial request and the final visual output to be fully inspectable. The system operates by reasoning backward from the final concept to determine necessary prerequisites, structuring a logical teaching sequence, selecting relevant mathematical content, planning visual scene beats, generating Manim code, and finally rendering the animation.

The overall process is executed through a multi-stage pipeline involving several specialized agents. This pipeline begins by clarifying the user's intent, establishing the required knowledge graph of prerequisites, defining the teaching curriculum, selecting the necessary mathematical packets (definitions, equations, examples), determining the storyboard (screen beats), compiling scene specifications into Manim objects, and generating the actual code, followed by static review, rendering, and final review. This structured approach ensures that every generation results in a self-contained run bundle, which preserves all reasoning artifacts, including JSON contracts, generated code, validation reports, and render evidence, providing a traceable path from the initial question to the final animation.

A key evolution of the system is the introduction of recursive editing, inspired by Recursive Language Models. This advanced capability treats the generated video and its run bundle as an environment that an intelligent agent can inspect and revise. For example, an agent can propose edits, such as adjusting camera angles to improve equation readability, which routes the request back through the scene plan and Manim code for recomputation, validation, and re-rendering.

Furthermore, Math-To-Manim is integrated as a reinforcement learning environment known as the Prime Intellect repair loop. In this context, the system is used to train agents to correct flawed outcomes; when generated animation code fails to render, the agent attempts a repair by taking the scene plan, the faulty code, and validation evidence to propose corrected Manim Python. Verifiers assess this proposed code for parseability, adherence to mathematical terms, safety, and visual layout, feeding the results back to update the policy and facilitate recovery. This loop ensures that the resulting agents learn the desired style: cinematic yet readable scenes, sparse formulas, and safe, renderable code.

The system is supported by an operator agent named Hermes, which functions as a developer interface around the repository. Hermes can inspect the code, documentation, and generated artifacts within every run bundle to verify that all components adhere to the defined artifact contracts. This capability allows Hermes to maintain the integrity of the reverse-reasoning pipeline without being a runtime dependency of the generation process. The structure of the repository supports this modularity, separating agents, schemas, tools, and the core pipeline orchestration, ensuring transparency and control over the complex generation and refinement process.