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

Download the latest Mimeo Manager ZIP from the License page in your Mimeo account. Mimeo and Mimeo Manager share one version per release; choose the matching pair. Extract the manager ZIP on the computer where you run your coding agent, preserving hidden files such as .mcp.json and .gitignore, and read its README and agent instructions.

You need Git and Ruby 3.0 or newer, including Ruby's standard libraries. The CLI is the single file bin/mimeo; it requires no additional gems. Open a terminal inside the extracted manager folder, then initialize your own repository:

git init

On your Mimeo instance, open Settings → Agents & API → Manager repo and choose Create a token & show the setup commands. The wizard's finish screen offers the same handoff. Copy the token securely while it is visible; it is shown only once and grants full API access.

In your extracted workspace, connect to your own app URL, replacing the example below. Paste the token when prompted; the terminal prompt does not hide typed input, so do this in a private terminal session.

./bin/mimeo init --host https://mimeo.example.com

If extraction did not preserve the executable bit, run chmod +x bin/mimeo first. init checks the connection, saves the host in .mimeo/config.yml and the token in gitignored .mimeo/token, pulls definitions and media, and updates the bundled .mcp.json to point at your instance. It then prints these next steps; run them yourself:

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

The commit starts your history with your Mimeo's definitions and media. This snapshot is not a database backup: people, events, and sending history stay on the server. The export is how the MCP server authenticates — the committed .mcp.json carries ${MIMEO_TOKEN} instead of a real credential. Launch your agent from that environment, or supply the variable through its secret-management settings. Agents that do not read .mcp.json need their own MCP configuration.

Run ./bin/mimeo diff to confirm the workspace agrees with the instance. Add your own private Git remote if you want off-computer history; no remote is required, and Mimeo never reads your Git repository. Keep tokens and subscriber exports out of commits.

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

Your instance's definition files arrive with the first pull. Everything else in the repo (your README, notes, agent instructions, and bundled 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:

• build-a-flow-spec-and-push — turn a plain-language brief into a flow
• draft-an-email — write one, asking the sharing question the app asks
• edit-a-layout — change the HTML and CSS every email is dressed in
• define-a-segment — express "who" as rules that evaluate live
• import-a-csv — bring a list in: map its columns, preview, confirm, commit
• fire-an-event — record something happening, previewed before it fires
• audit-account-state — what's unused, what's shared widely, what's drifted
• pull-a-fresh-snapshot — sync the repo and describe what moved

When to use which surface: Files or MCP?

Bringing an existing email operation over? Start with Migrating from another email platform. Your agent can plan cohorts, map imports, and review the cutover; approve live imports and sends before it acts. Before you hand your agent the repo, read how to keep its changes from reaching anyone by accident.