Agent Orchestration

🚀 Agent Orchestration

A Model Context Protocol (MCP) server that enables multiple AI agents to share memory, coordinate tasks, and collaborate effectively across IDEs and CLI tools.

🚀 Quick Start

No installation required! Just use npx:

For Any IDE/CLI (AGENTS.md)

# Navigate to your project
cd /path/to/your/project

# Initialize with AGENTS.md
npx agent-orchestration init

This creates AGENTS.md with full orchestration instructions that work with any AI coding agent.

For Cursor IDE

# Navigate to your project
cd /path/to/your/project

# Initialize for Cursor (copies .cursor/rules/)
npx agent-orchestration init-cursor

This copies .cursor/rules/ with Cursor-specific rules.

✨ Features

The Problem

When running multiple AI agents, they face critical coordination challenges:

1. No Turn Awareness - Agents don't know if it's their turn to act, leading to race conditions
2. File-Based Prediction - Agents predict state from files, not shared memory, causing stale reads
3. Context Drift - Parallel agents develop inconsistent understanding of the codebase
4. No Agent Discovery - Agents are unaware of other agents working on the same project
5. Duplicate Work - Multiple agents may attempt the same task simultaneously
6. Conflicting Edits - Without coordination, agents overwrite each other's changes

Solution

This MCP server provides:

• Shared Memory - Agents can store and retrieve context, decisions, and findings
• Task Queue - Turn-based task execution with dependencies
• Agent Discovery - Agents can see who else is working on the project
• Resource Locking - Prevent concurrent access to files or resources
• Coordination Status - Real-time visibility into the orchestration state
• Auto Context Sync - Automatically updates activeContext.md for easy reference

Compatibility

Works with any AI coding agent that supports MCP or AGENTS.md:

• OpenAI Codex
• Google Jules
• Cursor
• Aider
• Windsurf
• VS Code Copilot
• GitHub Copilot Coding Agent
• Devin
• And many more!

📦 Installation

Not required. You can use npx to start using the project directly.

💻 Usage Examples

For Initialization

For Any IDE/CLI (AGENTS.md)

# Navigate to your project
cd /path/to/your/project

# Initialize with AGENTS.md
npx agent-orchestration init

For Cursor IDE

# Navigate to your project
cd /path/to/your/project

# Initialize for Cursor (copies .cursor/rules/)
npx agent-orchestration init-cursor

CLI Commands

npx agent-orchestration init           # Create AGENTS.md (works with any AI agent)
npx agent-orchestration init-cursor    # Setup for Cursor IDE (.cursor/rules/)
npx agent-orchestration serve          # Run the MCP server
npx agent-orchestration help           # Show help

MCP Server Setup

Add to your MCP configuration (e.g., ~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "agent-orchestration": {
      "command": "npx",
      "args": ["-y", "agent-orchestration", "serve"],
      "env": {
        "MCP_ORCH_SYNC_CONTEXT": "true"
      }
    }
  }
}

The server automatically uses the current working directory as the project root.

Start Your Session

Use the bootstrap tool to start:

bootstrap

This registers you, shows current focus, pending tasks, and recent decisions.

Recommended Workflow

Main Orchestrator Agent

1. bootstrap                          # Start session
2. memory_set current_focus "..."     # Set project focus
3. task_create "Feature X"            # Create tasks
4. task_create "Feature Y"
5. coordination_status                # Monitor progress

Sub-Agents (Spawned for Specific Work)

1. claim_todo "Feature X"             # Register + claim in one call
2. lock_acquire "src/feature.ts"      # Lock files before editing
3. [do the work]
4. task_complete <task_id> "Done"     # Complete the task
5. agent_unregister                   # Clean up

📚 Documentation

Available Tools

Session Management

Agent Management

Shared Memory

Task Management

Coordination

Memory Namespaces

Use these namespaces for organization:

Configuration

Environment Variables

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     IDE / CLI Tool                           │
├─────────────┬─────────────┬─────────────┬─────────────┬─────┤
│ Main Agent  │ Sub-Agent 1 │ Sub-Agent 2 │ Sub-Agent 3 │ ... │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴─────┘
       │             │             │             │
       └─────────────┴──────┬──────┴─────────────┘
                            │
                    ┌───────▼───────┐
                    │  MCP Server   │
                    │  (TypeScript) │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
      ┌───────▼───┐ ┌───────▼───┐ ┌───────▼───┐
      │  Agents   │ │   Tasks   │ │  Memory   │
      │  Registry │ │   Queue   │ │   Store   │
      └───────────┘ └───────────┘ └───────────┘
              │             │             │
              └─────────────┼─────────────┘
                            │
                    ┌───────▼───────┐
                    │    SQLite     │
                    │  (per-project)│
                    └───────────────┘

AGENTS.md

This project follows the AGENTS.md format - a simple, open format for guiding AI coding agents used by over 60k open-source projects. When you run npx agent-orchestration init, it creates an AGENTS.md file that works with:

• OpenAI Codex
• Google Jules
• Cursor
• Aider
• Windsurf
• VS Code Copilot
• And many more!

Troubleshooting

Server won't start

1. Make sure Node.js 18+ is installed: node --version
2. Check the path in your MCP config is correct

Database errors

The SQLite database is created automatically in .agent-orchestration/. If corrupted:

rm -rf .agent-orchestration/

It will be recreated on next server start.

Agents not seeing each other

• Ensure all agents are using the same cwd in the MCP config
• Check agent_list to see registered agents
• Stale agents are auto-cleaned after 5 minutes of no heartbeat

Development

Prerequisites

• Node.js 18 or higher
• npm

Setup

# Clone the repository
git clone https://github.com/madebyaris/agent-orchestration.git
cd agent-orchestration

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Clean build
npm run clean && npm run build

Roadmap

We're actively developing new features. Here's what's coming:

• [ ] External Memory Integration - Integration with external memory providers like Mem0, Byteover, and our own memory solution
• [ ] Enhanced Sub-Agent Knowledge - Fix limitations in knowledge sharing between main agent and sub-agents
• [ ] Research-First Workflow - When building from scratch, agents should research first and prepare all requirements before coding
• [ ] Graceful Error Handling - Better error handling and recovery across all operations
• [ ] Auto Documentation - Automatically generate documentation from and for each sub-agent + main agent interactions

Have a feature request? Open an issue!

🔧 Technical Details

The project is built with a TypeScript-based MCP server that interacts with a SQLite database per project. It uses environment variables for configuration and provides a set of CLI tools for different operations such as session management, agent management, shared memory management, task management, and coordination.

📄 License

MIT

Author

Aris Setiawan - madebyaris.com

• GitHub: @madebyaris
• Repository: agent-orchestration