@hanzo/dev

State-of-the-art AI development platform with swarm intelligence

@hanzo/dev is an advanced AI development platform that orchestrates multiple AI agents working in parallel. Built with swarm intelligence and Model Context Protocol (MCP) at its core, it achieves industry-leading performance on software engineering benchmarks.

Features

• 🤖 Multi-AI Support: Integrate with Claude, OpenAI, Gemini, and local AI models
• 🔧 Tool Unification: Single interface for all AI coding assistants
• 🌐 MCP Integration: Full Model Context Protocol support for extensible tools
• 👥 Peer Agent Networks: Spawn multiple agents that collaborate via MCP
• 🎯 CodeAct Agent: Automatic planning, execution, and self-correction
• 🌍 Browser Automation: Control browsers via Hanzo Browser/Extension
• 📝 Advanced Editing: File manipulation with undo, chunk localization
• 🚀 Parallel Execution: Run multiple tasks concurrently across agents
• 🔍 SWE-bench Ready: Optimized for software engineering benchmarks

Installation

npm install -g @hanzo/dev

Or use directly with npx:

npx @hanzo/dev

Quick Start

Interactive Mode

dev

This launches an interactive menu where you can:

• Select your preferred AI tool
• Configure API keys
• Access specialized commands

Direct Tool Access

# Launch with specific AI provider
dev --claude
dev --openai
dev --gemini
dev --grok
dev --local

# Advanced modes
dev --workspace    # Unified workspace mode
dev --benchmark    # Run SWE-bench evaluation

# Swarm mode - edit multiple files in parallel
dev --claude --swarm 5 -p "Add copyright header to all files"
dev --openai --swarm 10 -p "Fix all ESLint errors"
dev --gemini --swarm 20 -p "Add JSDoc comments to all functions"
dev --local --swarm 100 -p "Format all files with prettier"

Environment Configuration

Create a .env file in your project root:

# API Keys
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here
TOGETHER_API_KEY=your_key_here

# Local AI
HANZO_APP_URL=http://localhost:8080
LOCAL_LLM_URL=http://localhost:11434

# Browser Integration
HANZO_BROWSER_URL=http://localhost:9223
HANZO_EXTENSION_WS=ws://localhost:9222

Advanced Features

Swarm Mode

Launch multiple agents to edit files in parallel across your codebase:

# Basic swarm usage
dev --claude --swarm 5 -p "Add copyright header to all files"

# Process specific file types
dev --openai --swarm 20 -p "Add type annotations" --pattern "**/*.ts"

# Maximum parallelism (up to 100 agents)
dev --gemini --swarm 100 -p "Fix linting errors"

# Using local provider for cost efficiency
dev --local --swarm 50 -p "Format with prettier"

Features:

• Lazy agent spawning: Agents are created as needed, not all at once
• Automatic authentication: Handles provider login if API keys are available
• Parallel execution: Each agent processes a different file simultaneously
• Smart file detection: Automatically finds all editable files in your project
• Progress tracking: Real-time status updates as files are processed

Example: Adding copyright headers to 5 files in parallel:

# Navigate to your test directory
cd test-swarm

# Run swarm with Claude
dev --claude --swarm 5 -p "Add copyright header '// Copyright 2025 Hanzo Industries Inc.' at the top of each file"

The swarm will:

1. Find all editable files in the directory
2. Spawn up to 5 Claude agents
3. Assign each agent a file to process
4. Execute edits in parallel
5. Report results when complete

Supported providers:

• --claude: Claude AI (requires ANTHROPIC_API_KEY or claude login)
• --openai: OpenAI GPT (requires OPENAI_API_KEY)
• --gemini: Google Gemini (requires GOOGLE_API_KEY)
• --grok: Grok AI (requires GROK_API_KEY)
• --local: Local Hanzo agent (no API key required)

Workspace Mode

Open a unified workspace with all tools available:

dev workspace

Features:

