Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Merge origin/main into feat/ruflo-console-mod

ruv0150757686b9
diff --cc plugins/ruflo-mods/README.md
index b9100b576d,18e0980cc9..339f5f6c8c
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@@ -1,14 -1,62 +1,62 @@@
# ruflo-mods
- ruflo as a Claude Code mod (function hooks): on by default in Claude Code >= 2.1.287; from 2.1.277 with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. Design and evidence: [ADR-404](../../v3/docs/adr/ADR-404-claude-code-mods-function-hooks.md).
+ ruflo as a Claude Code mod (function hooks): on by default in Claude Code >= 2.1.287; from 2.1.277 with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. Design and evidence: [ADR-404](../../v3/docs/adr/ADR-404-claude-code-mods-function-hooks.md), including Amendment 1 (default-on in `ruflo init`).
```bash
- ruflo mods install # opt in for this project (.claude/settings.local.json)
- ruflo mods doctor # function hooks on? refused by policy? what does it own?
- ruflo mods uninstall # remove only what install added
+ ruflo init # new projects: mods on by default, in the committed .claude/settings.json
+ ruflo init upgrade --mods # existing projects: merge the same keys (never overwrites yours) and install
+ ruflo mods install # just this checkout (.claude/settings.local.json); --scope project for the team
+ ruflo mods install --source local # dogfooding: load the mods live from this ruflo checkout (no clone)
+ ruflo mods doctor # marketplace source and freshness, plugins loadable, function hooks, what it owns
+ ruflo mods uninstall # claude plugin uninstall what ruflo installed; remove exactly the keys it added
```
+ These enable `ruflo-mods@ruflo`, `ruflo-swarm@ruflo` and `ruflo-console@ruflo`, the `ruflo` marketplace and `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. A key you already set is left as it is: a plugin you set to `false` stays off and is never installed. `ruflo init --no-mods` writes none of it.
+
+ ## What loads
+
+ - **ruflo-mods and ruflo-console** run only where function hooks are on. With them off, or with Claude Code's rollout switch off, they do nothing, and the classic hooks keep every event.
+ - **ruflo-swarm** loads its commands, skills and agents even without function hooks. With them on, it is also a mod that can run host commands (pane actions you start).
+ - **ruflo-console** is reported as "pending" until it is released in the marketplace.
+ - **The ruflo marketplace is cloned on first use.** Each teammate's first trusted, interactive Claude Code start clones `github.com/ruvnet/ruflo`. A headless `claude -p` on a fresh config loads nothing. Once the marketplace is cloned, which `ruflo init` does, `claude -p` loads the mods too.
+ - **Optional hardening:** set `pluginConfigs["ruflo-mods@ruflo"].options.modTrust = "refuse-risky"` with `modTrustAllow` in user or managed settings. Project settings cannot set it. The default is `observe`, which names what each later mod can do and blocks nothing.
+
+ ## Install and repair
+
+ When a `claude` binary is on PATH, init and install also do what you would do by hand, in the project directory:
+
+ ```bash
+ claude plugin marketplace update ruflo # or, first time: claude plugin marketplace add ruvnet/ruflo --scope <scope>
+ claude plugin install ruflo-mods@ruflo --scope <scope>
+ claude plugin install ruflo-swarm@ruflo --scope <scope>
+ ```
+
+ Settings alone are not always enough. Claude Code loads these plugins from its local clone of the `ruflo` marketplace (`~/.claude/plugins/marketplaces/ruflo`, or under `$CLAUDE_CONFIG_DIR`), with or without an install record.
+
+ - **No clone yet.** An interactive, trusted session clones it on start. A headless `claude -p` run does not.
+ - **A stale clone.** A clone from before ruflo-mods shipped has no `plugins/ruflo-mods`, so Claude Code skips the enabled plugin without a word, and `/ruflo-mods` is an unknown command. It does not refresh the clone on start. `ruflo mods doctor` and `ruflo doctor` report this as a failure, with the exact commands above.
+ - **Why `claude plugin install` too.** It keeps a cached copy that still loads if the clone goes stale later.
+
+ `ruflo mods uninstall` runs `claude plugin uninstall <id> --scope <scope>` only for the plugins ruflo itself installed: ones that were not installed before and that ruflo enabled. It then removes exactly the settings keys ruflo added. Both are recorded in `.claude-flow/mods/install.json`.
+
+ ## Dogfooding: `--source local`
+
+ `ruflo mods install --source local` declares the `ruflo` marketplace as a directory source pointing at a ruflo checkout: `--marketplace-path <dir>`, or by default the project root, which must hold the `ruflo` `.claude-plugin/marketplace.json`.
+
+ - **Live from the working tree.** Claude Code loads the plugins straight from that directory: no clone, nothing to go stale, and edits show on the next session. Verified on 2.1.287.
+ - **No `claude plugin install`.** Installing would pin a cached snapshot instead of the live tree.
+ - **One marketplace per config dir.** Claude Code keeps one `ruflo` marketplace per config dir, so switching it to a directory applies to every project on that machine. Switch back with `claude plugin marketplace add ruvnet/ruflo`.
+ - **Doctor** reports the source type, and warns when a project declares one source but Claude Code knows `ruflo` by another.
+
+ ## Flags
+
+ - `--no-plugin-install` writes settings only and runs no `claude` command.
+ - `--dry-run` (`mods install`, `mods uninstall`) prints the settings and the `claude` commands without running either.
+ - If `claude` is missing or a step fails, the manual commands are printed and the exit code is 0. Pass `--strict` (`mods install`) to exit 1 instead.
+ - Under `VITEST` or `CI`, init skips the `claude` step and prints the commands.
+ - Claude Code reformats `.claude/settings.json` (key order) when it installs at project scope. ruflo says so and leaves it: the content is unchanged.
+
-In a session, `/ruflo-mods` reports what the mod owns, routed, recorded and tightened.
+In a session, `/ruflo mods` (through ruflo-console's `/ruflo`) reports what the mod owns, routed, recorded and tightened. `/ruflo-mods` still works for one release as a deprecated alias.
## What it does