Mografy

English | 繁體中文

Mografy is a local Canvas animation tool for Claude Code and Codex. One shared mografy Skill helps the agent plan storyboards, adapt working examples, write scenes, review frames, and export the result. The browser player provides playback, scrubbing, subtitles, colors, effects, and audio controls.

Describe the animation in your agent, then watch it in mografy dev. The agent edits scene files; Mografy compiles and trial-renders them in Chromium before updating the player at the same time position.

Watch the intro with audio (MP4).

Latest updates

2026-10-27 — Mografy Templates: 43 free, ready-made templates for product videos, 22 native 9:16 in an editorial look and 21 16:9 in the montage look. mografy add <template...> projects/<name> starts a project from them.

2026-10-21 — Contextual music: the agent describes what each part of the film needs and an optional generator composes a score that lands on its moments; 3D layers with Three.js; a project style file (style.md) that fixes a project's design and motion decisions; and the shared Skill now keeps itself up to date after every install, build or update.

2026-10-20 — Edits no longer get stuck behind a stalled scene or a long review; the mografy command keeps working when the folder it was installed from is moved or deleted. See the changelog.

Get started

You need Node.js 22.12 or later. Then run:

git clone https://github.com/zz41354899/mografy.git
cd mografy
npm install -g pnpm
pnpm install
mografy dev

pnpm install installs dependencies and then, automatically, builds Mografy, downloads the Chromium it uses for checks and exports, and puts the mografy command on your PATH. It ends by suggesting a few mografy add commands: templates to start a film from, a reference film to copy and helpers for a project. mografy dev opens the player with the sixteen built-in animations. If you see them, the installation works.

To check for updates, run mografy update --check. To install the latest commit from your branch's tracked upstream, run mografy update from the Mografy folder. The command checks for local changes, waits for an active export to finish, stops the active player, fast-forwards the source, runs pnpm install (including build, Chromium setup and launcher refresh), synchronizes the shared Skill, then restarts the same project on the same port. Refresh the browser after it restarts. Without an active player, it updates the installation without opening a project.

If your installation predates the update command, stop the player with Ctrl+C and run this once in the original Mografy checkout:

git pull --ff-only
pnpm install
mografy dev

--check fetches Git metadata but does not change working files, install dependencies or restart the player. Updates stop for local changes (including untracked files), missing upstreams, detached HEADs or diverged history. User projects ignored by Git stay in place. If dependency setup fails after the source update, the player stays stopped and the error lists recovery commands. Separate checkouts update independently; outside a checkout, the PATH launcher selects its installed copy.

npm install -g pnpm installs the pnpm package manager; skip it if you already have pnpm. pnpm switches to the version Mografy pins in package.json by itself. If npm reports a permission error, run sudo npm install -g pnpm. Contributors changing Mografy itself also need pnpm check and pnpm test:browser; see Development and architecture.

More setup options

Open the bundled intro, or a project you already have:

mografy dev ./examples/mografy-intro
mografy dev ./projects/my-animation

New animations are created in the projects/ folder. To keep them somewhere else, set MOGRAFY_HOME before starting the player:

export MOGRAFY_HOME="$HOME/Animations"

Other settings, such as the default project and the FFmpeg path, are in configuration.

Create your first animation

1. Run mografy dev to open the player. No starter project is needed; after pnpm install it opens with the built-in animations.
2. Open the repository in Codex or Claude Code and describe the animation, naming the project folder. The agent creates the project and the player switches to it. The shared Skill guides scene authoring and review.
3. Watch the player update after each successful compile and Chromium trial render. Scrub to check timing and adjust the exposed scene controls.
4. Run mografy check ./projects/my-animation and mografy review ./projects/my-animation, then inspect the generated images. Export from the player or CLI when ready.

For example:

Create an eight-second 9:16 animation in projects/my-animation, with a native 1080 × 1920 canvas. Use the Typewriter and Logo reveal components as references. Show “Hello, Mografy.”, then reveal the logo with a teal accent. Review the actual frames and export an MP4.

For a longer sequence, ask for a storyboard first. Scene code determines the composition; the player exposes the parameters declared by that scene.

One Skill for Codex and Claude

Based on the maintainer's current experience, the Claude workflow is more fully calibrated. Codex can adapt its approach to the brief and rendered results while following the shared scene contract.

The Skill lives at .agents/skills/mografy/SKILL.md, outside animation subprojects. Claude's .claude/skills/mografy entry links to that same folder, and CLAUDE.md imports it. Both hosts read one maintained copy.

Its English references cover:

packages/core/skill/ holds the entrypoint and references as Markdown, and packages/core/src/guide.ts assembles them. After editing them, run pnpm build: it ends with pnpm sync:skills, which regenerates the Skill. pnpm install and mografy update build too, and mografy dev regenerates the Skill on start when its sources changed since the last sync (for example after a git pull). Animation projects receive AGENTS.md and CLAUDE.md pointers to the shared Skill.

Reference films

Mografy ships finished films as references for quality: mografy-montage (60 s promo in one continuous camera)