Repository avatar
AI Tools
v0.1.1
active

factoryhub

io.github.Mindburn-Labs/factoryhub

Find, read, validate, export and run AI factories with your own model. Runs stop at human decisions.

Documentation

factoryhub. AI factories, shared. Find a factory. Make it yours.

AI factories, shared.

The open format, engine, command line and MCP server for AI factories:
small teams of AI agents written as plain files that anyone can read, run, change and share.

Quickstart · Docs · Spec · Factories · Integrations · Contributing

License: Apache-2.0 Node.js 22 or newer Format: v1alpha1

What a factory is

A factory turns what a person gives into a finished, checked document. It says who does what, in what order, what gets checked, and where the person decides, in three kinds of plain files:

meeting-to-actions/
  factory.yaml              name and what it is for
  flow.yaml                 inputs and steps
  agents/<name>/agent.md    one role per agent

Here is part of a real one, factories/meeting-to-actions/flow.yaml, with some fields left out and its task texts shortened:

flow: mindburn.flow/v1
title: Meeting to actions
version: "1.1.1"
inputs:
  notes:
    type: longtext
    help: "The meeting notes or transcript, as rough as they are."
steps:
  extraction:
    title: Extract what was agreed
    agent: analyst
    kind: work
    task: |
      Read the notes and pull out four lists. Decisions: ...
  followup:
    title: Write the follow-up
    agent: writer
    kind: deliver
    needs: [extraction]
    task: |
      Write the follow-up. Sections, in this order: ...
  check_extraction:
    title: Check against the notes
    agent: reviewer
    kind: check
    needs: [followup]
    checks: followup
    task: |
      Compare the entire follow-up with the original notes. ...

Steps run in the order their needs allow, in parallel where they can. A check sends weak work back to be redone. An approve step stops the run until the person decides; nothing decides for them unless they ask for it with --yes. Every finished run writes a receipt: the hash of the factory, every step, every check verdict, every decision and the deliverable. Concepts explains the parts; the spec has every field.

Quickstart

You need Node.js 22 or newer and git.

git clone https://github.com/Mindburn-Labs/factoryhub && cd factoryhub
npm ci
npx factoryhub inspect meeting-to-actions

Then run it with your own model key, or a model on your machine:

export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, or OPENROUTER_API_KEY
npx factoryhub run meeting-to-actions -i notes=@notes.txt

npx factoryhub run meeting-to-actions --provider ollama --model <model>

Make your own with npx factoryhub new my-factory; it validates and runs from the start. More in the quickstart.

What is in this repository

PartWhat it does
spec/The factory format v1alpha1: a readable specification, JSON Schemas for factory.yaml, flow.yaml and the single-file form, conformance fixtures that test the schemas against the engine, the skill export mapping, and an RFC process.
packages/engineThe engine with no dependencies: parses a factory, runs its flow on Anthropic or any OpenAI-compatible model, writes and verifies receipts. The factoryhub site runs a copy of this engine.
packages/clifactoryhub: list, inspect, validate, run, resume, new, pack, export --as skill, search, get. Reference.
packages/mcpA local stdio MCP server: list, read, validate, export and run factories from any MCP client. Runs stop at every decision and resume with the person's answer. Reference.
factories/The house factories, each checked by npm run validate and the CI workflow, with a generated index.json.
integrations/An Agent Skill, a Claude Code plugin, OpenClaw and Hermes Agent skills, MCP client entries, and nine examples for seven agent frameworks.

The house factories

