agentic-flow

Agentic-Flow v2

Production-ready AI agent orchestration with 66 self-learning agents, 213 MCP tools, and autonomous multi-agent swarms.

---

⚡ Quick Start (60 seconds)

# 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

That's it! Your project now has:

• Self-learning hooks that improve agent routing over time
• 80+ specialized agents (coder, tester, reviewer, architect, etc.)
• ⚡ Background workers triggered by keywords (ultralearn, optimize, audit)
• 213 MCP tools for swarm coordination

Common Commands

# Route a task to the optimal agent
npx agentic-flow hooks route "implement user authentication"

# View learning metrics
npx agentic-flow hooks metrics

# Dispatch background workers
npx agentic-flow workers dispatch "ultralearn how caching works"

# Run MCP server for Claude Code
npx agentic-flow mcp start

Use in Code

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)`);

---

What's New in v2

SONA: Self-Optimizing Neural Architecture

Agentic-Flow v2 now includes SONA (@ruvector/sona) for sub-millisecond adaptive learning:

• +55% Quality Improvement: Research profile with LoRA fine-tuning
• ⚡ **2048 tokens)
• 2048 tokens) const paperAnalysis = await wrapper.linearAttention( queryEmbedding, paperSectionEmbeddings, paperSectionEmbeddings );

// GNN-enhanced citation network search const relatedPapers = await wrapper.gnnEnhancedSearch(paperEmbedding, { k: 20, graphContext: { nodes: allPaperEmbeddings, edges: citationLinks, edgeWeights: citationCounts, }, });

console.log(Found ${relatedPapers.results.length} related papers); console.log(Recall improved by ${relatedPapers.improvementPercent}%);

**Benefits**:
- O(n) complexity for long documents
- +12.4% better citation discovery
- Graph-aware literature search
- Handles papers with 10,000+ tokens

#### 2. **Multi-Agent Research Collaboration**

```typescript
// Create hierarchical research swarm
const researchCoordinator = new AttentionCoordinator(
  wrapper.getAttentionService()
);

// Queens: Principal investigators
const piOutputs = [
  { agentId: 'pi-1', output: 'Hypothesis A', embedding: [...] },
  { agentId: 'pi-2', output: 'Hypothesis B', embedding: [...] },
];

// Workers: Research assistants
const raOutputs = [
  { agentId: 'ra-1', output: 'Finding 1', embedding: [...] },
  { agentId: 'ra-2', output: 'Finding 2', embedding: [...] },
  { agentId: 'ra-3', output: 'Finding 3', embedding: [...] },
];

// Use hyperbolic attention for hierarchy
const consensus = await researchCoordinator.hierarchicalCoordination(
  piOutputs,
  raOutputs,
  -1.0 // hyperbolic curvature
);

console.log(`Research consensus: ${consensus.consensus}`);
console.log(`Top contributors: ${consensus.topAgents.map(a => a.agentId)}`);

Benefits:

• Models hierarchical research structures
• Queens (PIs) have higher influence
• Better consensus than simple voting
• Hyperbolic attention for expertise levels

3. Experimental Data Analysis

// Use attention-based multi-agent analysis
const dataAnalysisAgents = [
  { agentId: 'statistician', output: 'p 80% success)
});

// Apply lessons from past successes
similarTasks.forEach(pattern => {
  console.log(`Past solution: ${pattern.task}`);
  console.log(`Success rate: ${pattern.reward}`);
  console.log(`Key learnings: ${pattern.critique}`);
});

// Avoid past mistakes
const failures = await reasoningBank.searchPatterns({
  task: 'Implement user authentication',
  onlyFailures: true // Learn from failures
});

2️⃣ During Task: Enhanced Context Retrieval

// Use GNN for +12.4% better context accuracy
const relevantContext = await agentDB.gnnEnhancedSearch(
  taskEmbedding,
  {
    k: 10,
    graphContext: buildCodeGraph(), // Related code as graph
    gnnLayers: 3
  }
);

console.log(`Context accuracy improved by ${relevantContext.improvementPercent}%`);

// Process large contexts 2.49x-7.47x faster
const result = await agentDB.flashAttention(Q, K, V);
console.log(`Processed in ${result.executionTimeMs}ms`);

3️⃣ After Task: Store Learning Patterns

// Agents automatically store every task execution
await reasoningBank.storePattern({
  sessionId: `coder-${agentId}-${Date.now()}`,
  task: 'Implement user authentication',
  input: 'Requirements: OAuth2, JWT tokens, rate limiting',
  output: generatedCode,
  reward: 0.95,      // Success score (0-1)
  success: true,
  critique: 'Good test coverage, could improve error messages',
  tokensUsed: 15000,
  latencyMs: 2300
});

Performance Improvement Over Time

Agents continuously improve through iterative learning:

Iterations	Success Rate	Accuracy	Speed	Tokens
1-5	70%	Baseline	Baseline	100%
6-10	82% (+12%)	+8.5%	+15%	-18%
11-20	91% (+21%)	+15.2%	+32%	-29%
21-50	98% (+28%)	+21.8%	+48%	-35%

Agent-Specific Learning Examples

Coder Agent - Learns Code Patterns

// Before: Search for similar implementations
const codePatterns = await reasoningBank.searchPatterns({
  task: 'Implement REST API endpoint',
  k: 5
});

// During: Use GNN to find related code
const similarCode = await agentDB.gnnEnhancedSearch(
  taskEmbedding,
  { k: 10, graphContext: buildCodeDependencyGraph() }
);

// After: Store successful pattern
await reasoningBank.storePattern({
  task: 'Implement REST API endpoint',
  output: generatedCode,
  reward: calculateCodeQuality(generatedCode),
  success: allTestsPassed
});

Researcher Agent - Learns Research Strategies

