Claude-Flow — Multi-Agent Orchestration for Claude Code

What Claude-Flow Multi-Agent Orchestration Actually Is

Claude-Flow is an orchestration layer that runs on top of Claude Code, the official Anthropic command-line tool released in February 2025 (docs.anthropic.com/claude-code). Instead of asking a single Claude Code session to plan, write, review, and test, you fan that work out across 64 specialized agent archetypes — architect, reviewer, tester, refactorer, security, ops, and more — that share a SQLite-backed memory store and run in parallel. The orchestrator generates a plan from one high-level prompt, spawns the agents it needs, and resolves dependencies between them automatically.

The project is distributed via npm as claude-flow and lives at github.com/ruvnet/claude-flow. It is currently published on an alpha release cadence, so you pin a tag explicitly with npx claude-flow@alpha rather than relying on latest. Telemetry is opt-in: without environment variables set, runs stay entirely local on your machine.

The direct answer for engineers evaluating this skill: if you already use Claude Code and want parallel role specialization without writing a LangGraph state machine or wiring up AutoGen messaging, Claude-Flow gives you a registry, a memory layer, and a plan-first executor in three commands.

How the Swarm and Hive-Mind Modes Differ

Claude-Flow ships two execution modes, and picking the right one matters more than tweaking any individual agent prompt.

Swarm mode is the default and the one you reach for first. Each subtask spawns its own agent, agents run in parallel, and outputs are persisted as the run progresses. There is no shared mutable state during execution — agents finish, the orchestrator collects, and downstream agents receive structured inputs. This is the right model for tasks that decompose cleanly: "build a Rust port of zoxide" splits into design, scaffolding, implementation, tests, and review.

Hive-mind mode turns on shared memory across agents. Every agent reads from and writes to the same SQLite store as the run progresses, so a tester can see what the implementer just produced, and a security reviewer can see what the architect decided. You launch this with npx claude-flow hive-mind start. Use it when subtasks are tightly coupled — a refactor that spans many files, an incident response where multiple agents need a single consistent picture of the system.

The quick-use snippet from the official prompt template captures both:

# Initialize a new orchestration project
npx claude-flow@alpha init
# Run a swarm
npx claude-flow swarm "build a Rust port of zoxide"
# Launch hive-mind mode (multiple agents share memory)
npx claude-flow hive-mind start

A single init writes a .claude-flow/ directory containing the agent registry, the memory schema, and the run config. From that point forward, both modes operate on the same project state.

The 64-Agent Registry: What You Actually Get

The headline number — 64 specialized agents — is not marketing fluff; it maps to the full software development lifecycle. The registry covers planning roles (product analyst, architect, technical lead), implementation roles (backend, frontend, infra, database, refactorer), review roles (code reviewer, security auditor, performance auditor), validation roles (unit tester, integration tester, E2E tester, fuzzer), and operations roles (release manager, deployment, oncall responder, observability).

Each agent is a Claude Code subprocess plus a role-specific system prompt stored as Markdown inside .claude-flow/. Because the profiles are plain Markdown, you edit them like any other file in your repo. Adding a custom role takes one new file; deleting a role you do not want spawned takes one rm. There is no plugin API to learn, no framework abstraction to reverse-engineer.

The orchestrator decides which subset of the 64 to invoke for any given task. For a small bug fix it might spawn three agents; for a green-field feature it might spawn fifteen. The plan is generated up front, before any agent fires, so you can read it and abort if the orchestrator misunderstood the task.

Architecture: Node.js CLI Plus SQLite Memory

Claude-Flow itself is a Node.js CLI. There is no daemon, no server, no container. You install it with npx, run it from your project root, and it shells out to Claude Code subprocesses to do the actual model work. This matters for two reasons:

First, auth is inherited from Claude Code. You do not buy separate API credits, you do not configure a second key. Whatever authentication your local Claude Code CLI already has — Anthropic Console subscription, API key, enterprise SSO — flows through to every spawned agent. This is the same auth model Anthropic documents for the Claude Agent SDK (docs.anthropic.com/claude-code/sdk).

Second, memory is a single SQLite file. SQLite is a self-contained, serverless, zero-configuration database used by browsers, mobile apps, and embedded systems worldwide (sqlite.org/about.html). For Claude-Flow this means the memory layer adds zero infrastructure: no Redis, no Postgres, no vector database to provision. You can git-track the memory file as a build artifact, share it across a team for replayable runs, or .gitignore it like any other local cache. Schema changes are migrations on a file you fully own.

Step-by-Step: Going from Zero to a Running Swarm

The entire onboarding is three commands plus optional configuration. Here is the workflow as it appears in the prompt template, with each step explained.

