agentic-flow: Model Switching and Swarm Orchestration for Claude Code

What agentic-flow adds on top of Claude Code

Claude Code works well as a single-agent coding assistant, but it does not ship a router that picks a cheaper model per task, a background worker queue, or a persistent memory of past runs. agentic-flow is positioned as that layer. The README describes it as "Production-ready AI agent orchestration with 66 self-learning agents, 213 MCP tools, and autonomous multi-agent swarms", and the repository description frames the same idea around cost: switch between alternative low-cost AI models in Claude Code and the Agent SDK, then deploy the result as a hosted agent.

The target reader is someone who already writes Claude agents and commands and wants two things: to keep the authoring experience in Claude Code, and to hand the finished agent to a cloud runtime. The topics list (agents, claude, claude-agent-sdk, claude-code, gemini, openrouter, swarm-intelligence) confirms that the project sits between the Claude tooling and alternative model providers rather than replacing either.

Where the framing gets loose is the agent count. The README headline says 66 self-learning agents, the Quick Start bullet says "80+ specialized agents", and the package.json description says 66 again. That is a documentation inconsistency, not a functional one, but it means you should check what is actually installed rather than trust the badge.

The mechanism: hooks, routing, workers and an MCP server

The architecture visible in the README is a CLI that writes project state, plus a library you can import. `npx agentic-flow init` sets up a project; `npx agentic-flow hooks pretrain` bootstraps what the README calls intelligence from your codebase; then `claude` starts Claude Code with the hooks attached. The learning loop is the hook layer: as tasks are routed, the router is supposed to improve which agent gets picked.

Routing is exposed both as a command and as a method. The README shows `npx agentic-flow hooks route "implement user authentication"` on the CLI side and an `AgenticFlow` class with `initialize()` and `route()` on the library side, returning an agent name and a confidence value. Background work is separate: `npx agentic-flow workers dispatch "ultralearn how caching works"` pushes a keyword-triggered job into a worker pool. The README lists ultralearn, optimize and audit as example worker keywords, which implies the trigger is textual rather than a formal job schema.

Underneath, the README points at three named subsystems. SONA (@ruvector/sona) is described as the adaptive learning component with sub-millisecond pattern learning. AgentDB v3.0.0-alpha.6 supplies the vector and graph memory, including sparse attention and graph partitioning. ReasoningBank provides cross-run memory of successes and failures. The repository layout supports this: there are top-level `reasoningbank/`, `crates/`, `packages/` and `agentic-flow/` directories, plus an `agentdb.db-shm` file at the root, which is a SQLite shared-memory file and suggests the default store is local and file-backed rather than a hosted service.

One design choice worth flagging: the package exports map exposes many subpaths (`./wrappers/gnn`, `./wrappers/attention`, `./router`, `./reasoningbank/wasm-adapter`, and so on). That is a lot of public surface for a project whose version string is still an alpha. Deep imports into attention or GNN wrappers are the kind of thing that breaks between minor releases.

Installing agentic-flow and routing your first task

The README gives a 60-second path. It assumes Node.js 18 or later, per the badge, and it runs through npx so nothing is installed globally. The first command initialises the project and writes whatever configuration the CLI needs.

npx agentic-flow init

After that, the README bootstraps the learning layer from your existing codebase. This is the step that reads your repository, so it is the one to run on a branch rather than on a working tree you care about.

npx agentic-flow hooks pretrain

With the hooks in place, start Claude Code as usual. The README does not show any extra flag here, which is the point: the hooks attach to the existing session.

claude

To see routing without going through the editor, call the router directly. The README's example is a plain task description, and the output is the chosen agent plus a confidence figure.

npx agentic-flow hooks route "implement user authentication"

If you would rather call it from your own code, the README's TypeScript example is short. Note the package is ESM (`"type": "module"` in package.json), so this belongs in an ES module context.

import { AgenticFlow } from 'agentic-flow';

const flow = new AgenticFlow();
await flow.initialize();