// Enhanced research with GNN (+12.4% better)
const relevantDocs = await agentDB.gnnEnhancedSearch(
  researchQuery,
  { k: 20, graphContext: buildKnowledgeGraph() }
);

// Multi-source synthesis with attention
const synthesis = await coordinator.coordinateAgents(
  researchFindings,
  'multi-head' // Multi-perspective analysis
);

Tester Agent - Learns from Test Failures

// Learn from past test failures
const failedTests = await reasoningBank.searchPatterns({
  task: 'Test authentication',
  onlyFailures: true
});

// Generate comprehensive tests with Flash Attention
const testCases = await agentDB.flashAttention(
  featureEmbedding,
  edgeCaseEmbeddings,
  edgeCaseEmbeddings
);

Coordination & Consensus Learning

Agents learn to work together more effectively:

// Attention-based consensus (better than voting)
const coordinator = new AttentionCoordinator(attentionService);

const teamDecision = await coordinator.coordinateAgents([
  { agentId: 'coder', output: 'Approach A', embedding: embed1 },
  { agentId: 'reviewer', output: 'Approach B', embedding: embed2 },
  { agentId: 'architect', output: 'Approach C', embedding: embed3 },
], 'flash');

console.log(`Team consensus: ${teamDecision.consensus}`);
console.log(`Confidence: ${teamDecision.attentionWeights.max()}`);

Cross-Agent Knowledge Sharing

All agents share learning patterns via ReasoningBank:

// Agent 1: Coder stores successful pattern
await reasoningBank.storePattern({
  task: 'Implement caching layer',
  output: redisImplementation,
  reward: 0.92
});

// Agent 2: Different coder retrieves the pattern
const cachedSolutions = await reasoningBank.searchPatterns({
  task: 'Implement caching layer',
  k: 3
});
// Learns from Agent 1's successful approach

Continuous Improvement Metrics

Track learning progress:

// Get performance stats for a task type
const stats = await reasoningBank.getPatternStats({
  task: 'implement-rest-api',
  k: 20
});

console.log(`Success rate: ${stats.successRate}%`);
console.log(`Average reward: ${stats.avgReward}`);
console.log(`Improvement trend: ${stats.improvementTrend}`);
console.log(`Common critiques: ${stats.commonCritiques}`);

---

Project Initialization (init)

The init command sets up your project with the full Agentic-Flow infrastructure, including Claude Code integration, hooks, agents, and skills.

Quick Init

# Initialize project with full agent library
npx agentic-flow@alpha init

# Force reinitialize (overwrite existing)
npx agentic-flow@alpha init --force

# Minimal setup (empty directories only)
npx agentic-flow@alpha init --minimal

# Verbose output showing all files
npx agentic-flow@alpha init --verbose

What Gets Created

.claude/
├── settings.json      # Claude Code settings (hooks, agents, skills, statusline)
├── statusline.sh      # Custom statusline (model, tokens, cost, swarm status)
├── agents/            # 80+ agent definitions (coder, tester, reviewer, etc.)
├── commands/          # 100+ slash commands (swarm, github, sparc, etc.)
├── skills/            # Custom skills and workflows
└── helpers/           # Helper utilities
CLAUDE.md              # Project instructions for Claude

settings.json Structure

The generated settings.json includes:

{
  "model": "claude-sonnet-4-20250514",
  "env": {
    "AGENTIC_FLOW_INTELLIGENCE": "true",
    "AGENTIC_FLOW_LEARNING_RATE": "0.1",
    "AGENTIC_FLOW_MEMORY_BACKEND": "agentdb"
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...],
    "UserPromptSubmit": [...]
  },
  "permissions": {
    "allow": ["Bash(npx:*)", "mcp__agentic-flow", "mcp__claude-flow"]
  },
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh"
  },
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["agentic-flow@alpha", "mcp", "start"]
    }
  }
}

Post-Init Steps

After initialization:

# 1. Start the MCP server
npx agentic-flow@alpha mcp start

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

# 3. Generate optimized agent configurations
npx agentic-flow@alpha hooks build-agents

# 4. Start using Claude Code
claude

…

bash
npx agentic-flow@alpha hooks pre-edit  [options]

Options:
  -t, --task    Task description
  -j, --json          Output as JSON

# Example
npx agentic-flow@alpha hooks pre-edit src/api/users.ts --task "Add validation"
# Output:
#  Suggested Agent: backend-dev
#  Confidence: 94.2%
#  Related Files:
#    - src/api/validation.ts
#    - src/types/user.ts
# ⏱️  Latency: 2.3ms

Post-Edit Hook

Record edit outcome for learning:

npx agentic-flow@alpha hooks post-edit  [options]

Options:
  -s, --success           Mark as successful edit
  -f, --fail              Mark as failed edit
  -a, --agent      Agent that performed the edit
  -d, --duration      Edit duration in milliseconds
  -e, --error    Error message if failed
  -j, --json              Output as JSON

# Example (success)
npx agentic-flow@alpha hooks post-edit src/api/users.ts --success --agent coder

# Example (failure)
npx agentic-flow@alpha hooks post-edit src/api/users.ts --fail --error "Type error"

Pre-Command Hook

Assess command risk before execution:

npx agentic-flow@alpha hooks pre-command "" [options]

Options:
  -j, --json    Output as JSON

# Example
npx agentic-flow@alpha hooks pre-command "rm -rf node_modules"
# Output:
# ⚠️ Risk Level: CAUTION (65%)
# ✅ Command APPROVED
#  Suggestions:
#    - Consider using npm ci instead for cleaner reinstall

Route Hook

Route task to optimal agent using learned patterns:

npx agentic-flow@alpha hooks route "" [options]

Options:
  -f, --file    Context file path
  -e