Theme

Your manager repo

Your email operation as files in a git repo you own — pulled from your Mimeo, edited by you or your agent, pushed back through a diff, a validation and a rehearsal.

What it is

The manager repo holds everything you author: flows, segments, guards, sequences, emails, templates, custom field definitions, products and settings, each as a plain file you can read, diff and review. Your Mimeo stays the runtime source of truth — people, events, runs, sends, opens, clicks and money never appear in the repo.

It's also your agent's home base. The repo ships with the mimeo CLI, a committed .mcp.json that wires any agent opening the repo to your Mimeo's MCP server, a CLAUDE.md with the operating rules, and skills for the recurring work.

Getting yours

Open Settings → Agents & API → Manager repo on your Mimeo (the setup wizard offers the same screen when sending setup finishes). It mints an API token and hands you the exact commands to paste — either into your terminal, or into your coding agent, which will do the whole thing for you. They look like this: 

git clone https://github.com/buildermethods/mimeo-manager.git my-mimeo
cd my-mimeo
git remote remove origin
./bin/mimeo init --host https://your-mimeo.com --token mm_your_token

The git remote remove matters: a fresh clone still points at the template repo, and nothing of yours should ever push back to it. init then does three things: points the repo at your Mimeo (host committed in .mimeo/config.yml, token gitignored in .mimeo/token), pulls every definition into files, and rewrites .mcp.json so your agent's MCP connection works. Then it prints your next two moves: 

git add . && git commit -m "First snapshot"
export MIMEO_TOKEN="$(cat .mimeo/token)"

The commit starts your history with what your Mimeo has today. The export is how the MCP server authenticates — the committed .mcp.json deliberately carries ${MIMEO_TOKEN} instead of a real credential.

The CLI itself needs nothing installed: it's one file at bin/mimeo, running on git and the Ruby that ships with macOS and every mainstream Linux. And the remote is yours — point origin at your own private repo so the history lives somewhere safe. No remote is required; your Mimeo never reads your git either way.

The loop

./bin/mimeo pull      # sync down first, always
                      # ... edit files, or ask your agent to ...
./bin/mimeo diff      # what a push would change — nothing is applied
./bin/mimeo push      # diff → validate → rehearse → apply
./bin/mimeo pull      # after a structural push: pick up ids Mimeo minted

Pull before editing. Someone may have changed something in the admin UI since your last sync, and pushing a stale file would quietly revert it. Read the diff before pushing. It names the steps you're touching and says how many people are standing on anything you're removing. Pull again after a structural push — Mimeo mints ids for new steps and emails, and the second pull is how your files catch up.

push is all-or-nothing: it diffs, validates every definition, dry-runs the flows that changed against a real person, and only then asks to apply. Applied changes appear live on any admin page you have open. Every command and flag: the CLI docs.

What's in the repo

flows/<key>.json                  validated flow definitions
segments/<key>.json               rules definitions
guards/<id>-<name>.json           condition + action + scope
sequences/<id>-<name>.yml         ordered email refs, delays, repeat mode
emails/<id>-<subject>.md          markdown body + YAML frontmatter
templates/layouts|components/     full HTML/CSS
templates/layouts.yml             each layout's theme + the default layout
media/<filename>                  the media library's files themselves
media.yml                         each media file's hosted URL, alt text, id
fields.yml                        custom field definitions
products.yml                      product keys + names
themes.yml                        colours, type + page shape layouts use
settings.yml                      tunables, send windows, mailing address

A fresh clone has only empty directories — the files arrive with your first pull. Everything else in the repo (your README, notes, CLAUDE.md, .claude/skills/) is invisible to the CLI: never read, never pushed, never removed. The formats in full: Definition files.

Two of those folders are there for you and your agent to write in. changelog/ is the history of the work: one dated file per day (YYYY-MM-DD-description-of-changes.md), opening with a plain-language overview and then the key changes. Your agent starts one every session and keeps it current as it goes, so "what happened to the onboarding flow in March" has an answer that isn't a pile of diffs. integrations/ is where you write down how data reaches your Mimeo — the signup form on your site, your checkout, a webhook from another service, a nightly import. Start in integrations/integrations.md and split it into a file per place when it outgrows one; your agent reads it before touching anything a live integration feeds, and adds to it as it learns. No keys or tokens in either, same as everywhere else in the repo.

Secrets stay out by design. The token file is gitignored (the CLI re-adds the ignore line if it's ever missing), and settings.yml carries tunables, send windows and the footer's mailing address — provider credentials and webhook secrets live encrypted on your Mimeo and never appear in a file.

Your agent in this repo

Open the repo in Claude Code (or any agent that reads .mcp.json) with MIMEO_TOKEN set, and it has both surfaces at once: the files, and your Mimeo's MCP server — the full tool surface, authoring included, best used for questions and changes that don't need a commit. CLAUDE.md teaches it the rules that matter — never renumber a node id, never de-duplicate emails, always pull before editing.

The bundled skills cover the recurring work:

When to use which surface: Files or MCP?

Next: The CLI →  ·  Definition files  ·  The MCP server