Routines your twin runs, one file each.

About ten minutes, with your twin running (the menu bar app, or mirrin run). You'll build rain check.

1. Make the file

   This writes ~/.mirrin/protocols/rain-check.yaml, already a working protocol that runs when asked.

   TerminalCopy

   $ mirrin protocols new rain check

2. Say what it should do

   Open the file in any text editor and brief your twin: when to run, what it needs, which values each person fills in, and when to stay quiet.

   rain-check.yamlfrom the quickstart

   name: rain check
   description: Warns on weekday mornings when rain is likely during something outdoors.
   version: 0.1.0
   author: your-handle
   tags: [weather, daily]
   schedule: "30 6 * * 1-5"
   requires: [calendar, web]
   vars:
     city:
       description: The city to check the forecast for
       required: true
     forecast_site:
       description: A forecast page fetch_url can read
       default: https://wttr.in
   prompt: |
     Look at today's calendar with list_events and pick out anything that happens
     outdoors or means walking somewhere. Fetch the forecast for {{city}} from
     {{forecast_site}} with fetch_url. If rain is likely during any of those, say so
     in one or two sentences: which event, what time, and what to bring.
     If nothing is outdoors, or no rain is expected, reply NOTHING_TO_REPORT.

3. Lint it

   Lint finds what breaks a protocol or makes it hard to share: a {{var}} that isn't declared, a schedule cron can't read, a scheduled prompt that never says NOTHING_TO_REPORT, a requires that isn't a known skill or tool, and anything that looks like a password or key. It exits with status 1 on an error.

   TerminalCopy

   $ mirrin protocols lint ~/.mirrin/protocols/rain-check.yaml

4. Check it on your machine

   Lint checks the file; check checks it against your own twin. Each protocol gets a line: ✓ ready, ✗ and what isn't connected, or ! and the values still to fill in. Put your city in ~/.mirrin/protocols/vars.yaml, under rain check:, and run it again.

   TerminalCopy

   $ mirrin protocols check

5. Run it now

   Say /reload to your twin so it reads your edits. Then open the Routines page (Protocols… in the menu bar or tray; with mirrin run, mirrin devices page and then Routines) and press Run now. Or say “run rain check” in chat: running a protocol asks first, and the answer comes back into the conversation even when there's nothing to report, which makes chat the better way to test. From then on the schedule takes over; change it on the same page (Set time, Skip next) or just say “move rain check to 7:15 on weekdays”.

Each step with what you'll see, and what to do when it isn't that: Your first protocol in ten minutes. Then the writing guide, on writing protocols people keep switched on.

A pack is a git repository with a pack.yaml, a protocols/ folder and, if you like, a personas/ folder. Start from the template: it has a protocol, a persona and a lint workflow. The registry is a single list of packs, kept in the Mirrin repository; the packs themselves stay in their authors' own repositories.

• Available now Find one. Search looks in each pack's name, description and tags. Every release carries a copy of the index, so it works offline too.

  mirrin protocols search travel

• Available now Install it by name, from the registry, at the commit its entry names.

  mirrin protocols install <name>

• Available now Or by its address, and pin it with # and a tag, a branch or a full commit.

  mirrin protocols add https://github.com/you/mirrin-pack-weather-wise#v0.2.0

• Available now Update. It shows the old and new commit and every file that changed, and applies them only when you say yes (--yes to skip asking).

  mirrin protocols update

• Available now See what you have, and remove a pack.

  mirrin protocols
  mirrin protocols remove weather-wise

Or ask your twin: “is there a protocol for commuting?” searches the registry and can show you what a pack would add before it installs anything. The Routines page has the same under Find more.

• A pack stays put. It stays on the commit it was installed at until you apply an update. Pinned to a commit, it stays there; pinned to a tag or branch, it follows it.
• Your copy wins. A protocol of your own with the same name as a pack's is the one that runs, so you can change one routine without forking the pack.
• Listing yours is a pull request that adds one entry to the registry, with the full commit to install. A maintainer reads the pack at that commit before it's merged.
• Your licence. A pack in your own repository is under the licence you give it there; listing it doesn't change that.

Make a pack: the layout, testing it on a throwaway twin, pinning and shipping updates. Get your pack listed: the entry, the pull request and what reviewers check.

1. It's a brief, not a program.

   Nothing in a protocol is executed. Its prompt is handed to your twin, which acts with the tools you've connected, under the same approvals as anything you ask it yourself.

2. What asks first.

   Sending email or messages, changing your calendar, clicks and form fills in the browser, writing files, phone calls, and running, creating or changing a protocol or installing a pack. With the default settings, reading your calendar and mail and fetching public pages run without asking.

3. The hard floor.

   Payments, shell commands, payment-looking clicks in the browser and sensitive files (~/.ssh, keychains, .env files, private keys and more) always ask, whatever your settings say. A “never” you've set stays a refusal.

4. No standing powers.

   “Yes, always” can't be given for creating or changing protocols, installing packs or clicks in the browser, so a protocol can't talk its way into more.

5. Never secrets.

   Passwords, API keys and tokens belong in your config or a connected account, never in a protocol, which is meant to be shared and is shown in full to anyone who previews it. mirrin protocols lint fails on anything in a prompt or a var's default that looks like a key, a token or a written-out password. It doesn't read descriptions or READMEs, so check those yourself.

6. Read it before you install it.

   A pack's protocols are trusted like your own, and its scheduled ones start at their next due time. Ask your twin to show you a pack first, or press Preview on the Routines page: you'll see each protocol's schedule, what it needs and every word of its prompt. mirrin protocols add and install install straight away, so read the pack's protocols/ folder on its repository page first.

What a harmful pack could try and what stops it, the red flags reviewers look for, and how to report one: the safety model for protocols and packs.

1. Share a routine as a pack

   No programming needed. Write it, put it in a pack from the template, lint it, run it on your own twin, then open a pull request that adds one entry to the registry. It stays in your repository, under your name and your licence.

2. Improve the six starters

   Every new install begins with them, so the bar is high: useful to nearly everyone, built on what most people connect, and quiet when there's nothing to say. Fixes to the six are welcome as pull requests; a new starter starts as an issue.

3. Improve the engine

   The loader, scheduler, lint and pack tools are written in Go; the contributor's guide shows where each one lives. Work on a throwaway twin, MIRRIN_HOME=$(mktemp -d), so nothing you try reaches your own.

No time to write it? Open a Protocol idea issue and describe it the way you'd brief a person. What you contribute to the repository is MIT, like the rest of the source; a pack in your own repository stays under the licence you give it. By taking part you agree to the Code of Conduct.