The .mcyc routine format

The format is open

You do not need permission, a license, or a conversation with us to use it.

That split is deliberate. A routine you spent months refining should not be trapped in one vendor's app, including ours. If miniCycle disappeared tomorrow, a .mcyc file would still be a readable, documented description of your routine, and anything could open it.

If you build something that reads or writes .mcyc, we would genuinely like to hear about it, but that is an invitation, not a requirement.

At a glance

A complete file

This is valid and complete. Save it as morning.mcyc and import it.

{
  "name": "morning_routine",
  "title": "☀️ Morning Routine",
  "autoReset": true,
  "deleteCheckedTasks": false,
  "cycleCount": 0,
  "tasks": [
    { "id": "t1", "text": "💧 Drink a glass of water", "completed": false },
    { "id": "t2", "text": "🧘 Stretch for five minutes", "completed": false },
    { "id": "t3", "text": "📓 Write down today's top task", "completed": false, "highPriority": true }
  ]
}

Strip it further if you like. This is the smallest file that imports:

{ "name": "minimal", "tasks": [] }

With a scheduled task

Set recurring and describe the schedule. Only the sub-object matching frequency is read, so you can leave the others out:

{
  "name": "weekly_shop",
  "title": "🛒 Weekly Shop",
  "autoReset": false,
  "tasks": [
    {
      "id": "t1",
      "text": "🧺 Check what's already in the pantry",
      "completed": false,
      "recurring": true,
      "recurringSettings": {
        "frequency": "weekly",
        "indefinitely": true,
        "weekly": { "days": ["Sat"] },
        "time": { "hour": 10, "minute": 0, "meridiem": "AM" }
      }
    }
  ]
}

You do not need to write a recurringTemplates map. The app derives one from every task marked recurring when the file is imported.

Field reference

Defaults below are what the importer actually applies to a file that omits the field, which is not always the same as the value you would guess.

Root object

Task object

recurringSettings

frequency selects which sub-object is consulted, and may be hourly, daily, weekly, biweekly, monthly, or yearly. Use indefinitely: true to repeat forever, or indefinitely: false with a repeatCount. Weekday names are three letters: Sun through Sat. Full details, including the monthly and specific-date forms, are in the full specification.

Modes: how a routine resets

Two booleans at the root decide what happens when everything is checked off. There is no mode field. The mode is inferred.

Three things that surprise people

Each of these is a real behavior of the importer, not a caveat about edge cases.

"deleteWhenCompleteSettings": { "cycle": true, "todo": true }

Validating a file

A machine-readable schema is published alongside this page, so you can check a file before handing it to anyone.

Both URLs below are JSON Schema, draft 2020-12, and both describe what the importer accepts: a file that validates will import. They carry identical rules today. Pick one based on whether you want it to stay still.

A new format version gets a new filename, never an edit to an existing one. That is the guarantee that makes the pinned URL worth pinning, and it is why the two are served with different cache lifetimes: the versioned file is immutable, the current one stays correctable.

From the command line

# Node, using ajv (pinned: safe in CI)
npx ajv-cli validate -s mcyc-2.5.schema.json -d my-routine.mcyc --spec=draft2020

# Python, using check-jsonschema (reads the URL directly)
pipx run check-jsonschema \
  --schemafile https://minicycle.app/schema/mcyc-2.5.schema.json \
  my-routine.mcyc

In an editor

Most editors will offer completion and inline errors if you point them at the schema. In VS Code, map the extension once in your settings:

"json.schemas": [
  {
    "fileMatch": ["*.mcyc"],
    "url": "https://minicycle.app/mcyc.schema.json"
  }
]

Versioning and stability

Files carry a task-level schemaVersion of 2, matching the app's current 2.5 data schema. The format has been stable since then, and the importer still reads older files, including pre-2.5 layouts.

Our intent for anything built on this: existing files keep importing. New fields may be added, so treat unknown keys as ignorable rather than as errors, which is also how the app treats them.

Published schemas follow the same rule. Each format version gets its own permanent URL (/schema/mcyc-2.5.schema.json today), and a version that has shipped is never edited in place. If the format reaches 2.6, that becomes a new file and the 2.5 document stays exactly as it is, so anything pinned to it keeps validating the way it did on the day you pinned it.

The full specification carries the complete field-by-field reference, every recurring form, worked examples, security notes, and generator scripts for Node and Python. This page is the short version.