Combo: Multi-Agent Workflow Orchestration (ruflo + claude-mem + claude-code-router) Partial

Scenario

You have a pile of tasks you want AI to do: organize notes, write weekly reports, review code, answer messages. If you open a session for each one manually, you re-explain context every time and nothing runs in parallel. What you want is a multi-agent workflow: define the steps, let several agents each own one step, share intermediate state, and have the results merged for you. This combo answers "how to organize several agents into a pipeline": ruflo owns orchestration (split a task into steps, run them in parallel or serially, with built-in memory and swarm), claude-mem owns cross-session memory (no re-explaining between steps), and claude-code-router owns model routing (different steps can use different models or providers). After install you get a workflow you can start with one command, with steps running automatically and state remembered across them.

Demand signal: Juejin "16 AI agents running 13 media accounts" 28612 views, "AI agents from scratch" 11316 views, "multi-agent collaboration workflows" 3379 views (demand/analysis-20260829.md R3 + analysis-20260830.md D3). If you only need to manage several coding sessions in the terminal, install herdr alone - this combo targets multi-step task pipelines, not session management.

Combo members

ruflo: orchestration main track (harness form)

• Download: npm package ruflo (official npm; China uses the npmmirror prefix)
• Version: 3.38.20 (measured on 2026-08-28; Node >= 18; requires an installed Claude Code or Codex client)
• Install: npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect (see "Step 3" in the walkthrough)

claude-mem: cross-session memory support

• Download: npm package claude-mem (official npm; China uses the npmmirror prefix)
• Version: 0.11.x (measured on 2026-08-28; Node >= 18)
• Install: npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem && claude-mem install --ide claude-code (see "Step 2" in the walkthrough)

claude-code-router: model routing support

• Download: npm package @musistudio/claude-code-router (official npm; China uses the npmmirror prefix)
• Version: 3.0.22 (measured on 2026-08-28; Node >= 18)
• Install: npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund (see "Step 1" in the walkthrough)

Solution overview

Alternatives (replace by scenario, do not mix):

• Team running many agents in parallel -> switch the main track to omc (team-first multi-agent orchestration, plugin form for the Claude Code ecosystem); keep ruflo for solo local pipelines.
• Not on the Claude stack and want one gateway -> switch model support to litellm (one OpenAI-compatible endpoint for 100+ models); possible-compatible with members by write-surface analysis, not measured.
• Building multi-agent apps in code (not a terminal user) -> switch the main track to agent-framework (Python library, matrix verified with claude-mem and claude-code-router).

Why this install order: install model routing (ccr) and configure providers first, then memory (claude-mem), then the orchestration main track (ruflo) last - ruflo init reads existing Claude config, so installing it later avoids it overwriting the first two. Note the inferred conflict surfaces between ruflo and ccr/claude-mem (see "Dependency warnings") - confirm the config files coexist manually after install.

Quick start (skip the walkthrough)

The one-click script is generated from this document (rendered at pages/combos/combo-multi-agent-workflow.sh). Backup and check prerequisites first, then run:

bash pages/combos/combo-multi-agent-workflow.sh

• You get: a multi-agent workflow - ruflo orchestration + claude-mem memory + ccr model routing.
• Estimated time: 10-15 minutes. Biggest risk point = ruflo init config coexistence (its write surface has inferred conflicts with ccr/claude-mem; confirm ~/.claude/settings.json and ~/.claude.json contents manually after install).
• Prerequisites: Node >= 18; an installed Claude Code or Codex client; disk < 500MiB (all three are npm packages).

Want to understand each step and how to recover from mistakes? See the walkthrough. If the one-click script fails, run the steps manually.

Walkthrough

Step 1: install claude-code-router (model routing first - the "model distribution" base for multi-step tasks)

ccr extracts "which model" out of tool config: configure providers once, and every agent step can switch models without editing client config. It writes the routing env section of ~/.claude/settings.json (also the shared surface ruflo must respect later). Use the npmmirror prefix in China (measured: 9s/102 packages).

