Skip to docs content
Browse documentation
On this page

How Minion works

The factory loop as a conversation: ask what your favorite bot shipped, save the answer as an export you can invoke from any agent, then a daily email that stays quiet until something actually ships.

Minion turns a question you would ask again into code you own. The agent you already use does the thinking once. After that, asking is a package import, and a schedule can mail you only when something actually happened.

This page is the playbook for that loop. Every call below is made through the two MCP tools, search and execute.

The loop

  1. Ask once. "What did my favorite bot ship recently on GitHub?" Search finds the saved githubAccessToken secret and a memory that names minion-bot as the favorite bot, then execute fetches that user's public events with Authorization: Bearer {{secret:githubAccessToken}}. Filter to published releases and new public repositories.
  2. Save the answer shape. Offer to make it a package. After they say yes, open guide:package_with_daily_job (and guide:edit_a_saved_package for later changes), then create a package with a callable export using minion.packages.save. The export returns the list (or "nothing new") and records the newest event id in packageStorage().
  3. Ask again from any agent. "Anything interesting shipped by my favorite bot recently?" Search finds the owned package. Invoke it. A phone agent does not rewrite the GitHub walk.
  4. Get notified. From a third agent, in a new conversation: search first. There is no GitHub webhook for one person's public activity, so add a package-owned daily job. Open a repo session with minion.repo.openSession, change only the new wrapper and the manifest lines, then minion.repo.publish. The wrapper calls the same export and runs minion.email.send only when the list is non-empty. Run it once with minion.jobs.runNow before you trust the schedule.

What "shipped" means

Use GitHub's public events API, not a watched-repo notification. Count:

  • ReleaseEvent with payload.action === "published"
  • CreateEvent with payload.ref_type === "repository"

Ignore stars, forks, pushes, and issue noise. Store the newest seen event id so the next invoke or job run only reports what is new.

Package shape

  • Shared implementation that accepts an optional sinceId and returns { shipped, message }.
  • Callable export (for example ./whatShipped) that loads sinceId from packageStorage(), returns the list, and advances the cursor.
  • No-argument scheduled wrapper (for example ./daily-digest) that calls that export and sends mail only when shipped.length > 0.
  • A jobs entry in the minion block of package.json pointing at the wrapper, with a cron expression and timezone. Test it with minion.jobs.runNow before you rely on the schedule.

The fetch uses the saved githubAccessToken via Authorization: Bearer {{secret:githubAccessToken}}. minion.email.send only mails verified destinations, or your own account email when to is omitted.

When to load this guide

Open this page when someone asks how Minion works, what the loop is, or how an ad hoc question becomes an export and a quiet daily email. For the same loop in code, open guide:search_and_execute, then guide:package_with_daily_job. To serve a page from a package, open guide:serve_an_app.