ruvnet/agentic-flow: Self-Learning AI Agent Orchestration for Claude Code

ruvnet/agentic-flow: Self-Learning AI Agent Orchestration for Claude Code

Developers using Claude Code and the Agent SDK face a familiar tension: the prototyping experience is smooth, but turning a working agent into a production deployment often means rebuilding from scratch. ruvnet/agentic-flow bridges that gap with 66 self-learning agents, 213 MCP tools, and infrastructure to deploy hosted agents in your own cloud environment. With 776 GitHub stars and 171 forks, this TypeScript project (last updated June 28, 2026) gives teams a path from Claude Code experimentation to real business deployments without abandoning the workflow they already know.

This article walks through what agentic-flow actually does, how its self-learning hooks system works, and how to get started in under 60 seconds.

What is ruvnet/agentic-flow?

ruvnet/agentic-flow is an open-source orchestration layer for AI agents built specifically for developers already comfortable with Claude Code and Anthropic's Agent SDK. The project's stated purpose: take what you've created with Claude agents and commands, then deploy fully hosted agents for production use cases.

The tool sits in a growing category of agent orchestration frameworks, but with a narrower focus than general-purpose platforms like LangChain or CrewAI. It targets developers who want to:

• Keep using Claude Code's interface for agent development
• Add self-learning capabilities that improve routing over time
• Export working agents to hosted infrastructure they control

The project is built in TypeScript (requiring Node.js 18+) and distributes via npm as agentic-flow. The README specifies an MIT license, though the repository stats list the license as "Not specified" — a minor discrepancy worth noting if you're evaluating it for enterprise use.

At its core, agentic-flow provides three integrated systems:

1. Self-learning hooks that observe development patterns and optimize agent routing
2. Background workers triggered by keywords like ultralearn, optimize, and audit
3. MCP server integration exposing 213 tools for swarm coordination, memory management, and GitHub operations

The "self-learning" aspect comes from ReasoningBank, a pattern storage system where agents record successful and failed task executions, then retrieve relevant precedents for future work. This isn't theoretical — the hooks system includes explicit pre-edit, post-edit, pre-command, and route hooks that feed the learning pipeline.

Key Features

SONA: Self-Optimizing Neural Architecture

The v2 release introduces SONA (@ruvector/sona), a sub-millisecond adaptive learning system. Documented capabilities include:

• Rank-2 Micro-LoRA for edge deployment (2211 ops/sec, <5MB footprint)
• Rank-16 Base-LoRA for quality-sensitive tasks (+55% improvement)
• EWC++ continual learning to prevent catastrophic forgetting
• LLM Router with intelligent model selection claiming 60% cost reduction ($720/month → $288/month in the documented example)

The README provides specific latency claims: <1ms learning overhead, 300x faster pattern retrieval (150ms → 0.5ms), and five configuration profiles from "Real-Time" (2200 ops/sec) to "Research" (+55% quality).

Five Attention Mechanisms

agentic-flow implements multiple attention variants for different coordination patterns:

The Flash Attention implementation claims 2.49x speedup in JavaScript^{↗ Bright Coding Blog} runtime and 7.47x with NAPI bindings, with 50-75% memory reduction.

AgentDB v3 Integration

The framework bundles AgentDB@alpha for vector and graph operations:

• HNSW indexing: 150x-12,500x speedup over brute-force search (1M vectors in 6.7ms)
• GNN query refinement: +12.4% recall improvement via 3-layer graph neural networks
• Sparse attention: 10-100x acceleration for large graphs
• WASM/NAPI binaries: 730 KB optimized builds

66 Self-Learning Agents

The agent taxonomy spans development, coordination, and operations roles:

• Core development: coder, reviewer, tester, planner, researcher
• Swarm coordination: hierarchical-coordinator, mesh-coordinator, adaptive-coordinator
• Consensus protocols: byzantine-coordinator, raft-manager, gossip-coordinator
• GitHub operations: pr-manager, code-review-swarm, issue-tracker, release-manager
• SPARC methodology: specification, pseudocode, architecture, refinement

All agents integrate with ReasoningBank for pattern learning and can use any of the five attention mechanisms for coordination.

Use Cases

1. From Claude Code Prototype to Hosted Deployment

The primary use case matches the project's origin story: a developer builds an agent workflow using Claude Code's conversational interface, then uses agentic-flow init and agentic-flow mcp start to generate deployable infrastructure. The MCP server exposes the same capabilities through a standard protocol, allowing integration with existing toolchains.

2. Intelligent Code Review Pipelines

The code-review-swarm agent and related GitHub tools enable automated PR analysis. The documented workflow spawns parallel agents for security auditing, performance analysis, style checking, and test validation — then uses attention-based consensus to synthesize findings. The README cites an 84.8% SWE-Bench solve rate for this pattern.

