SFFMC

OpenCode plugins ported from Xiaomi MiMo-Code — drop in, no fork required

🚀 Quick start · 📖 Docs · 💬 Changelog · 🤝 Contributing

🇬🇧 English · 🇷🇺 Русский

---

⚡ TL;DR

# 1. Install all five packages
npm install -g @sffmc/runtime @sffmc/cognition @sffmc/memory @sffmc/safety @sffmc/utilities

# 2. Add to ~/.config/opencode/opencode.json
# 3. Restart OpenCode
# 4. Verify

That's it. No fork, no patches, no rebuild.

---

🤔 Why SFFMC?

Vanilla OpenCode	OpenCode + SFFMC
Manual workflow scripts	⚙️ 7 built-in workflows (`deep-research`, `security-audit`, `refactor`, `plan`, `tdd`, `doc-gen`, `lib-migrate`)
Forgotten context between sessions	💾 FTS5 memory + dream consolidation
Dangerous tool calls slip through	🛡️ 5-layer safety gate + auto-max escalation
One answer per question	🧠 Max-mode with LLM-as-judge, picks the best of N candidates
No health visibility	🔬 13 monorepo diagnostics

The name is a small wink at the upstream project: Some Feature from Mimo Code.

---

✨ What's in the box?

⚙️ Workflow engine Sandboxed JS scripts with budget caps, resume, and child workflows. Write your own or copy one of the 7 built-ins.	🛡️ Safety gates Catch destructive operations before they hit the disk. Auto-recover from tool failures. Auto-escalate to max-mode when the model is stuck.
💾 Cross-session memory FTS5 search, checkpoint journaling, dream consolidation. Your context survives between chats — the model remembers yesterday's decisions.	🧠 Max-mode reasoning Generate N parallel candidates, pick the best with an LLM-as-judge. Higher quality answers without paying for retries.

📖 See the full feature list →

---

📦 The 5 packages

Package	Role	Type	Version
@sffmc/runtime	Sandboxed JS workflow orchestrator + 7 built-in workflows	Standalone plugin
@sffmc/cognition	Max-mode reasoning, compose skills, health diagnostics	Standalone plugin
@sffmc/memory	Cross-session memory, judge, dream, checkpoint	Composite plugin
@sffmc/safety	Watchdog, safety gates, auto-max	Composite plugin
@sffmc/utilities	Shared SDK — config, event-bus, hooks, paths	Library (no plugin slot)

Composite plugins can read state from other SFFMC plugins but only write to their own slot. utilities is consumed by the other four and never appears in your plugin array.

---

🚀 Quick start

Pick the install path that fits you best:

Option A — npm (simplest)

npm install -g @sffmc/runtime @sffmc/cognition @sffmc/memory @sffmc/safety @sffmc/utilities

Then add the four plugins to ~/.config/opencode/opencode.json (the order matters — composites first):

{
  "plugin": [
    "@sffmc/safety",    // composite: catches destructive ops
    "@sffmc/memory",    // composite: loads past context
    "@sffmc/runtime",   // standalone: workflow engine
    "@sffmc/cognition"  // standalone: max-mode reasoning
  ]
}

Restart OpenCode. Verify the install:

/sffmc_health

You should see 13 diagnostics run in the terminal. ✅

Option B — one-liner (clones repo + auto-configures)

# macOS / Linux (requires SSH key on GitHub)
curl -fsSL https://raw.githubusercontent.com/Rahspide/sffmc/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Rahspide/sffmc/main/install.ps1 | iex

The script clones the repo, runs sffmc init, and edits opencode.json for you. Override the target branch with SFFMC_VERSION=v0.16.3.

Option C — from source

git clone https://github.com/Rahspide/sffmc.git ~/.sffmc/plugins/sffmc
cd ~/.sffmc/plugins/sffmc
./install.sh

📖 Full install guide (version pinning, troubleshooting, platform notes): docs/install.md →

---

🔧 CLI reference

Every install ships a sffmc binary:

Command	What it does
sffmc init	Re-sync opencode.json with the 4 plugins
sffmc init --all	Install all 5 packages (including utilities library)
sffmc init --yes	Skip the confirmation prompt
sffmc update	git pull + re-run init
sffmc doctor	Run the 9-check diagnostic
sffmc uninstall	Remove all SFFMC entries from opencode.json

💡 Run sffmc doctor after any OpenCode upgrade — it catches plugin loading order issues, missing dependencies, and config drift.

---

🏗️ Architecture

SFFMC follows a composite pattern:

• Each plugin reads freely from other plugins' state.
• Each plugin writes only to its own slot — no shared mutable state.
• Hot-pluggable — add or remove a package without touching the others.

Hook categories (dispatched by mergeHooks from @sffmc/utilities):

Category	Semantics	Hook keys
TRANSFORM	Chain (first → last)	experimental.chat.messages.transform, experimental.chat.system.transform, experimental.text.complete
GATE	First-truthy-wins	tool.execute.before, tool.execute.after, permission.ask, command.execute.before
SIDE_EFFECT	All run, return discarded	config, event, experimental.session.start, experimental.session.end
tool	Later-wins with warn	registered tool definitions

📖 Full SDK reference: CONTRIBUTING.md →

---

🎬 Demo: safety gate catches rm -rf

Real SFFMC session — @sffmc/safety immediately denies rm -rf / (the Error: [Rules] DENIED: ... line is the verbatim output from packages/safety/src/rules/index.ts). For a less-dangerous rm -rf /tmp/build it asks (logs a WARN, then OpenCode shows its built-in permission dialog where the user clicks Deny).

---

🧪 Quality gates

Every commit runs a 6-step gate chain. The precommit script runs the same gates locally:

#	Gate	What it checks
1	🚿 Cleanroom	Banned identifiers, external URLs, workflow-term regex
2	⚡ ReDoS audit	safe-regex over the redaction-rules catalogue
3	🔗 Load-order audit	AST-based hook-conflict detection
4	🧪 Test suite	1946 tests across 109 files
5	💚 Health summary	13 monorepo diagnostics
6	📝 Typecheck	bun build --no-bundle

bun run precommit   # runs gates 1–6 locally before push

bun.lock is regenerated on every version bump to keep workspace pins in sync with manifests.

---

📚 Documentation

Doc	What's inside
📥 Getting started	Install, first workflow, debugging
⚙️ Dynamic workflow	Sandbox internals, budgets, error model
🧪 Workflow examples	5 copy-paste workflows
📥 Install guide	Manual install, platform notes
🚀 Drone CI	CI pipeline reference
✨ MiMo features	What's ported, what's not

---

🤝 Contributing

1. Fork the repo.
2. Branch with a descriptive name: feature/<slug> or fix/<slug>.
3. Code with tests — coverage matters. New hook category? Add a regression test and re-run bun run audit:load-order.
4. Run the local gate: bun run precommit.
5. Push and open a PR — CI runs the same 7 gates.

See CONTRIBUTING.md for the plugin SDK reference, hook categories, and architectural decisions.

Local dev workflow — clone the repo, then add file:// entries to your opencode.json pointing at your working copy:

{
  "plugin": [
    "file:///path/to/sffmc/packages/safety",
    "file:///path/to/sffmc/packages/memory",
    "file:///path/to/sffmc/packages/runtime",
    "file:///path/to/sffmc/packages/cognition"
  ]
}

Your edits hot-reload — no need to re-run the installer.

---

📝 License

MIT — see the file for full text. Some functionality is adapted from Xiaomi MiMo-Code under the upstream license.

---

_{Built with 🧡 by @Rahspide · Powered by Bun · Inspired by Xiaomi MiMo-Code}