FactoryWhat it doesInputs requiredStepsAsks you to approveWeb tools
client-file-readinessCompares what a client sent against your checklist, reports what is missing, from the wrong period or unclear, and drafts the message asking for it.3 of 43nonone
competitor-teardownReads your website and up to three competitors, then writes a decision-ready brief showing where you win, where you lose and what to change this week.2 of 35noweb_fetch, web_search
homepage-auditReads your home page the way a first-time visitor does and returns a prioritised list of fixes with the exact new wording.1 of 34noweb_fetch
inbox-triageSorts a batch of customer messages by urgency and type, drafts a reply to each in your tone, and lists what needs a human decision.2 of 34nonone
launch-kitTurns a product description into a launch kit with positioning, a landing page draft, a launch email, three follow-ups and posts for social channels, all in one voice.2 of 56yesweb_fetch
meeting-to-actionsTurns rough meeting notes or a transcript into decisions, owned actions with dates, open questions and a follow-up message ready to send.1 of 23nonone
newsletter-noteWrites a short newsletter note, under 120 words, that tells your readers what your new video, podcast or talk is about and points them to it, using only the facts sheet.1 of 32nonone
outreach-packTurns checked market research and launch materials into an outreach pack.2 of 33nonone
prospect-briefResearches one company you want to sell to and writes a one-page brief plus a first email and follow-up that mention real, checkable facts about them.2 of 37yesweb_fetch, web_search
release-deskPuts the posts, the short-video script and the newsletter note written from one video into a single release packet: the week at a glance, every piece checked against the others and the facts sheet, and every claim listed with the words it rests on, for you to approve once.1 of 43yesnone
short-video-cutWrites a 30-second script for TikTok, Reels or Shorts and a cut list from the facts sheet of one video, podcast or talk: a hook, three beats and a closing line, each clip with the timestamp and the exact words where it starts and ends.1 of 32nonone
video-factsReads the transcript of one video, podcast or talk and writes a facts sheet: every number, result, claim and quote the speaker states, in their own words, with each hedge kept and a timestamp or the first words for each.1 of 12nonone
video-to-postsTurns the transcript of one video, podcast or talk into a week of posts for X, LinkedIn, a short video and a newsletter, using only what the speaker said.1 of 24yesnone
week-of-postsWrites an X thread, two single posts and a LinkedIn post from the facts sheet of one video, podcast or talk, in the speaker's voice, saying nothing the facts sheet does not say.1 of 32nonone

Add yours: a factory in five minutes.

Use it from your agent

Each integration is marked with what was actually tested at this commit. "Tested locally" means exercised on a maintainer's machine with the version and result recorded in the status matrix; "documented only" means written from the tool's current docs and not exercised. CI has not run yet, so nothing is marked "tested in CI".

WhereHowStatus
Claude Codeplugin with the skill and the MCP servertested locally
Gemini CLIMCP entrytested locally
CodexMCP entrytested locally (ran a factory to its approval step)
CursorMCP entrydocumented only
VS CodeMCP entrydocumented only
Claude DesktopMCP entrydocumented only
OpenClawskilltested locally (skills-ref validator)
Hermes Agentskilltested locally (its parser, validator and skills guard)
Any agent that reads skillsAgent Skill, or factoryhub export --as skilltested locally (skills-ref validator)
Vercel AI SDK, OpenAI Agents SDK (JS and Python), LangChain (JS and Python), smolagents, Hugging Face, CrewAI, LlamaIndexframework examples over MCPlisting tools: tested locally; agents: documented only

Setup for each: docs/integrations.md.

factory.mindburn.org

Mindburn Labs runs a hosted factoryhub at factory.mindburn.org, currently in private preview. factoryhub search and factoryhub get read its published catalogue; while the preview lasts they need the access key you were given, in FACTORYHUB_ACCESS_KEY. Everything else in this repository works without it.

Contributing

Contributions are welcome: factories, fixes, docs, integrations and format proposals. Start with CONTRIBUTING.md. Changes to the format go through RFCs. The roadmap lists what comes next.

Community

License

Apache-2.0. Each factory declares its own license in its flow.yaml; the house factories declare MIT. The ClawHub skill files in integrations/openclaw/factoryhub are MIT-0, as ClawHub requires. See NOTICE.

NPM
factoryhub
Install Command
npm install factoryhub
Runtime: npx