3. Self-Improving Documentation Systems

The ultralearn worker trigger performs deep codebase analysis in the background. When a developer asks about "how authentication works," the system extracts patterns across 42+ files, stores them in ReasoningBank, and makes them available for future routing decisions. This addresses the common problem where documentation drifts from implementation.

4. Hierarchical Multi-Agent Research

The hyperbolic attention mechanism models PI/research-assistant hierarchies. Principal investigators (queens) maintain higher influence in consensus calculations, while workers contribute findings. The curvature parameter (-1.0 in examples) controls how strongly hierarchy affects attention weights.

5. Cost-Optimized Model Routing

The LLM Router selects between Sonnet and Haiku based on quality requirements and budget constraints. For teams with variable task complexity, this provides a concrete mechanism to reduce API spend without manually tagging each request.

Installation & Setup

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• Claude Code installed and configured

Quick Start (60 seconds)

The README provides this exact sequence:

# 1. Initialize your project
npx agentic-flow init

# 2. Bootstrap intelligence from your codebase
npx agentic-flow hooks pretrain

# 3. Start Claude Code with self-learning hooks
claude

Step 1: npx agentic-flow init

This creates the .claude/ directory structure with 80+ agent definitions, 100+ slash commands, skills, and helper utilities. It also generates CLAUDE.md with project-specific instructions and settings.json with hook configurations.

The --force flag overwrites existing configurations; --minimal creates empty directories only; --verbose shows all files being written.

Step 2: npx agentic-flow hooks pretrain

Analyzes repository structure and git history (default depth: 50 commits) to bootstrap the learning system. Output includes file counts, pattern creation, memory storage, and co-edit detection. The --depth 100 option increases git history analysis.

Step 3: claude

Starts Claude Code with the generated hooks active. The settings.json configures PreToolUse, PostToolUse, SessionStart, and UserPromptSubmit hooks that call back to agentic-flow for routing and learning.

Post-Init Configuration

# Start the MCP server
npx agentic-flow mcp start

# Generate optimized agent configurations
npx agentic-flow hooks build-agents

# View learning metrics
npx agentic-flow hooks metrics

The build-agents command accepts a --focus parameter (quality, speed, security, testing, fullstack) to specialize generated configurations.

Optional: NAPI Runtime

For the claimed 3x speedup on attention operations:

npm rebuild @ruvector/attention
node -e "console.log(require('@ruvector/attention').runtime)"
# Should output: "napi"

Real Code Examples

Example 1: Basic Task Routing

This snippet from the README shows the core API:

import { AgenticFlow } from 'agentic-flow';

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

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

The AgenticFlow class encapsulates initialization, routing, and (implicitly) the learning backend. The route() method returns both the selected agent identifier and a confidence score — useful for deciding whether to proceed automatically or prompt for confirmation.

Example 2: Hook-Based Pre-Edit Context

The CLI interface for getting context before editing:

npx agentic-flow hooks pre-edit src/api/users.ts --task "Add validation"

Documented output:

🎯 Suggested Agent: backend-dev
📊 Confidence: 94.2%
📁 Related Files:
   - src/api/validation.ts
   - src/types/user.ts
⏱️  Latency: 2.3ms

This demonstrates how the hooks system integrates with file operations. The pre-edit hook searches ReasoningBank for similar past edits, identifies relevant files through co-edit patterns, and suggests the agent with highest historical success on comparable tasks.

Example 3: GNN-Enhanced Search

From the customer support use case:

import { EnhancedAgentDBWrapper } from 'agentic-flow/core';

const wrapper = new EnhancedAgentDBWrapper({
  enableAttention: true,
  enableGNN: true,
  attentionConfig: { type: 'flash' },
});

await wrapper.initialize();

const solutions = await wrapper.gnnEnhancedSearch(customerQuery, {
  k: 5,
  graphContext: knowledgeGraph,
});

The EnhancedAgentDBWrapper is the main interface to AgentDB's vector and graph capabilities. Enabling both attention and GNN triggers the +12.4% recall improvement path. The graphContext parameter accepts a knowledge graph structure that the 3-layer GNN uses for query refinement.

Example 4: Attention-Based Multi-Agent Consensus

import { AttentionCoordinator } from 'agentic-flow/coordination';

const coordinator = new AttentionCoordinator(wrapper.getAttentionService());

const response = await coordinator.coordinateAgents([
  { agentId: 'support-1', output: 'Solution A', embedding: [...] },
  { agentId: 'support-2', output: 'Solution B', embedding: [...] },
  { agentId: 'support-3', output: 'Solution C', embedding: [...] },
], 'flash');

console.log(`Best solution: ${response.consensus}`);

