flowchart TD
    subgraph ClientLayer["User & Client Layer"]
        User["Developer / User"]
        ClaudeDesktop["Claude Desktop"]
        CursorIDE["Cursor IDE"]
        WebBrowser["Web Browser (Studio GUI)"]
        TelegramUser["Telegram Mobile Client"]
    end

    subgraph GatewayLayer["MCP & Gateway Layer"]
        MCPServer["FastMCP Stdio Server<br/>(mcp_server/server.py)"]
        WebStudio["Web Studio & REST Gateway<br/>(FastAPI / Uvicorn)"]
        TelegramBridge["Telegram Supervisor Bridge<br/>(core/telegram_bridge.py)"]
    end

    subgraph CoreLayer["Orchestrator Core"]
        Engine["Orchestrator Engine<br/>(engine/orchestrator.py)"]
        SQLiteStore["SQLite Event Sourcing<br/>(team.sqlite3)"]
        Queues["Task Queues & Loop Monitor"]
        WatchdogBrain["Watchdog Supervisor Engine<br/>(core/watchdog_brain.py)"]
    end

    subgraph TeamHierarchy["Hierarchical Agent Team"]
        Watchdog["Root Watchdog Agent<br/>(Global Supervisor & Bridge)"]
        CEO["CEO Agent<br/>(Strategic Planning & Architecture)"]
        Manager["Manager Agent<br/>(Milestone Breakdown & Task Dispatch)"]
        Worker1["Specialist Worker 1<br/>(Implementation / Code)"]
        Worker2["Specialist Worker 2<br/>(Documentation / QA)"]
    end

    subgraph ExecutionLayer["Execution Harnesses & Providers"]
        subgraph CLIAdapters["Native CLI Harnesses"]
            ClaudeCode["Claude Code CLI"]
            AntigravityCLI["Gemini Antigravity CLI"]
            CodexCLI["Codex CLI"]
            HermesCLI["Hermes / OpenClaw"]
        end
        subgraph DirectAPI["Direct API Providers"]
            DeepSeekAPI["DeepSeek (V3 / R1)"]
            ZaiAPI["Z.ai / GLM-5"]
            GeminiAPI["Google Gemini"]
            OpenAIAPI["OpenAI"]
            OpenRouterAPI["OpenRouter / SiliconFlow / Groq"]
        end
    end

    User --> ClaudeDesktop
    User --> CursorIDE
    User --> WebBrowser
    TelegramUser <--> TelegramBridge

    ClaudeDesktop -->|"stdio MCP"| MCPServer
    CursorIDE -->|"stdio MCP"| MCPServer
    WebBrowser -->|"HTTP / WebSocket"| WebStudio
    TelegramBridge <--> WatchdogBrain

    MCPServer -->|"Engine Actions"| Engine
    WebStudio -->|"REST / Event Streams"| Engine
    WatchdogBrain <--> Engine

    Engine <--> SQLiteStore
    Engine <--> Queues

    Watchdog -.->|"Supervises"| CEO
    Watchdog -.->|"Supervises"| Manager
    Engine --> CEO
    CEO -->|"Dispatches Roadmap"| Manager
    Manager -->|"Assigns Task"| Worker1
    Manager -->|"Assigns Task"| Worker2

    Worker1 --> CLIAdapters
    Worker2 --> DirectAPI

git clone https://github.com/menma4ever/agentic-team-mcp.git
cd agentic-team-mcp
.\Setup.ps1

# 1. Clone the repository
git clone https://github.com/menma4ever/agentic-team-mcp.git
cd agentic-team-mcp

# 2. Create and activate a Python virtual environment
python -m venv .venv

# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Linux / macOS:
source .venv/bin/activate

# 3. Install core dependencies
pip install -r requirements.txt

cp settings.example.json settings.json

{
  "api_keys": {
    "deepseek": "sk-your-deepseek-key",
    "zai": "your-zai-api-key",
    "gemini": "your-gemini-api-key",
    "openai": "",
    "anthropic": ""
  },
  "cli_auth_enabled": {
    "claude": true,
    "agy": true,
    "codex": false
  }
}

Launch.cmd

python main.py

python main.py [OPTIONS]

Options:
  --port INTEGER    Port for web studio & engine (default: 8765)
  --no-browser      Start engine and studio without opening browser
  --mcp             Run as stdio Model Context Protocol (MCP) server
  --console TEXT    Open human-in-the-loop interactive console for agent

{
  "mcpServers": {
    "agentic-team": {
      "command": "C:\\path\\to\\agentic-team-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\agentic-team-mcp\\main.py",
        "--mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "agentic-team": {
      "command": "C:\\path\\to\\agentic-team-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\agentic-team-mcp\\main.py",
        "--mcp"
      ]
    }
  }
}

agentic-team-mcp/
├── assets/                  # Studio screenshots & preview assets
│   ├── web_studio_team_floor.png
│   ├── web_studio_preview.gif
│   └── web_studio_overview.png
├── Launch.cmd               # Fast Windows launcher
├── Setup.ps1                # Automated PowerShell virtualenv & dependency setup
├── LICENSE                  # MIT License
├── README.md                # Project documentation & guides
├── requirements.txt         # Core dependencies
├── settings.example.json    # Example configuration template
├── main.py                  # Main entry point (Web Studio, Engine & MCP Server)
├── core/                    # Core supervisor, telegram bridge, auth pool & config
│   ├── auth_pool.py         # Multi-account rotation & CLI auth slots
│   ├── catalog.py           # Dynamic model & harness discovery
│   ├── config.py            # Pydantic schema validation & redaction
│   ├── credential_store.py  # Secure local credential storage
│   ├── multimodal.py        # Visual analysis & image processing
│   ├── service.py           # Engine lifecycle & process locking
│   ├── telegram_bridge.py   # Telegram supervisor bridge & alert loop
│   ├── telegram_supervisor.py # Interactive mobile control endpoints
│   ├── watchdog_brain.py    # Root Watchdog intelligence & evaluation
│   └── workspace.py         # Sandboxed workspace directories
├── engine/                  # Orchestration core & persistence
│   ├── actions.py           # Agent action handlers & dispatching
│   ├── loop_monitor.py      # Stuck-loop detection & runaway turn prevention
│   ├── message_router.py    # Priority messaging & event routing
│   ├── models.py            # Pydantic data models for agents & tasks
│   ├── orchestrator.py      # Central event loop & agent scheduler
│   └── store.py             # SQLite event-sourcing database layer
├── harness/                 # Subprocess & provider execution harnesses
│   ├── cli_runner.py        # PTY/pipe adapters for Claude, Antigravity, Codex
│   └── direct_api.py        # Direct async streaming HTTP API client
├── mcp_server/              # Model Context Protocol stdio server
│   └── server.py            # FastMCP tool declarations & engine proxy
├── tests/                   # End-to-end integration & unit test suites
│   ├── test_auth_pool.py
│   ├── test_backend_audit.py
│   ├── test_engine.py
│   ├── test_google_quota_recovery.py
│   ├── test_release.py
│   ├── test_runtime_revision.py
│   ├── test_service.py
│   ├── test_telegram_bridge.py
│   └── test_watchdog_brain.py
└── web/                     # Web Studio dashboard & REST API
    ├── app.py               # FastAPI server & WebSocket endpoints
    └── static/              # Interactive graph, terminal streams, and UI