agent-orchestration

v0.6.1

Published

3 months ago

Agent Orchestration - MCP server for multi-agent coordination across IDEs and CLI tools

0High
0Medium
0Low

madebyaris

mcp model-context-protocol agents-md cursor ai-agents orchestration multi-agent codex aider windsurf copilot

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.

The Problem

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

No Turn Awareness - Agents don't know if it's their turn to act, leading to race conditions
File-Based Prediction - Agents predict state from files, not shared memory, causing stale reads
Context Drift - Parallel agents develop inconsistent understanding of the codebase
No Agent Discovery - Agents are unaware of other agents working on the same project
Duplicate Work - Multiple agents may attempt the same task simultaneously
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
Research-First Workflow - Ensures agents understand context before coding
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!

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.

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 doc --task <task-id>
npx agent-orchestration cursor check   # Verify Cursor CLI support
npx agent-orchestration cursor delegate --task <task-id>
npx agent-orchestration cursor status --task <task-id>
npx agent-orchestration cursor resume --task <task-id>
npx agent-orchestration cursor sync --task <task-id>
npx agent-orchestration cursor recover --task <task-id>
npx agent-orchestration cursor handoff --task <task-id> --summary "..."
npx agent-orchestration cursor list    # Show delegated Cursor tasks
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

Note: bootstrap is an MCP tool invocation inside your agent/IDE, not a terminal command.

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

Available Tools

Session Management

| Tool | Description | |------|-------------| | bootstrap | Start here! Initialize session: register, get focus, tasks, decisions | | claim_todo | For sub-agents: Register + create/claim a task in one call | | agent_whoami | Get your current agent info (ID, name, role, status) |

Agent Management

| Tool | Description | |------|-------------| | agent_register | Register this agent with the orchestration system | | agent_heartbeat | Send a heartbeat to indicate agent is active | | agent_list | List all registered agents | | agent_unregister | Unregister this agent (releases all locks) |

Shared Memory

| Tool | Description | |------|-------------| | memory_set | Store a value in shared memory | | memory_get | Retrieve a value from shared memory | | memory_list | List all keys in a namespace | | memory_delete | Delete a value from shared memory |

Task Management

| Tool | Description | |------|-------------| | task_create | Create a new task (auto-detects complexity) | | task_claim | Claim a task to work on (requires research for non-trivial) | | task_update | Update task status or progress | | task_complete | Mark a task as completed | | task_list | List tasks with filters | | is_my_turn | Check if work is available for you |

Research Workflow

| Tool | Description | |------|-------------| | research_ready | Mark research complete for a task | | research_status | Check research progress for a task | | research_query | Search past research findings | | research_checklist | View research requirements by complexity |

Coordination

| Tool | Description | |------|-------------| | lock_acquire | Acquire a lock on a resource | | lock_release | Release a held lock | | lock_check | Check if a resource is locked | | coordination_status | Get overall system status |

Cursor Provider

| Tool | Description | |------|-------------| | cursor_check | Verify Cursor CLI availability and supported features | | cursor_delegate_task | Launch a Cursor CLI run for a task and persist session metadata | | cursor_task_status | Inspect delegated task health, recovery state, and retryability | | cursor_resume_task | Return the resume command for a delegated task | | cursor_sync_task | Refresh delegated task state and sync findings back into shared memory | | cursor_recover_task | Relaunch a failed or stale delegated task with current shared context | | cursor_handoff_task | Record a structured handoff for the next agent | | cursor_list_delegations | Show delegated Cursor tasks and their last known status | | task_generate_doc | Generate Markdown documentation for a task from current orchestration state |

Cursor-Native Delegation

You can now delegate orchestrator tasks directly to Cursor CLI instead of manually creating a plan, opening a new tab, and pasting context yourself.

CLI Workflow

# Verify Cursor CLI is available
npx agent-orchestration cursor check

# Delegate a task to Cursor
npx agent-orchestration cursor delegate --task <task-id> --mode agent

# Inspect health and recovery hints
npx agent-orchestration cursor status --task <task-id>

# Resume the delegated session later
npx agent-orchestration cursor resume --task <task-id>

# Sync the latest delegated knowledge back into shared memory
npx agent-orchestration cursor sync --task <task-id>

# Recover a stale or failed delegated run
npx agent-orchestration cursor recover --task <task-id>

# Record a structured handoff for another agent
npx agent-orchestration cursor handoff --task <task-id> --summary "Current implementation is complete; QA and docs remain."

# Generate task documentation on demand
npx agent-orchestration doc --task <task-id>