1. Initialize the project. Run npx claude-flow@alpha init from the root of any repo. This scaffolds .claude-flow/ with the agent registry, the memory schema, and a run config. No global install, no package.json changes required outside the npx cache.
2. Inspect the agent registry. Open .claude-flow/agents/ and skim a few of the 64 Markdown profiles. Each one is a plain system prompt; reading three or four gives you a feel for the role boundaries the orchestrator will draw. Edit or delete profiles before your first run if you have strong preferences.
3. Pin a version. Replace @alpha with a specific tag like @0.2.x once you find a release that works. The project explicitly ships on an alpha cadence, so unpinned upgrades can change behavior.
4. Run a swarm. Pass a single high-level prompt: npx claude-flow swarm "build a Rust port of zoxide". The orchestrator generates a plan, spawns the agents it needs, and streams stdout from each agent into the run log.
5. Watch the SQLite memory grow. As agents finish, their outputs land in the SQLite memory file. You can open it with any SQLite client (DB Browser for SQLite, sqlite3 CLI, the VS Code extension) to inspect what each agent saw and produced.
6. Launch hive-mind mode for tightly coupled tasks. When you need agents to share state during the run rather than after, switch with npx claude-flow hive-mind start. The same registry, the same memory file, different coordination semantics.
7. Handle errors structurally. When an agent fails, the orchestrator marks it failed and routes around it. Downstream agents that depended on its output receive a structured failure they can retry, rather than the entire run aborting.

That is the entire surface area for a first successful run. There is no DAG to draw, no message bus to configure, no checkpoint store to provision.

Comparison: Where Claude-Flow Sits Among Orchestration Frameworks

Claude-Flow is one of several multi-agent orchestration approaches that have appeared since LangChain published LangGraph in early 2024 (blog.langchain.dev) and OpenAI open-sourced Swarm in October 2024 (github.com/openai/swarm). It occupies a specific niche.

The trade-off is explicit: AutoGen, CrewAI, and LangGraph give you more flexibility and provider portability, but you write more code and you reimplement the tool ecosystem Claude Code already provides. Claude-Flow gives up provider portability in exchange for using Claude Code's existing tools (file edits, bash, web fetch, MCP servers) without a second integration layer.

For TokRepo users running parallel automations on top of Claude Code, this is usually the right trade. If you also use schedulers like the Loop local recurring task scheduler or full workflow frameworks like SuperClaude, Claude-Flow plugs in alongside them rather than replacing them.

Configuration, Self-Hosting, and Versioning

Everything Claude-Flow knows about a project lives in one directory. The .claude-flow/init writes is plain text — agent profiles in Markdown, configuration in JSON or YAML, the SQLite file as a single binary. There is no cloud component, no required login, no SaaS layer.

Agents are configurable Markdown — open any profile, change the system prompt, save. The next run picks it up. Adding a new role is creating a new Markdown file with a name and a prompt; the orchestrator discovers it on the next init or run. This file-as-prompt pattern is the same one Anthropic's own subagent documentation describes for Claude Code (docs.anthropic.com/claude-code/sub-agents).

The SQLite memory file is local by default. You decide whether to commit it: committing gives you replayable runs and team-shared memory, ignoring keeps repos lean. Either choice is valid; the project takes no opinion. Pinning a version with npx claude-flow@<tag> is recommended because the project is explicitly on an alpha cadence — pin once you find a release that produces the agent topology you want. Telemetry is opt-in via environment variables, so a default install never sends data off your machine.

For teams running Claude-Flow alongside CI, pair it with subagent-style validators like the build-validator CI validation subagent and the verify-app E2E test subagent. The Claude-Flow run produces the change; the validators gate it. To track token spend across all the parallel agents, the ccusage real-time token cost tracker reads the same Claude Code session logs Claude-Flow's subprocesses write to.

When to Use Claude-Flow and When to Skip It

Reach for Claude-Flow when (a) you already use Claude Code as your daily driver, (b) the task decomposes into more than two distinct roles, and (c) you would otherwise hand-spawn subagent calls or write a LangGraph in the next hour. The 3-command setup pays for itself the first time you save the LangGraph hour.

Skip it when the task is genuinely single-role — a small refactor, a focused bug fix, a docs edit. Spawning 15 agents to fix a typo wastes tokens and adds nothing. Skip it when you need provider portability across Anthropic, OpenAI, and Google models in the same run; that is what AutoGen and LangGraph exist for. Skip it when your orchestration logic is itself the product (you are building an agent platform, not using one); a thin npm wrapper will not give you the runtime control you need.

For the in-between case — recurring automation that still benefits from role specialization — combine Claude-Flow with a scheduler. A nightly Claude-Flow swarm triggered by Loop or by a cron job, with results funneled through a CI subagent, is the highest-leverage setup most teams find on Claude Code today.