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:

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
• 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:

1. cursor_delegate_task or agent-orchestration cursor delegate
2. cursor_task_status to inspect health and recovery hints
3. cursor_sync_task or agent-orchestration cursor sync
4. cursor_recover_task when the delegated process is stale or failed
5. cursor_handoff_task when a human or another agent needs to pick up the work
6. 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

1. Task Creation - Complexity is auto-detected from keywords (or manually set)
2. Research Phase - Agent documents findings in structured namespaces
3. Research Gate - task_claim is blocked until research is complete
4. 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

agent-orchestration.config.json

Optional project-level config for Cursor orchestration:

{
  "cursor": {
    "binary": "agent",
    "defaultMode": "agent",
    "defaultForce": true,
    "autoApproveMcps": true,
    "trustWorkspace": true,
    "useCreateChat": true,
    "logDir": ".agent-orchestration/providers/cursor",
    "preferWorktreeFor": ["moderate", "complex"],
    "recoveryStaleAfterMs": 600000
  }
}

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

For contributors and local 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:

• Research-First Workflow - Agents research and prepare before coding (DONE in v0.5.2, carried forward in v0.6.0)
• External Memory Integration - Integration with external memory providers like Mem0, Byteover, and our own memory solution
• Enhanced Sub-Agent Knowledge - Delegated Cursor tasks now persist structured briefs, updates, findings, decisions, and handoff state in shared memory
• Graceful Error Handling - Delegated Cursor tasks now track health, stale/failed recovery state, retry counts, and structured recovery hints
• Auto Documentation - Task docs are now generated automatically from orchestration state, delegation memory, provider recovery metadata, and task events

Have a feature request? Open an issue!

Author

Aris Setiawan - madebyaris.com

• GitHub: @madebyaris
• Repository: agent-orchestration

License

MIT