const result = await flow.route('Fix the login bug');
console.log(`Best agent: ${result.agent} (${result.confidence}% confidence)`);

After a few routed tasks, `npx agentic-flow hooks metrics` prints the learning counters. If those counters stay at zero, the hooks are not observing your session, and that is the first thing to debug before trusting any routing output.

Where agentic-flow is the wrong tool

The learning layer is the selling point and also the main risk. A router that adapts to your repository is only as good as its feedback signal, and the README does not explain how success is judged. `hooks route` returns a confidence number, but nothing in the README says what that number is calibrated against or how to override a bad choice. If you need deterministic task dispatch, a hand-written mapping from task type to model is easier to reason about than a learned one.

The project is also alpha software wearing production language. The README headline says "Production-ready", while the repository's package.json declares version 2.0.2-alpha and the release list stops at v2.3.6 in November 2025. The last push to the default branch was on 2026-07-30, so the repository is not archived and has seen recent activity, but the version strings across README, package.json and npm releases do not agree with each other. Treat any specific performance figure in the README (the sub-millisecond learning overhead, the 60% cost savings, the 2211 ops/sec throughput) as a claim from the project, not as a measurement you can rely on.

Finally, the licence is unresolved. The README carries an MIT badge, but the repository's top-level file listing does not include a LICENSE file, and the project metadata records the licence as unknown. That is a gap you should close before shipping anything built on it.

agentic-flow compared with a plain Claude Code setup

The honest alternative is not another orchestration framework; it is using Claude Code on its own with a handful of custom commands. That setup has no router, no worker queue and no cross-session memory, but it also has no pretraining step, no local database file, and no dependency on an alpha package. Every routing decision is one you made yourself.

The difference in approach is where the intelligence lives. A plain Claude Code setup keeps it in the prompt and in your commands. agentic-flow moves it into a persistent store, with ReasoningBank recording outcomes and the router consulting that store on the next task. That trade only pays off if you run enough tasks for the pattern to be worth learning. For a repository where you open Claude Code a few times a week, the pretraining and metrics overhead buys you very little.

The second real alternative is a general agent framework where you build the loop yourself. Those give you explicit control over model selection and state, at the cost of writing the routing and memory code that agentic-flow ships. If your requirement is a specific model mix (the topics list mentions gemini and openrouter alongside Claude), check whether the router in agentic-flow exposes that mix in configuration before you assume it does; the README does not document the provider configuration keys.

Maintenance, upgrades and licence questions to settle

The repository was last pushed on 2026-07-30, which is recent, and it is not archived. The release history, however, ends at v2.3.6 on 2025-11-24, so the cadence you should plan for is unclear: there is code activity without a matching release tag in the README's release list.

Upgrade cost is driven by the export surface. Because package.json exposes deep subpaths such as `./wrappers/attention`, `./wrappers/gnn` and `./reasoningbank/wasm-adapter`, an import that reaches into those modules is tied to the internal layout. Pin the version in your lockfile and read the changelog before bumping. The `type: "module"` setting also means the package is ESM-only, which matters if the rest of your toolchain is CommonJS.

On licensing, the README badge says MIT, but the repository root listing has no LICENSE file and the project metadata records the licence as unknown. I am not giving legal advice; the concrete step is to confirm the licence text in the repository before you depend on it, especially if you intend to deploy hosted agents for business use, which is exactly the scenario the repository description advertises.

Editorial conclusion

Adopt agentic-flow if you already run Claude Code and want to try routing tasks to cheaper models or adding a learning layer without replacing your editor workflow. Do not adopt it if you need a documented, stable API surface: the package.json still reads 2.0.2-alpha while the README describes v2 features, and no LICENSE file appears in the repository root listing. Before committing, run npx agentic-flow init on a throwaway branch, then npx agentic-flow hooks metrics after a few routed tasks to see whether the learning layer records anything you can act on.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. ruvnet/agentic-flow on GitHub