rawe/claude-agent-orchestrator

Agent Orchestrator Framework (AOF)

A comprehensive framework for orchestrating specialized Claude Code agent sessions.

What is the Agent Orchestrator Framework?

The Agent Orchestrator Framework (AOF) enables you to create, manage, and orchestrate specialized Claude Code agent sessions programmatically. Whether you want to delegate tasks to specialized agents, run long-running background processes, or manage multiple concurrent AI workflows, AOF provides the tools and abstractions you need.

Key Capabilities:

• Launch specialized Claude Code agent sessions programmatically
• Configure agents with custom system prompts and instructions
• Manage multiple concurrent agent sessions
• Inject different MCP server configurations per agent
• Extract and process results from completed agents
• Create reusable agent blueprints for common tasks
• Support for long-running and background tasks

Quick Start

Requirements

• Claude Code CLI - installed and authenticated
• Docker - Desktop or Engine + Compose V2
• Python ≥3.11 + uv

1. Clone and Start Services

git clone <repo-url>
cd claude-agent-orchestrator
make start-all

This starts:

• Dashboard at http://localhost:3000
• Agent Coordinator at http://localhost:8765
• Context Store at http://localhost:8766
• Neo4j at http://localhost:7475
• MCP Servers (Context Store, Neo4j)

Note: Atlassian and Azure DevOps MCPs require credentials in .env files and will be skipped if not configured. See for setup.

2. Start the Agent Runner

The Agent Runner executes agent runs. Run it in your project directory (where agents should work):

cd /path/to/your/project
/path/to/claude-agent-orchestrator/servers/agent-runner/agent-runner

The runner connects to Agent Coordinator and waits for runs. Keep it running while using the framework.

3. Open the Dashboard

make open
# Or manually: open http://localhost:3000

From the Dashboard you can:

• Create and manage agent sessions
• Monitor agent execution in real-time
• Browse and edit agent blueprints
• Manage documents in the Context Store

Stopping Everything

make stop-all    # Stop all services
# Ctrl+C         # Stop the agent runner

Repository Structure

agent-orchestrator-framework/
│
├── README.md                          # This file
├── Makefile                           # Build, run, deploy commands
├── docker-compose.yml                 # Container orchestration
│
├── docs/                              # Documentation
│   ├── ARCHITECTURE.md                # System architecture overview
│   └── agent-coordinator/             # Agent Coordinator server docs
│
├── servers/                           # Backend servers
│   ├── agent-coordinator/             # Session management + event capture + agent registry
│   ├── agent-runner/                  # Run executor (polls coordinator, runs Claude Code)
│   │   └── lib/agent_orchestrator_mcp/  # Embedded Agent Orchestrator MCP server
│   └── context-store/                 # Document storage
│
├── mcps/                              # MCP servers (agent capabilities)
│   ├── context-store/                 # Document management MCP
│   ├── neo4j/                         # Neo4j graph database MCP (Docker)
│   ├── atlassian/                     # Jira + Confluence MCP (Docker, requires credentials)
│   └── ado/                           # Azure DevOps MCP (Docker, requires credentials)
│
├── dashboard/                         # Web UI (React + Vite)
│
├── plugins/                           # Claude Code plugins
│   ├── orchestrator/                  # Agent orchestration commands
│   └── context-store/                 # Document management commands
│
└── config/                            # Configuration
    └── agents/                        # Agent blueprints

MCP Servers (Agent Capabilities)

The mcps/ directory contains MCP servers that provide capabilities to agents. These are the tools agents can use to interact with external services and the framework itself.

Start MCP servers:

make start-mcps                    # Start all external MCP servers
make start-mcp-context-store       # Document management
make start-mcp-neo4j               # Neo4j queries (uses defaults)
make start-mcp-atlassian           # Requires mcps/atlassian/.env
make start-mcp-ado                 # Requires mcps/ado/.env

The Agent Orchestrator MCP is embedded in the Agent Runner:

• When running agents via the framework, the MCP server is automatically available
• Agent configurations use ${AGENT_ORCHESTRATOR_MCP_URL} placeholder (dynamically replaced)
• For external clients (Claude Desktop), start the runner with --mcp-port 9500 to expose a fixed endpoint

See mcps/README.md for detailed setup.

Example Agents

The config/agents/ folder contains example agent blueprints.

Context Store

The Context Store server provides document storage and retrieval for sharing context between agents and sessions. Documents can be tagged, queried, and organized with parent-child relationships.

Optional: Semantic Search - Search documents by meaning using vector embeddings. Requires Ollama running locally with an embedding model. See for setup instructions.

Core Concepts

Agent Blueprints

Reusable configurations that define specialized agent behavior. Each blueprint can include a custom system prompt, instructions, and MCP server configurations. Managed via the Agent Registry server or stored in .agent-orchestrator/agents/.

Sessions

Isolated Claude Code sessions for individual agents. Each session has a unique ID and configuration. Session data is persisted in the Agent Coordinator server (SQLite).

MCP Configuration

Different agents can have different MCP server configurations, enabling specialized capabilities per agent type.

Orchestration Commands

The Python-based ao-* commands (ao-start, ao-resume, ao-status, etc.) are the foundation of both usage levels. They handle session lifecycle, agent configuration, and result extraction.

Service URLs

See for deployment details and for full architecture.

Glossary

See for the complete terminology and conceptual hierarchy.

Testing

The framework includes an integration test suite for verifying Agent Coordinator and Agent Runner functionality. Tests can be run with either a deterministic test executor or the real Claude Code executor.

See for setup and test case documentation.

Documentation

• - Full system architecture and component interactions
• - Detailed setup and configuration
• - Docker setup and configuration
• - Run executor with embedded Agent Orchestrator MCP
• - Document storage server with semantic search
• - All available MCP servers
• - MCP server for document management