# Or launch the resume session immediately
npx agent-orchestration cursor resume --task <task-id> --exec

MCP Workflow

cursor_delegate_task:
  task_id: "<task-id>"
  mode: "agent"
  use_worktree: true

Delegations store provider metadata directly on the task, including:

Cursor chat/session ID
provider status
worktree usage
launch command
run log path

Moderate and complex tasks default to Cursor worktrees for safer parallel execution.

Delegation Knowledge Loop

Delegated Cursor tasks now write structured shared memory so the next agent can resume with live context instead of only the original launch prompt.

Namespaces:

delegation:<task_id>:brief
delegation:<task_id>:updates
delegation:<task_id>:findings
delegation:<task_id>:decisions
delegation:<task_id>:handoff

Recommended flow:

cursor_delegate_task or agent-orchestration cursor delegate
cursor_task_status to inspect health and recovery hints
cursor_sync_task or agent-orchestration cursor sync
cursor_recover_task when the delegated process is stale or failed
cursor_handoff_task when a human or another agent needs to pick up the work
cursor_resume_task to rebuild a resume prompt from the latest shared knowledge

Graceful Recovery

Delegated Cursor runs now track recovery metadata directly on the task:

recovery state (healthy, stale, failed, completed, unknown)
recoverability
last error / exit code
retry count
recovery hints

This enables:

stale process detection when no clean exit is captured
structured recovery hints in MCP and CLI
safe relaunch via cursor_recover_task
preservation of knowledge and handoff state across retries

Auto Documentation

Task documentation is now generated automatically into .agent-orchestration/docs/ from:

task metadata and output
research namespaces
delegation knowledge namespaces
provider health and recovery state
recent task-specific orchestration events

Generated files:

.agent-orchestration/docs/tasks/<task-id>.md
.agent-orchestration/docs/README.md

Documentation refreshes automatically during:

delegated task launch
delegated sync
delegated handoff
delegated recovery
task completion

You can also regenerate docs manually with:

npx agent-orchestration doc --task <task-id>

Research-First Workflow

Tasks are automatically assigned a complexity level that determines research requirements:

| Complexity | Examples | Research Required | |------------|----------|-------------------| | trivial | Typo fix, config change | None | | simple | Bug fix, small refactor | context, files | | moderate | New endpoint, component | + requirements | | complex | New feature, migration | + design |

How It Works

Task Creation - Complexity is auto-detected from keywords (or manually set)
Research Phase - Agent documents findings in structured namespaces
Research Gate - task_claim is blocked until research is complete
Implementation - Agent proceeds with full context

Research Namespaces

research:<task_id>:context      # Understanding of codebase
research:<task_id>:files        # Affected files identified
research:<task_id>:requirements # Specs and edge cases
research:<task_id>:design       # Architecture 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 (complexity auto-detected)
4. task_create "Feature Y"
5. coordination_status                # Monitor progress

Sub-Agents (Spawned for Specific Work)

1. claim_todo "Feature X"             # Register + see research checklist

# Research Phase (for non-trivial tasks)
2. memory_set key="understanding" namespace="research:<task_id>:context" value="..."
3. memory_set key="files" namespace="research:<task_id>:files" value="..."
4. research_ready task_id="<task_id>" # Validate research complete

# Implementation Phase
5. task_claim task_id="<task_id>"     # Now allowed to start
6. lock_acquire "src/feature.ts"      # Lock files before editing
7. [do the work]
8. task_complete <task_id> "Done"     # Complete the task
9. agent_unregister                   # Clean up

Trivial Tasks (No Research)

1. claim_todo "Fix typo in README"    # Complexity: trivial
2. task_claim task_id="<task_id>"     # Immediately allowed
3. [do the work]
4. task_complete <task_id> "Done"

Memory Namespaces

Use these namespaces for organization:

| Namespace | Purpose | Example Keys | |-----------|---------|--------------| | context | Current state and focus | current_focus, current_branch | | decisions | Architectural decisions | auth_strategy, db_choice | | findings | Analysis results | perf_issues, security_audit | | blockers | Issues blocking progress | api_down, missing_deps |

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_ORCH_DB_PATH | Path to SQLite database | .agent-orchestration/orchestrator.db | | MCP_ORCH_SYNC_CONTEXT | Auto-sync activeContext.md | false | | MCP_ORCH_AGENT_NAME | Default agent name | Auto-generated | | MCP_ORCH_AGENT_ROLE | Default agent role | sub | | MCP_ORCH_CAPABILITIES | Comma-separated capabilities | code |