npm_config_registry=https://registry.npmmirror.com npm install -g @musistudio/claude-code-router --no-audit --no-fund
ccr --help

Expected output: ccr --help prints the command list (measured v3.0.22) Confirm:

• ccr --help produces output; on first run configure a provider ("No available models" is normal before that).

Stuck?:

• npm slow/timeout -> the npmmirror prefix is already there; retry in another network window.
• No available models -> configure a provider per the guide, then ccr start.

Step 2: install claude-mem (memory second - the prerequisite for sharing context between workflow steps)

claude-mem captures sessions automatically, compresses them, and injects relevant context - step 3 does not need step 1's background re-explained. It registers a plugin into ~/.claude.json and writes ~/.claude/plugins/ during install (potential conflict surface with ruflo, see dependency warnings).

npm_config_registry=https://registry.npmmirror.com npm install -g claude-mem
claude-mem install --ide claude-code

Expected output: claude-mem install finishes registration (measured 0.11.x, MCP + worker form) Confirm:

• claude-mem --version prints a version; claude-mem install --ide claude-code exits without error.

Stuck?:

• install registration fails -> confirm the Claude Code client exists and is compatible; check guide.md FAQ for error details.

Step 3: install ruflo (orchestration last - init reads existing Claude config, so install last to avoid overwrites)

ruflo is a meta-harness: orchestration, memory and swarm for Claude Code / Codex. init uses non-interactive flags (measured: --no-signup --no-skills-sh --no-codex-detect); it writes a workspace-level .claude/settings.json afterwards - the shared write surface with ccr, so confirm coexistence manually per the dependency warnings.

npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

Expected output: ruflo init finishes; --version prints 3.38.20 Confirm:

• npx -y ruflo --version -> 3.38.20;
• the workspace .claude/settings.json contains the ruflo section AND the original ccr routing env section is still there (check with cat .claude/settings.json).

Stuck?:

• init hangs interactively -> use the non-interactive flags above; otherwise check network (npmmirror is built in).
• ccr section overwritten in settings.json -> merge manually: keep ccr's env.ANTHROPIC_BASE_URL etc., append the ruflo section (conflict handling in "Dependency warnings").

Daily use

• Start a workflow: run npx -y ruflo in the project directory and define steps with its orchestration commands (see ruflo guide.md).
• Shared context between steps: claude-mem injects automatically; use claude-mem subcommands to inspect memory manually.
• Switch models: use ccr to switch providers, or edit the routing section of ~/.claude/settings.json.

Uninstall and cleanup

• ruflo: npm rm -g ruflo || true (skip if you used npx); remove the ruflo section from the workspace .claude/settings.json (keep the ccr section!).
• claude-mem: claude-mem uninstall first (unregister), then npm rm -g claude-mem; ~/.claude-mem/ is its own config and can be deleted.
• ccr: npm rm -g @musistudio/claude-code-router; ~/.claude-code-router/ is its own config and can be deleted; confirm removal of the routing env section in ~/.claude/settings.json manually per the guide's uninstall section.

Install order

1. claude-code-router (model routing) -> 2. claude-mem (memory) -> 3. ruflo (orchestration main track). Configure routing, install memory, then orchestration last so ruflo init does not overwrite the first two; the combo is ready only after one multi-step task runs end to end.

Dependency warnings