• Integrated shell, editor, browser, and planner
• Persistent session state
• Tool switching without context loss
• Unified command interface

MCP Server Configuration

Configure MCP servers in .mcp.json:

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": { "MCP_ALLOWED_PATHS": "." }
    },
    {
      "name": "git",  
      "command": "npx",
      "args": ["@modelcontextprotocol/server-git"]
    },
    {
      "name": "custom",
      "command": "python",
      "args": ["my-mcp-server.py"],
      "transport": "stdio"
    }
  ]
}

Architecture

Core Components

1. Editor Module (lib/editor.ts)

   • View, create, and edit files
   • String replacement with validation
   • Chunk localization for large files
   • Undo/redo functionality

2. MCP Client (lib/mcp-client.ts)

   • Stdio and WebSocket transports
   • Dynamic tool discovery
   • Session management
   • JSON-RPC protocol

3. CodeAct Agent (lib/code-act-agent.ts)

   • Automatic task planning
   • Parallel step execution
   • Self-correction with retries
   • State and observation tracking

4. Peer Agent Network (lib/peer-agent-network.ts)

   • Agent spawning strategies
   • Inter-agent communication
   • MCP tool exposure
   • Swarm optimization

5. Agent Loop (lib/agent-loop.ts)

   • LLM provider abstraction
   • Browser automation
   • Tool orchestration
   • Execution management

API Usage

Programmatic Access

import { CodeActAgent, PeerAgentNetwork, ConfigurableAgentLoop } from '@hanzo/dev';

// Create an agent
const agent = new CodeActAgent('my-agent', functionCallingSystem);
await agent.plan('Fix the login bug');
const result = await agent.execute();

// Create a peer network
const network = new PeerAgentNetwork();
await network.spawnAgentsForCodebase('./src', 'claude-code', 'one-per-file');

// Configure agent loop
const loop = new ConfigurableAgentLoop({
  provider: {
    name: 'Claude',
    type: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY,
    model: 'claude-3-opus-20240229',
    supportsTools: true,
    supportsStreaming: true
  },
  maxIterations: 10,
  enableMCP: true,
  enableBrowser: true,
  enableSwarm: true
});

await loop.initialize();
await loop.execute('Refactor the authentication module');

Custom Tool Registration

import { FunctionCallingSystem } from '@hanzo/dev';

const functionCalling = new FunctionCallingSystem();

// Register custom tool
functionCalling.registerTool({
  name: 'my_custom_tool',
  description: 'Does something special',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Tool input' }
    },
    required: ['input']
  },
  handler: async (args) => {
    // Tool implementation
    return { success: true, result: `Processed: ${args.input}` };
  }
});

Performance & Benchmarks

SWE-bench Results

Our platform is continuously evaluated on the Software Engineering Benchmark:

Metric	Score	Details
Success Rate	15%+	Solving real GitHub issues
Avg Resolution Time	90s	Per task completion
Cost Efficiency	$0.10/task	Using swarm optimization
Parallel Speedup	4.2x	With 5-agent swarm

Running Benchmarks

# Run full SWE-bench evaluation
dev --benchmark swe-bench

# Run on specific dataset
dev --benchmark swe-bench --dataset lite

# Custom benchmark configuration
dev --benchmark swe-bench \
  --agents 10 \
  --parallel \
  --timeout 300 \
  --output results.json

Performance Optimizations

1. Swarm Intelligence: Multiple agents work on different aspects simultaneously
2. Local Orchestration: Hanzo Zen manages coordination locally, reducing API calls
3. Smart Caching: MCP tools cache results across agents
4. Parallel Execution: CodeAct identifies independent steps and runs them concurrently

Testing

# Run all tests
npm test

# Run specific test suite
npm run test:swe-bench

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/hanzoai/dev.git
cd dev/packages/dev

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

License

MIT © Hanzo AI

Acknowledgments

Built by Hanzo AI - Advancing AI infrastructure for developers worldwide.