Skip to content
View obeskay's full-sized avatar

Block or report obeskay

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Maximum 250 characters. Please don't include any personal information such as legal names or email addresses. Markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this userโ€™s behavior. Learn more about reporting abuse.

Report abuse
obeskay/README.md

๐Ÿ SwarmVille - AI Agent Coordination Framework

Turn parallel execution into synchronized teamwork for your AI agents

npm version Node.js version TypeScript License Build Status

๐ŸŽฏ The Problem with Multi-Agent Systems

Most "multi-agent" frameworks are just glorified task runners. They execute agents in parallel, but that's not coordination. Real teamwork means:

  • Communication: Agents talking to each other, not just to the orchestrator
  • Knowledge Sharing: Building on each other's work instead of starting from scratch
  • Conflict Avoidance: Smart task distribution and duplicate prevention
  • Collective Learning: Agents improving based on team performance

SwarmVille provides the coordination layer that turns a group of AI agents into a real team.

โœจ Key Features

๐Ÿ—ฃ๏ธ Agent Communication Network

// Agents can communicate directly with each other
const weatherAgent = new Agent({
  name: 'weather-expert',
  capabilities: ['weather-api', 'forecasting'],
  communication: {
    publish: ['weather-updates', 'storm-alerts'],
    subscribe: ['location-data', 'user-preferences']
  }
});

const notificationAgent = new Agent({
  name: 'notification-service',
  capabilities: ['push-notifications', 'email'],
  communication: {
    subscribe: ['storm-alerts'],
    publish: ['notification-sent']
  }
});

๐Ÿค Task Coordination

  • Smart Allocation: Assigns tasks based on agent capabilities and availability
  • Conflict Resolution: Prevents duplicate work and priority clashes
  • Progress Tracking: Real-time updates on task completion across the swarm

๐Ÿง  Shared State Management

  • Global State: Shared knowledge base accessible to all agents
  • Local State: Agent-specific private state when needed
  • State Persistence: Automatic backup and recovery mechanisms

๐Ÿ”„ Result Broadcasting

// Agents can publish results for others to consume
const researcher = new Agent({
  name: 'market-researcher',
  onResult: (data) => {
    swarm.broadcast('market-insights', data);
  }
});

const strategist = new Agent({
  name: 'business-strategist',
  onEvent: (event) => {
    if (event.type === 'market-insights') {
      // Build strategy based on fresh research
      this.executeStrategy(event.data);
    }
  }
});

๐Ÿš€ Quick Start

Installation

npm install swarm-ville
# or
yarn add swarm-ville

Hello Swarm

import { Swarm, Agent } from 'swarm-ville';

// Create agents with different capabilities
const contentWriter = new Agent({
  name: 'content-writer',
  capabilities: ['writing', 'research'],
  instructions: 'Create engaging blog posts about technology'
});

const seoExpert = new Agent({
  name: 'seo-optimizer',
  capabilities: ['seo', 'keyword-research'],
  instructions: 'Optimize content for search engines'
});

const socialMedia = new Agent({
  name: 'social-manager',
  capabilities: ['content-sharing', 'community-engagement'],
  instructions: 'Share content across social platforms'
});

// Create and start the swarm
const swarm = new Swarm([contentWriter, seoExpert, socialMedia]);

// Execute a coordinated task
await swarm.execute('create-and-promote-tech-blog-post');

// Monitor progress
swarm.on('task-completed', (result) => {
  console.log('Swarm completed task:', result.summary);
  console.log('Content created:', result.content.length, 'words');
  console.log('SEO score:', result.seo.score);
  console.log('Social posts:', result.social.platforms.length);
});

Advanced Coordination

// Define task dependencies
const developmentSwarm = new Swarm([
  new Agent({ name: 'frontend-dev', capabilities: ['react', 'typescript'] }),
  new Agent({ name: 'backend-dev', capabilities: ['node', 'mongodb'] }),
  new Agent({ name: 'tester', capabilities: ['testing', 'e2e'] })
], {
  coordination: {
    dependencies: {
      'build-frontend': [],
      'build-backend': [],
      'integration-test': ['build-frontend', 'build-backend']
    }
  }
});

await developmentSwarm.execute('feature-release');

๐Ÿ“š Documentation

๐Ÿงช Examples

Check out the examples/ directory for real-world use cases:

  • Content Creation Pipeline: Multiple agents working together to create, optimize, and distribute content
  • E-commerce Product Launch: Coordinated efforts from research to marketing
  • Bug Resolution Team: Developers, testers, and documentation specialists working in sync

๐Ÿ”ง Contributing

I built SwarmVille because I was tired of seeing AI agents work like isolated contractors instead of a cohesive team. If you share this vision, I'd love your help!

How to Contribute

  1. Report Bugs: Open an issue with reproduction steps and expected behavior
  2. Feature Requests: Tell me what coordination features you need
  3. Code Contributions: Pull requests are welcome! Please check the guidelines below
  4. Documentation: Help make SwarmVille easier to use for everyone

Development Setup

# Clone the repository
git clone https://github.com/obeskay/swarm-ville.git
cd swarm-ville

# Install dependencies
npm install

# Run tests
npm test

# Run linting
npm run lint

# Build the project
npm run build

Before Contributing

  • Read the Contributing Guidelines
  • Check that there isn't already an issue for your feature/bug
  • Keep code changes focused and well-tested
  • Update documentation for any new features

๐Ÿค Community

  • Discord: Join our community for real-time discussions
  • GitHub Discussions: Ask questions and share ideas
  • Twitter: Follow @obeskay for updates

๐Ÿ“Š Project Stats

Platform Language Code Style Testing

๐Ÿ™ Acknowledgments

Built with inspiration from:

  • The need for better AI coordination in the industry
  • Open source contributors who taught me everything
  • Everyone who's ever yelled "Why aren't these agents talking to each other?!"

๐Ÿ“„ License

MIT License - see LICENSE for details.


Made with โค๏ธ by Omar Beskay. Because the future of AI is collaboration, not competition.

Pinned Loading

  1. n8n-ai-workflows n8n-ai-workflows Public

    AI workflow automation and integration patterns - practical conversational AI implementations

    Shell

  2. cursor-talk-to-figma-mcp cursor-talk-to-figma-mcp Public

    Forked from grab/cursor-talk-to-figma-mcp

    Cursor Talk To Figma MCP

    JavaScript

  3. shotgun_code shotgun_code Public

    Forked from glebkudr/shotgun_code

    Oneโ€‘click codebase โ€œblastโ€ for Largeโ€‘Languageโ€‘Model workflows.

    Vue

  4. mac-disk-monitor mac-disk-monitor Public

    macOS menu bar disk space monitor with 3 working versions - Swift native, Python autopilot, and simple monitor

    Python