• Conflicts (honest four states):
• ruflo x ccr: possible-compatible (partially verified 2026-08-30) - write surface fields/levels do not overlap: ruflo writes workspace .claude/settings.json env (measured: CLAUDE_FLOW_*/CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS only, no ANTHROPIC_*), ccr injects HOME ~/.claude/settings.json env (ANTHROPIC_*, triggered after provider config); ccr gateway start/stop coexists fine with ruflo doctor. Injection chain not triggered, not promoted to verified. Source: site docs.
• ruflo x claude-mem: possible-compatible (partially verified 2026-08-30) - claude-mem writes HOME ~/.claude.json (measured: newly created, no mcpServers section) + ~/.claude/plugins/, ruflo writes workspace + HOME CLAUDE.md pointer block (measured: preserved); write surfaces do not overlap; ruflo doctor unaffected. claude-mem IDE registration not verified (no Claude Code env), not promoted to verified. Source: site docs.
• claude-mem x ccr: compatible (verified 2026-08-28) - pipeline measured: co-installed smoke tests both passed, write surfaces disjoint. Source: site docs.
• agent-framework x ccr / agent-framework x claude-mem: compatible (verified) - pipeline measured. Source: site docs.
• omc x ccr: possible-compatible (inferred); omc x claude-mem is not in the matrix - check the matrix before switching main tracks, never overclaim unmeasured pairs.
• Versions: ruflo 3.38.20; claude-mem 0.11.x; ccr 3.0.22; Node >= 18 (all three are npm packages).
• Environment: all three depend on a Claude Code or Codex client (ruflo init detects the client); ccr needs provider config on first run; claude-mem install writes registration surfaces - uninstall before removing the package.
• China network: all three installs include the npmmirror prefix (measured); the likeliest sticking point is ruflo init config coexistence, not the network.

FAQ

1. Do ruflo and ccr conflict? -> Inferred conflict surface = overlapping sections in ~/.claude/settings.json, coexistence not measured. Install ccr and configure routing first, then run ruflo init; confirm both sections coexist with cat .claude/settings.json. Want to avoid config coexistence entirely? Use only ruflo (memory + swarm built in) and skip ccr/claude-mem.
2. Why not omc? -> omc is team-first multi-agent orchestration (plugin form), good for parallel work across a team; for solo local pipelines ruflo is lighter. Pick one main track per scenario, do not mix.
3. How is this different from herdr? -> herdr manages "terminal runtime for parallel sessions" (sessions/workspaces); this combo manages "multi-step task orchestration" (split steps / parallel / merge + memory + multi-model). Managing several sessions at once -> herdr; running multi-step tasks automatically -> this combo.
4. Does claude-mem slow every step down? -> it compresses and injects relevant context (MCP + worker form, measured); tune the injection in its config if it feels like too much (see claude-mem guide.md).

Acceptance check (one shot)

Run this block after installing; all green = combo ready; any failure -> back to the matching step in the install walkthrough.

npx -y ruflo --version
claude-mem --version
ccr --help

预期输出: ruflo 3.38.20; claude-mem 0.11.x; ccr prints its command list. All green = orchestrate -> memory -> routing command surface ready

Note: confirm the write surfaces coexist once after install - ~/.claude/settings.json (ccr routing env) and ~/.claude.json (claude-mem registration) both present (inferred conflict recorded); on first run ccr prompts for provider config (No available models is normal).

Verification evidence

Every combo is measured in an isolated environment (smoke + write-surface check); unmeasured items are honestly marked in the text, and measurement dates are listed in the verification section below.

Verified 2026-08-30 · TTL expires — (180 days)

• ruflo swarm orchestration layer (isolated test 2026-08-30): local ollama provider (configure/test connectivity PASS) + swarm init/start/status all passed (8 agent slots ready); the execution layer (agents actually running tasks) needs a Claude Code / claude -p channel, not verified. local repro log 2026-08-30.
• 3-tool integration (2026-08-30 isolated, partial): ruflo init + claude-mem install + ccr install/start/stop coexist in one environment, write surfaces do not overlap (see evidence); after install ruflo doctor 18 passed / All checks passed. Not fully verified: ccr env injection chain (needs provider config), claude-mem IDE registration (no Claude Code env) - honestly noted, not promoted to verified. local repro log 2026-08-30.
• Member-level measurements: ruflo (site docs claude-mem (site docs claude-code-router (local repro log +）.
• Verified matrix pairs: claude-mem x ccr (2026-08-28 pipeline), agent-framework x ccr, agent-framework x claude-mem (site docs).

Related problems

• agent-toolchain-coexist
• claude-code-router-3