This shows the coordination layer in action. Multiple agents produce candidate outputs with embeddings; the coordinator applies Flash Attention to compute consensus. The mechanism parameter ('flash') selects the attention variant, with alternatives including 'multi-head', 'linear', 'hyperbolic', 'moe', and 'graphrope'.

Advanced Usage & Best Practices

Managing the Learning Rate

The AGENTIC_FLOW_LEARNING_RATE environment variable (default 0.1) controls how aggressively the system updates Q-values for agent routing. For stable production environments, consider reducing this to reduce exploration noise. For active development periods, increasing it may accelerate pattern acquisition.

Exploration vs. Exploitation

The AGENTIC_FLOW_EPSILON parameter (default 0.1) implements ε-greedy exploration. At 0.1, 10% of routings randomly explore non-optimal agents to discover potentially better strategies. Set to 0.0 for deterministic routing in production; increase temporarily when adding new agent types.

Memory Backend Selection

Three backends are documented:

• agentdb: Full vector + graph capabilities, highest performance
• sqlite: Portable, no additional services
• memory: Ephemeral, for testing only

The default agentdb requires the WASM/NAPI binaries. If you encounter build issues, sqlite provides a fallback with reduced search performance.

Worker Keyword Discipline

The background workers system responds to trigger keywords anywhere in prompts. Be precise: ultralearn how caching works launches deep analysis, but casual mentions in unrelated prompts may spawn unintended workers. The workers status command monitors active workers; workers cleanup --age 24 removes stale entries.

Trajectory Tracking for RL

For reinforcement learning applications, explicitly track trajectories:

npx agentic-flow hooks intel trajectory-start "Implement OAuth" -a coder
# ... perform steps ...
npx agentic-flow hooks intel trajectory-step 42 -a "edit file" -r 0.8
npx agentic-flow hooks intel trajectory-end 42 --success --quality 0.95

This feeds the EWC++ consolidation process that prevents catastrophic forgetting across task types.

Comparison with Alternatives

Trade-offs to consider:

• LangChain offers broader ecosystem integration and language model flexibility, but lacks the Claude Code-specific hooks and pre-built agent library. Teams not using Claude Code will find agentic-flow's assumptions less aligned.

• CrewAI provides simpler task delegation patterns for Python-centric teams, but doesn't include the vector search infrastructure or attention-based coordination mechanisms. The learning system is less explicit.

• agentic-flow excels when your team already uses Claude Code, wants to preserve that workflow, and needs the specific performance optimizations (Flash Attention, HNSW indexing) for large-scale agent coordination. The TypeScript requirement and Node.js ecosystem may exclude Python-heavy ML pipelines.

FAQ

Q: Is the MIT license confirmed? The README badge shows MIT, but repository metadata lists "Not specified." Verify the actual LICENSE file before enterprise adoption.

Q: Does this replace Claude Code? No — it extends Claude Code with deployable infrastructure and learning capabilities. You still need Claude Code installed.

Q: What's the actual performance overhead? The README claims <1ms for routing and <0.1ms for attention operations, but your mileage varies with repository size and HNSW index complexity.

Q: Can I use this without Claude Code? The MCP server and programmatic API work independently, but the hooks system and quick-start path assume Claude Code integration.

Q: How do the 60% cost savings work? The LLM Router selects cheaper models (Haiku vs. Sonnet) for tasks where quality requirements permit. Actual savings depend on your task distribution.

Q: Is v2 production-ready? The README states "Production-ready" and "Grade A+," but the npm tag is @alpha and AgentDB is v3.0.0-alpha.6. Evaluate stability for your risk tolerance.

Q: What happens to learned patterns when I switch projects? The hooks transfer command moves patterns between projects with confidence thresholds and mode selection (merge, replace, additive).

Conclusion

ruvnet/agentic-flow occupies a specific niche: developers who've built something useful in Claude Code and need a credible path to production deployment without rewriting everything. The 66 pre-built agents, 213 MCP tools, and explicit self-learning infrastructure reduce the gap between prototype and production more than generic frameworks that don't assume the Claude ecosystem.

The technical claims are extensive — sub-millisecond attention, 150x vector search speedup, 60% cost reduction — and the README provides enough benchmark detail to validate them independently. The alpha versioning and "Not specified" license metadata suggest the project is still maturing, but the active development (last commit June 2026) and 776-star community indicate sustained interest.

Best suited for: Teams already invested in Claude Code, TypeScript/Node.js environments, and use cases requiring explicit multi-agent coordination with learning capabilities.

Get started: https://github.com/ruvnet/agentic-flow

For teams evaluating broader agent orchestration strategies, see our comparison of [INTERNAL_LINK: ai-agent-frameworks-2024] for additional context on the ecosystem.