Skip to content
Get packs

Guide · Open source

How to use Ruflo: install, set up and run agent swarms

Updated · written with AI from the project's own documentation and checked against our catalogue data

Ruflo is an open-source MIT-licensed layer, written in TypeScript, that sits around AI coding assistants such as Claude Code and Codex. It lets several agents split up tasks, coordinate as a swarm and keep memory across sessions. This guide is for developers comfortable with the terminal and npm who want to set it up and understand what it does, and by the end you will know how to start it in Claude Code, Codex or another MCP client.

Rufloruvnet/ruflo · ★ 80.6k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Claude Code 2.1.287 or later, or another MCP-enabled client, and that Node.js is installed for npx.
  2. 2Install the Claude Code plugins. Run the marketplace add and plugin install commands inside Claude Code, then reload plugins and run /ruflo.
  3. 3Or run the setup wizard. For Codex or other MCP clients, run npx ruflo@latest init wizard in your project folder.
  4. 4Connect the MCP server. Configure your client to run npx with the arguments -y, ruflo@latest, mcp, start.
  5. 5Open the terminal UI. Optionally run npx ruflo tui to view overview, cost, swarm, events and missions.
  6. 6Review before trusting. Read the code of Mods and any integration before granting it your account's permissions.

What Ruflo does and who it is for

The README describes Ruflo as an agent meta-harness: the execution layer that gives a model tools, memory and controls so it can do longer jobs. The model writes code; Ruflo handles coordination around it.

It fits developers already using Claude Code or Codex who want multiple agents working together, and teams experimenting with multi-agent workflows and shared memory. It is less suited to non-developers looking for a simple chat app.

  • Multiple agents split up tasks and coordinate as a swarm
  • Memory is kept across sessions
  • Can expose Ruflo tools to an MCP-capable client

Prerequisites before you install Ruflo

The Claude Code plugin path requires Claude Code 2.1.287 or later. Node.js is required for npx, though the README excerpt does not state a minimum Node.js version.

Most integrations depend on Claude Code, Codex or another MCP-enabled client, so you need at least one of these already set up.

  • Claude Code 2.1.287 or later (for the Claude Code plugin path)
  • Node.js (required for npx; check the README for the version)
  • A terminal and a project folder

Install Ruflo in Claude Code

Inside Claude Code, add the Ruflo marketplace and install the plugins. Core provides foundation tools, Console opens the agent cockpit and Mods add routing and policy enforcement inside Claude Code.

Mods run with your account's permissions, so review their code before installing.

/plugin marketplace add ruvnet/ruflo /plugin install ruflo-core@ruflo /plugin install ruflo-console@ruflo /plugin install ruflo-mods@ruflo /reload-plugins /ruflo

Set up Ruflo for Codex or another MCP client

Run the setup wizard in your project terminal to set up the project. Then connect your client to the Ruflo MCP server. For clients that support local stdio MCP servers, set the command to npx and the arguments to -y, ruflo@latest, mcp, start.

MCP exposes Ruflo tools to your client. The console and mods are Claude Code integrations, and hook support depends on the client.

  • Command: npx
  • Arguments: ["-y", "ruflo@latest", "mcp", "start"]
npx ruflo@latest init wizard npx -y ruflo@latest mcp start

Try the optional terminal UI

The console also runs on its own, without Claude Code. It shows Overview, Cost, Swarm, Events and Missions, plus an optional AI page. Add --plain to print one frame for scripts.

The README links to a Terminal UI guide in docs/USERGUIDE.md for more detail.

npx ruflo tui

Use Ruflo day to day and know its limits

The README says that after init you can use Claude Code normally, and the hooks system routes tasks, learns from successful patterns and coordinates agents in the background. You do not need to learn every MCP tool or CLI command first.

Ruflo is not a fully audited, production-hardened security tool according to the README's warnings, so read the code of anything you install. Comparable projects include LangGraph, CrewAI, AutoGen and the OpenAI Agents SDK.

  • Start with the Claude Code plugin or the MCP server, not both at once
  • Review Mods code before installing
  • Compare against LangGraph, CrewAI, AutoGen or the OpenAI Agents SDK if you are unsure

What people use it for

  • Coordinating several Claude Code agents that split up a coding task
  • Sharing memory across sessions for a team experimenting with multi-agent workflows
  • Exposing Ruflo tools to an MCP-capable client such as Codex
  • Monitoring swarm activity and cost from the optional terminal UI

Frequently asked questions

Is Ruflo free to use?

Ruflo is released under the MIT licence, which is an open-source licence. The README excerpt does not list prices, so check the repository for any paid features or hosted services.

What are the requirements for Ruflo?

The Claude Code plugin path requires Claude Code 2.1.287 or later. Node.js is required for npx, and the README excerpt does not state a version. Most integrations depend on Claude Code, Codex or another MCP client.

How do I install Ruflo in Claude Code?

Inside Claude Code, run the marketplace add command for ruvnet/ruflo, install the core, console and mods plugins, then run /reload-plugins and /ruflo.

Does Ruflo work with Codex?

The README says to use npx for project setup and connect your client to the Ruflo MCP server. Run npx ruflo@latest init wizard, then configure npx with the MCP start arguments.

Is Ruflo safe to use?

The README warns that Mods run with your account's permissions, so review their code before installing. It is not presented as fully audited or production-hardened, so it may not suit security-critical work.

What are alternatives to Ruflo?

The source lists LangGraph, CrewAI, AutoGen and the OpenAI Agents SDK as comparable projects. Choose based on whether you already use Claude Code, Codex or an MCP client.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ruflo suits developers who already use Claude Code or Codex and want several agents to coordinate with shared memory, and who are comfortable with npm and the terminal. If you want a simple chat app, need audited production security, or do not use Claude Code, Codex or another MCP client, pick a different tool.

Install options & downloads