Skip to content
Back to search

AI-Agents-Orchestrator

πŸͺˆ Intelligent orchestration system that coordinates multiple AI coding assistants (Claude, Codex, Gemini CLI, Copilot CLI) to collaborate on complex software development tasks via REPL or a Vue/Nuxt UI dashboard. Also includes an Agentic Team runtime with role-based multi-agent open communication & lead-gated final responses.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hoangsonww--ai-agents-orchestrator/badge.svg)](/listings/hoangsonww--ai-agents-orchestrator)

HTML

<a href="/listings/hoangsonww--ai-agents-orchestrator"><img src="/api/listings/hoangsonww--ai-agents-orchestrator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Use AI Collaboration Only (Minimal Setup)

If you want cross-agent continuity rather than a complete orchestration platform, use the standalone plugin directly. It has no dependency on the root `requirements.txt`.

git clone https://github.com/hoangsonww/AI-Agents-Orchestrator.git
cd AI-Agents-Orchestrator

# Example: install into Codex from the local plugin marketplace
codex plugin marketplace add ./AI-Collaboration-Skills
codex plugin add ai-collaboration@ai-collaboration

# Start a continuity task from the repository you are editing
cd /path/to/your-project
/path/to/AI-Agents-Orchestrator/AI-Collaboration-Skills/bin/ai-collaboration \
  task start "Implement account recovery"

The plugin begins recording supported lifecycle events locally. Open another supported agent in the same repository and invoke the `resume-task` skill or call `ai_collaboration.get_context`; both agents resolve the same active task from `~/.ai-collaboration/`.

Claude Code, Cursor, Gemini CLI, and GitHub Copilot CLI installation commands are documented in [`AI-Collaboration-Skills/README.md`](AI-Collaboration-Skills/README.md#install-from-this-repository).

Prerequisites

- **Operating System**: Linux, macOS, or Windows (WSL recommended) - **Python**: 3.8 or higher - **Node.js**: 20+ (for Web UI) - **Memory**: Minimum 4GB RAM - **Disk Space**: 1GB for installation + workspace - **Network**: Required for AI CLI tools and updates - **Claude Code**: Installed, setup, and signed in on your machine (Required for any workflows using Claude Code - if you run `claude` in terminal and it works, you're good) - **OpenAI Codex**: Installed and authenticated (if using Codex agent, try running `codex` and see if it responds) - **Google Gemini CLI**: Installed and authenticated (if using Gemini agent, try `gemini --version` to verify) - **GitHub Copilot CLI**: Installed and authenticated (if using Copilot agent, try `copilot --version` to verify) - **Llama.cpp or Ollama**: If using local LLM agents, ensure they are installed and configured properly (try running `ollama list` or `llamacpp --help` to verify) - **Optional**: Docker and Docker Compose for containerized setup

Install

git clone https://github.com/hoangsonww/AI-Agents-Orchestrator.git
cd AI-Agents-Orchestrator

python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

pip install -r requirements.txt
chmod +x ai-orchestrator

Run the Orchestrator

# Interactive shell
./ai-orchestrator shell

# One-shot task
./ai-orchestrator run "Create a Python REST API" --workflow default

# Start the Web UI
make run-ui
# Then open http://localhost:5001

Run the Agentic Team

# Interactive REPL
./ai-orchestrator agentic-shell

# With options
./ai-orchestrator agentic-shell --max-turns 16 --offline

# Start the Web UI
make run-agentic-ui
# Then open http://localhost:5002

Verify Installation

./ai-orchestrator --help        # Show all commands
./ai-orchestrator agents        # List available agents
./ai-orchestrator workflows     # List available workflows
./ai-orchestrator validate      # Validate configuration

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,403 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AI Coding Tools Orchestrator and Agentic Team Runtime
  2. ![Claude](https://img.shields.io/badge/Claude-Anthropic-D97706?logo=anthropic&logoColor=white)
  3. ![OpenAI Codex](https://img.shields.io/badge/Codex-OpenAI-412991?logo=openai&logoColor=white)
  4. ![Gemini](https://img.shields.io/badge/Gemini-Google-4285F4?logo=google&logoColor=white)
  5. ![GitHub Copilot](https://img.shields.io/badge/Copilot-GitHub-000000?logo=githubcopilot&logoColor=white)
  6. ![Ollama](https://img.shields.io/badge/Ollama-Local_LLM-000000?logo=ollama&logoColor=white)
  7. ![llama.cpp](https://img.shields.io/badge/llama.cpp-GGUF-8B5CF6?logo=meta&logoColor=white)
  8. ![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB?logo=python&logoColor=white)
  9. ![Model Context Protocol](https://img.shields.io/badge/MCP-Model_Context_Protocol-4A90D9?logo=modelcontextprotocol&logoColor=white)
  10. ![FastMCP](https://img.shields.io/badge/FastMCP-3.x-black?logo=modelcontextprotocol&logoColor=white)
  11. ![Flask](https://img.shields.io/badge/Flask-3.x-000000?logo=flask&logoColor=white)
  12. ![Pydantic](https://img.shields.io/badge/Pydantic-2.x-E92063?logo=pydantic&logoColor=white)
  13. ![Click](https://img.shields.io/badge/Click-8.x-000000?logo=python&logoColor=white)
  14. ![Rich](https://img.shields.io/badge/Rich-13.x-009485?logo=python&logoColor=white)
  15. ![HTTPX](https://img.shields.io/badge/HTTPX-0.27-3776AB?logo=python&logoColor=white)
  16. ![Tenacity](https://img.shields.io/badge/Tenacity-Retry-3776AB?logo=python&logoColor=white)
  17. ![Structlog](https://img.shields.io/badge/Structlog-Logging-3776AB?logo=python&logoColor=white)
  18. ![PyYAML](https://img.shields.io/badge/PyYAML-6.x-3776AB?logo=yaml&logoColor=white)
  19. ![Vue.js](https://img.shields.io/badge/Vue.js-3.x-4FC08D?logo=vue.js&logoColor=white)
  20. ![Nuxt](https://img.shields.io/badge/Nuxt-3.x-00C58E?logo=nuxt.js&logoColor=white)
  21. ![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?logo=vite&logoColor=white)
  22. ![TailwindCSS](https://img.shields.io/badge/Tailwind-3.x-06B6D4?logo=tailwindcss&logoColor=white)
  23. ![Pinia](https://img.shields.io/badge/Pinia-State-FFD859?logo=vue.js&logoColor=white)
  24. ![Monaco](https://img.shields.io/badge/Monaco_Editor-VS_Code-007ACC?logo=visualparadigm&logoColor=white)
  25. ![Obsidian](https://img.shields.io/badge/Obsidian-Knowledge_Graph-483699?logo=obsidian&logoColor=white)
  26. ![Socket.IO](https://img.shields.io/badge/Socket.IO-4.x-010101?logo=socket.io&logoColor=white)
  27. ![Axios](https://img.shields.io/badge/Axios-HTTP-5A29E4?logo=axios&logoColor=white)
  28. ![Prometheus](https://img.shields.io/badge/Prometheus-Metrics-E6522C?logo=prometheus&logoColor=white)
  29. ![Grafana](https://img.shields.io/badge/Grafana-Dashboards-F46800?logo=grafana&logoColor=white)
  30. ![Bandit](https://img.shields.io/badge/Bandit-Security_Scan-FFD43B?logo=python&logoColor=white)
  31. ![Pylint](https://img.shields.io/badge/Pylint-10.00%2F10-brightgreen?logo=python&logoColor=white)
  32. ![Pytest](https://img.shields.io/badge/Pytest-562_Tests-0A9EDC?logo=pytest&logoColor=white)
  33. ![MyPy](https://img.shields.io/badge/MyPy-Type_Checked-3776AB?logo=python&logoColor=white)
  34. ![Black](https://img.shields.io/badge/Code_Style-Black-000000?logo=python&logoColor=white)
  35. ![Flake8](https://img.shields.io/badge/Linter-Flake8-4B8BBE?logo=python&logoColor=white)
  36. ![isort](https://img.shields.io/badge/isort-Imports-EF8336?logo=python&logoColor=white)
  37. ![Pre-commit](https://img.shields.io/badge/Pre--commit-15_Hooks_Passing-FAB040?logo=precommit&logoColor=white)
  38. ![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
  39. ![Kubernetes](https://img.shields.io/badge/Kubernetes-Ready-326CE5?logo=kubernetes&logoColor=white)
  40. ![SQLite](https://img.shields.io/badge/SQLite-Context_Graph-003B57?logo=sqlite&logoColor=white)
  41. ![FTS5](https://img.shields.io/badge/FTS5-Full_Text_Search-003B57?logo=sqlite&logoColor=white)
  42. ![BM25](https://img.shields.io/badge/BM25-Ranking-3776AB?logo=python&logoColor=white)
  43. ![Sentence Transformers](https://img.shields.io/badge/Sentence_Transformers-Embeddings-FF6F00?logo=huggingface&logoColor=white)
  44. ![psutil](https://img.shields.io/badge/psutil-System_Metrics-3776AB?logo=python&logoColor=white)
  45. ![python-dotenv](https://img.shields.io/badge/python--dotenv-Env_Config-ECD53F?logo=dotenv&logocolor=white)
  46. ![Colorama](https://img.shields.io/badge/Colorama-Terminal_Colors-3776AB?logo=python&logoColor=white)
  47. ![pyupgrade](https://img.shields.io/badge/pyupgrade-Syntax_Modernizer-3776AB?logo=python&logoColor=white)
  48. ![Terraform](https://img.shields.io/badge/Terraform-IaC-844FBA?logo=terraform&logoColor=white)
  49. ![NGINX](https://img.shields.io/badge/NGINX-Reverse_Proxy-009639?logo=nginx&logoColor=white)
  50. ![HAProxy](https://img.shields.io/badge/HAProxy-Load_Balancer-009639?logo=task&logoColor=white)
  51. ![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-CI%2FCD-2088FF?logo=githubactions&logoColor=white)
  52. ![GitLab CI](https://img.shields.io/badge/GitLab_CI-Pipeline-FC6D26?logo=gitlab&logoColor=white)
  53. ![Jenkins](https://img.shields.io/badge/Jenkins-Pipeline-D24939?logo=jenkins&logoColor=white)
  54. ![Microsoft Azure](https://img.shields.io/badge/Azure-Cloud-0078D4?logo=microsoftazure&logoColor=white)
  55. ![systemd](https://img.shields.io/badge/systemd-Services-4EAA25?logo=linux&logoColor=white)
  56. ![MIT License](https://img.shields.io/badge/License-MIT-green?logo=opensourceinitiative&logoColor=white)
  57. ![Mermaid Diagrams](https://img.shields.io/badge/Mermaid_Diagrams-132-FF3670?logo=mermaid&logoColor=white)
  58. <div align="center">
  59. **Six independent systems β€” an AI Orchestrator, an Agentic Team runtime, AI Collaboration task continuity, an MCP Server, a Context Dashboard, and Graphify (project-to-graph intelligence engine) β€” that help Claude, Codex, Cursor, Gemini, Copilot, Ollama, and llama.cpp collaborate on software development tasks.**
  60. [Overview](#overview) | [Architecture](#architecture) | [Agentic Infrastructure](#agentic-infrastructure) | [System Comparison](#system-comparison) | [Features](#feature-highlights) | [Quick Start](#quick-start) | [Project Structure](#project-structure) | [Configuration](#configuration) | [Deployment](#deployment) | [Testing](#testing) | [MCP Server](#mcp-server-optional----model-context-protocol)
  61. </div>
  62. ---
  63. ## Overview
  64. AI Coding Tools ships **six independent systems** in a single repository:
  65. 1. The **Orchestrator** runs step-based workflows where AI agents execute tasks in sequence (implement, review, refine).
  66. 2. The **Agentic Team** runs a free-communication runtime where role-based agents (Project Manager, Architect, Developer, QA, DevOps) discuss a task in turns until the team lead declares the work complete.
  67. 3. **Graphify** turns any project directory into a queryable knowledge graph β€” classes, functions, imports, call graphs, and design rationale stored in a local SQLite database with FTS5 search.
  68. 4. **AI Collaboration** is a separately installable, zero-dependency task-continuity plugin for Claude Code, Codex, Cursor, Gemini CLI, and GitHub Copilot CLI. Native lifecycle hooks capture prompts, tool activity, Git state, tests, and checkpoints into a private local store; portable skills and a standalone MCP server let the next agent resume with focused, deterministic context.
  69. 5. The **MCP Server** bridges both engines to IDE-based AI assistants.
  70. 6. The **Context Dashboard** visualizes the graph memory. Each runtime carries its own adapters, configuration, UI, and CLI; AI Collaboration is also standalone and imports from neither runtime.
  71. Beyond the core engines, we provide a complete **Agentic Infrastructure** that empowers AI agents:
  72. - **9 Specialized Agents** for web, backend, security, DevOps, AI/ML, database, mobile, performance, and documentation
  73. - **22 Reusable Skills** across development, testing, security, DevOps, AI/ML, and documentation
  74. - **34+ MCP Tools** for code analysis, security scanning, testing, DevOps, and context memory
  75. - **Graph Context System** with hybrid search (BM25 + semantic) for persistent memory and learning
  76. - **Domain Rules** encoding best practices for security, database, API design, performance, and AI/ML
  77. > [!TIP]
  78. > Quickstart with the Orchestrator for structured workflows, or the Agentic Team for open-ended collaboration. Both systems benefit from the shared agentic infrastructure and context memory. See [QUICKSTART.md](QUICKSTART.md) for quick setup instructions to get started in ~2 minutes. Or, see [#quick-start](#quick-start) below for a detailed walkthrough.
  79. > [!TIP]
  80. > **Do not want to set up the full platform?** Install only [`AI-Collaboration-Skills/`](AI-Collaboration-Skills/README.md). It needs no project Python dependencies, web UI, orchestrator configuration, or hosted serviceβ€”just Python 3.8+, Git, and a supported coding agent. Use it to move an in-progress task between agents, recover work after a context limit, or keep a durable local audit trail while continuing to work directly in your preferred CLI or editor.
  81. ## Agentic Infrastructure
  82. We provide a rich agentic infrastructure that both the Orchestrator and Agentic Team utilize to empower their AI agents with specialized knowledge, reusable skills, powerful tools, and persistent context memory. This infrastructure is designed to be modular and extensible, allowing for easy addition of new agents, skills, tools, and context nodes as the system evolves.
  83. ```mermaid
  84. graph TB
  85. subgraph "🧠 Agentic Infrastructure"
  86. direction LR
  87. subgraph AGENTS["Specialized Agents (9)"]
  88. WEB[Web Frontend]
  89. API[Backend API]
  90. SEC[Security]
  91. OPS[DevOps]
  92. ML[AI/ML]
  93. DB[Database]
  94. end
  95. subgraph SKILLS["Skills Library (22)"]
  96. DEV[Development]
  97. TEST[Testing]
  98. SECS[Security]
  99. DEVOPS[DevOps]
  100. AIML[AI/ML]
  101. DOCS[Documentation]
  102. end
  103. subgraph TOOLS["MCP Tools (34+)"]
  104. CODE[Code Analysis]
  105. SCAN[Security Scan]
  106. TTOOLS[Testing]
  107. DTOOLS[DevOps]
  108. CTX[Context Memory]
  109. end
  110. subgraph CONTEXT["Graph Context"]
  111. GRAPH[(Graph Store)]
  112. SEARCH[Hybrid Search]
  113. EMBED[Embeddings]
  114. end
  115. end
  116. AGENTS --> SKILLS
  117. SKILLS --> TOOLS
  118. TOOLS --> CONTEXT
  119. ```
  120. | Component | Count | Description |
  121. |-----------|-------|-------------|
  122. | **Specialized Agents** | 9 | Domain experts for web, backend, security, DevOps, AI/ML, database, mobile, performance, documentation |
  123. | **Skills** | 22 | Reusable task templates across 6 categories |
  124. | **MCP Tools** | 34+ | Code analysis, security scanning, testing, DevOps, context memory |
  125. | **Node Types** | 10 | Conversation, Task, Mistake, Pattern, Decision, CodeSnippet, Preference, File, Concept, Project |
  126. | **Edge Types** | 12 | RELATED_TO, CAUSED_BY, FIXED_BY, SIMILAR_TO, DEPENDS_ON, etc. |
  127. > [!IMPORTANT]
  128. > πŸ“š **[Click for Full Agentic Infrastructure Documentation](AGENTIC_INFRA.md)**
  129. ### Context System
  130. Both the Orchestrator and Agentic Team maintain **independent** graph-based context databases for persistent memory and cross-session learning. A unified Context Dashboard aggregates both stores for visualization.
  131. ```mermaid
  132. graph TB
  133. subgraph "Context System Architecture"
  134. direction TB
  135. subgraph ORCH_CTX["Orchestrator Context<br/>~/.ai-orchestrator/context.db"]
  136. OM[models/ β€” Node & edge schemas]
  137. OS[store/ β€” Graph persistence]
  138. OX[search/ β€” BM25 + semantic + hybrid]
  139. OO[ops/ β€” Analytics, export, pruning, versioning]
  140. end
  141. subgraph TEAM_CTX["Agentic Team Context<br/>~/.agentic-team/context.db"]
  142. TM[models/ β€” Node & edge schemas]
  143. TS[store/ β€” Graph persistence]
  144. TX[search/ β€” BM25 + semantic + hybrid]
  145. TO[ops/ β€” Analytics, export, pruning, versioning]
  146. end
  147. subgraph DASH["Context Dashboard :5003"]
  148. APP[app.py β€” Flask aggregator]
  149. VIZ[templates/ β€” Interactive visualization]
  150. end
  151. subgraph OBS_OUT["Obsidian Export"]
  152. OBS_V["Obsidian Vault<br/>[[wikilinks]] + graph.json"]
  153. end
  154. end
  155. ORCH_CTX --> DASH
  156. TEAM_CTX --> DASH
  157. ORCH_CTX --> OBS_OUT
  158. TEAM_CTX --> OBS_OUT
  159. style ORCH_CTX fill:#1a365d,color:#fff
  160. style TEAM_CTX fill:#1a365d,color:#fff
  161. style DASH fill:#2d3748,color:#fff
  162. style OBS_OUT fill:#7C3AED,color:#fff
  163. ```
  164. **Node Types** β€” 10 types of knowledge stored in the graph:
  165. | Node Type | Description |
  166. |-----------|-------------|
  167. | **Conversation** | Past chat sessions with full message history |
  168. | **Task** | Completed tasks with outcomes, agent used, and duration |
  169. | **Mistake** | Errors with corrections and prevention strategies |
  170. | **Pattern** | Reusable code patterns and best practices |
  171. | **Decision** | Architectural decisions with rationale and trade-offs |
  172. | **CodeSnippet** | Useful code fragments with language and context |
  173. | **Preference** | Learned user preferences (tools, style, workflows) |
  174. | **File** | Source files with language, size, and framework metadata |
  175. | **Concept** | Abstract concepts and domain knowledge |
  176. | **Project** | Registered project roots with scan metadata |
  177. **Edge Types** β€” 12 relationship types connecting nodes:
  178. | Edge Type | Description |
  179. |-----------|-------------|
  180. | `RELATED_TO` | General semantic relationship |
  181. | `CAUSED_BY` | Causal chain (mistake β†’ root cause) |
  182. | `FIXED_BY` | Resolution link (mistake β†’ fix) |
  183. | `SIMILAR_TO` | Similarity link (patterns, tasks) |
  184. | `DEPENDS_ON` | Dependency relationship |
  185. | `PRECEDED_BY` | Temporal ordering (earlier event) |
  186. | `FOLLOWED_BY` | Temporal ordering (later event) |
  187. | `LEARNED_FROM` | Knowledge derivation (preference β†’ conversation) |
  188. | `USED_IN` | Usage relationship (pattern β†’ task) |
  189. | `REFERENCES` | Cross-reference between nodes |
  190. | `DERIVED_FROM` | Derived knowledge (snippet β†’ pattern) |
  191. | `EVOLVED_INTO` | Evolution tracking (v1 pattern β†’ v2) |
  192. **Hybrid Search** combines three retrieval strategies via Reciprocal Rank Fusion (RRF):
  193. 1. **BM25** β€” Keyword-based search using term frequency–inverse document frequency
  194. 2. **Semantic** β€” Embedding-based similarity using vector cosine distance
  195. 3. **Hybrid** β€” Fused ranking of BM25 + semantic results using RRF for best-of-both-worlds retrieval
  196. ### Project-Scoped Context Graphs
  197. Both systems support **project-scoped context graphs** for full portability. When a user points the system at their project directory, agents automatically scan and build a rich context graph of the codebase.
  198. ```mermaid
  199. graph TB
  200. subgraph "Project Context Scoping"
  201. direction TB
  202. USER[User configures PROJECT_PATH] --> SCAN[ProjectScanner]
  203. SCAN --> PID["project_id = SHA-256[:16] of path"]
  204. subgraph "Isolated Project Graphs"
  205. P1["Project A<br/>pid=a1b2c3..."]
  206. P2["Project B<br/>pid=d4e5f6..."]
  207. P3["Global Scope<br/>pid='' (no project)"]
  208. end
  209. PID --> P1 & P2
  210. SCAN --> FILES[File Nodes]
  211. SCAN --> PATTERNS[Pattern Nodes]
  212. SCAN --> DECISIONS[Decision Nodes]
  213. SCAN --> EDGES[Relationship Edges]
  214. end
  215. style P1 fill:#2b6cb0,stroke:#2c5282,color:#fff
  216. style P2 fill:#276749,stroke:#22543d,color:#fff
  217. style P3 fill:#744210,stroke:#975a16,color:#fff
  218. ```
  219. **Key features:**
  220. - **Deterministic IDs**: `project_id` is a SHA-256 prefix of the normalized absolute path β€” idempotent and reproducible
  221. - **Multi-project isolation**: Each project gets its own graph partition; queries filter by `project_id`
  222. - **Global scope**: Nodes with `project_id=""` are universal (patterns, reference knowledge) β€” shared across all projects
  223. - **Automatic scanning**: `ProjectScanner` detects languages, frameworks, file structure, and config patterns
  224. - **Portability**: Set `PROJECT_PATH` environment variable or `settings.project_path` in config YAML β€” the system handles the rest
  225. - **Incremental updates**: `rescan_project()` rebuilds the graph atomically; `delete_project_graph()` cleanly removes all project nodes
  226. > [!TIP]
  227. > **Auto-seeding:** Run `scripts/seed_context_graphs.py` to populate both context databases with generic reference knowledge (patterns, mistakes, decisions) on first use. Seed data contains no hallucination-prone fake tasks or conversations β€” only universally applicable best practices.
  228. > [!NOTE]
  229. > **Context Dashboard:** Launch with `python -m context_dashboard` (port 5003) to visualize both context graphs, inspect nodes/edges, and search across all stored knowledge. See [`context_dashboard/README.md`](context_dashboard/README.md) for details.
  230. > [!TIP]
  231. > **Obsidian Export:** Export any graph as an [Obsidian](https://obsidian.md) vault for offline interactive exploration. Graphify: `graphify export obsidian <path>`. Context systems: `ContextExporter.export_obsidian()`. Each vault includes `[[wikilinks]]`, typed folders, YAML frontmatter, and pre-configured `.obsidian/graph.json` color groups. See [GRAPHIFY.md](GRAPHIFY.md#obsidian-vault-export), [ORCHESTRATOR.md](ORCHESTRATOR.md#obsidian-vault-export), and [AGENTIC_TEAM.md](AGENTIC_TEAM.md#obsidian-vault-export).
  232. ### Skills Library & Agent Definitions
  233. AI coding agents are enhanced with specialized role definitions, reusable skills, and domain rules that are automatically loaded based on context.
  234. ```mermaid
  235. graph LR
  236. subgraph "Agent Ecosystem"
  237. direction TB
  238. subgraph CLAUDE[".claude/"]
  239. CA["agents/ (11)"]
  240. CS["skills/ (23)"]
  241. CR["rules/ (11)"]
  242. CC[CLAUDE.md]
  243. end
  244. subgraph CODEX[".codex/"]
  245. XA["agents/ (13)"]
  246. XC[config.toml]
  247. XR[rules/]
  248. end
  249. AGENTS_MD[AGENTS.md β€” Shared instructions]
  250. end
  251. CA --> CS
  252. CA --> CR
  253. AGENTS_MD --> CLAUDE
  254. AGENTS_MD --> CODEX
  255. style CLAUDE fill:#7c3aed,color:#fff
  256. style CODEX fill:#059669,color:#fff
  257. ```
  258. **Claude Agents** β€” 11 specialized agents in `.claude/agents/`:
  259. | Agent | File | Domain |
  260. |-------|------|--------|
  261. | Web Frontend | `web-frontend.md` | React, Vue, CSS, accessibility, responsive design |
  262. | Backend API | `backend-api.md` | REST, GraphQL, databases, Flask/FastAPI |
  263. | Security Specialist | `security-specialist.md` | OWASP, vulnerability analysis, secure coding |
  264. | DevOps Infrastructure | `devops-infrastructure.md` | Docker, Kubernetes, CI/CD, cloud |
  265. | AI/ML Engineer | `ai-ml-engineer.md` | ML pipelines, embeddings, LLM integration |
  266. | Database Architect | `database-architect.md` | Schema design, query optimization, migrations |
  267. | Mobile Developer | `mobile-developer.md` | iOS, Android, React Native, Flutter |
  268. | Performance Engineer | `performance-engineer.md` | Profiling, load testing, optimization |
  269. | Documentation Writer | `documentation-writer.md` | API docs, architecture, tutorials |
  270. | Code Reviewer | `code-reviewer.md` | Code quality, best practices, PR reviews |
  271. | Test Runner | `test-runner.md` | Test execution, coverage, failure diagnosis |
  272. **Codex Agents** β€” 13 specialized agents in `.codex/agents/`:
  273. | Agent | File | Domain |
  274. |-------|------|--------|
  275. | Code Reviewer | `code-reviewer.toml` | Code quality and review automation |
  276. | Explorer | `explorer.toml` | Codebase exploration and research |
  277. | Security Specialist | `security-specialist.toml` | Security auditing and vulnerability scanning |
  278. | Web Frontend | `web-frontend.toml` | Frontend development and UI patterns |
  279. | DevOps Infrastructure | `devops-infrastructure.toml` | Infrastructure and deployment automation |
  280. | Implementer | `implementer.toml` | Feature implementation and coding |
  281. | Database Architect | `database-architect.toml` | Database design and optimization |
  282. | Performance Engineer | `performance-engineer.toml` | Performance profiling and optimization |
  283. | Test Runner | `test-runner.toml` | Test suite execution and diagnosis |
  284. | AI/ML Engineer | `ai-ml-engineer.toml` | ML pipelines and AI system design |
  285. | Backend API | `backend-api.toml` | Backend services and API development |
  286. | Documentation Writer | `documentation-writer.toml` | Technical documentation |
  287. | Mobile Developer | `mobile-developer.toml` | Mobile application development |
  288. **Skills Library** β€” 24 reusable skill templates in `.claude/skills/` across 7 categories:
  289. | Category | Count | Skills |
  290. |----------|-------|--------|
  291. | **Development** | 6 | `react-components`, `rest-api-design`, `python-async`, `database-queries`, `graphql-development`, `error-handling` |
  292. | **Testing** | 4 | `unit-testing`, `integration-testing`, `test-driven-development`, `performance-testing` |
  293. | **Security** | 4 | `input-validation`, `authentication`, `secure-coding`, `vulnerability-assessment` |
  294. | **DevOps** | 3 | `docker-containerization`, `ci-cd-pipelines`, `kubernetes-deployment` |
  295. | **AI/ML** | 3 | `embeddings-retrieval`, `llm-integration`, `rag-pipeline` |
  296. | **Documentation** | 3 | `api-documentation`, `architecture-docs`, `code-documentation` |
  297. | **Context** | 1 | `context-graph-builder` |
  298. > Four additional standalone skills (`context-graph-builder`, `generate-reports`, `health-check`, `run-tests`) provide operational task automation.
  299. **Domain Rules** β€” 11 rule files in `.claude/rules/` encoding best practices:
  300. | Rule | File | Enforces |
  301. |------|------|----------|
  302. | Adapters | `adapters.md` | Adapter pattern, base class contracts |
  303. | API Design | `api-design.md` | RESTful conventions, versioning, error formats |
  304. | Testing | `testing.md` | Pytest patterns, coverage requirements, fixtures |
  305. | Performance | `performance.md` | Profiling, caching, async patterns |
  306. | Config | `config.md` | YAML config, environment variables, validation |
  307. | AI/ML | `ai-ml.md` | Model integration, embeddings, prompt patterns |
  308. | Observability | `observability.md` | Logging, metrics, health checks |
  309. | Frontend | `frontend.md` | Component patterns, accessibility, state management |
  310. | CI/CD | `ci-cd.md` | Pipeline design, deployment gates, rollback |
  311. | Security | `security.md` | Input validation, auth, secrets management |
  312. | Database | `database.md` | Schema design, migrations, query safety |
  313. > [!NOTE]
  314. > Agents automatically inherit access to all skills and rules in their scope. When Claude Code is invoked with a specialized agent (e.g., `@security-specialist`), it loads the agent definition, relevant skills, and applicable domain rules to provide expert-level guidance.
  315. ### Configuration Files
  316. | File | Purpose |
  317. |------|---------|
  318. | `.claude/CLAUDE.md` | Main instructions for Claude Code β€” imports `AGENTS.md` and sets project context |
  319. | `.claude/settings.json` | Claude project settings (permissions, model preferences) |
  320. | `.codex/config.toml` | Codex project configuration |
  321. | `.codex/agents/*.toml` | Codex agent role definitions with system prompts |
  322. | `AGENTS.md` | Shared instructions read by all AI coding agents (Codex, Gemini CLI, etc.) |
  323. | `AGENTIC_INFRA.md` | Full documentation of the agentic infrastructure |
  324. ## Architecture
  325. ### High-Level Overview
  326. ```mermaid
  327. graph TD
  328. subgraph Repository["AI Coding Tools Repository"]
  329. direction TB
  330. subgraph Orchestrator["orchestrator/"]
  331. O_CLI["CLI Shell"]
  332. O_UI["Web UI<br/>Nuxt 3 + Flask + Socket.IO"]
  333. O_CORE["Core Engine<br/>Workflow Manager<br/>Task Manager"]
  334. O_ADAPT["Adapters<br/>Claude | Codex | Gemini<br/>Copilot | Ollama | llama.cpp"]
  335. O_RESIL["Resilience<br/>Retry | Fallback | Offline"]
  336. O_OBS["Observability<br/>Prometheus | Logging | Health"]
  337. O_SEC["Security Module<br/>Validation | Rate Limiting | Audit"]
  338. O_INFRA["Infra<br/>Cache | Async Executor | Config Manager"]
  339. O_CONF["orchestrator/config/agents.yaml"]
  340. end
  341. subgraph AgenticTeam["agentic_team/"]
  342. A_CLI["CLI REPL"]
  343. A_UI["Web UI<br/>Nuxt 3 + Flask + Socket.IO"]
  344. A_ENGINE["Engine<br/>Free Communication<br/>Lead-Gated Output"]
  345. A_ADAPT["Adapters<br/>Claude | Codex | Gemini<br/>Copilot | Ollama | llama.cpp"]
  346. A_FALLBACK["Fallback + Offline"]
  347. A_CONF["orchestrator/config/agents.yaml"]
  348. end
  349. subgraph Collaboration["AI-Collaboration-Skills/ β€” standalone"]
  350. C_HOOKS["Native Lifecycle Hooks"]
  351. C_CORE["Provider-neutral Core<br/>Tasks | Sessions | Events"]
  352. C_STORE["Private Local State<br/>SQLite + gzip Objects"]
  353. C_ACTIVE["Resume Surfaces<br/>Skills | CLI | 10 MCP Tools"]
  354. end
  355. end
  356. O_CLI --> O_CORE
  357. O_UI --> O_CORE
  358. O_CORE --> O_ADAPT
  359. O_CORE --> O_RESIL
  360. O_CORE --> O_OBS
  361. O_CORE --> O_SEC
  362. O_CORE --> O_INFRA
  363. O_ADAPT --> ExtCloud["Cloud CLIs<br/>claude | codex | gemini | copilot"]
  364. O_ADAPT --> ExtLocal["Local Backends<br/>Ollama | llama.cpp"]
  365. A_CLI --> A_ENGINE
  366. A_UI --> A_ENGINE
  367. A_ENGINE --> A_ADAPT
  368. A_ENGINE --> A_FALLBACK
  369. A_ADAPT --> ExtCloud
  370. A_ADAPT --> ExtLocal
  371. ExtCloud --> C_HOOKS
  372. CursorIDE["Cursor IDE"] --> C_HOOKS
  373. C_HOOKS --> C_CORE
  374. C_CORE --> C_STORE
  375. C_STORE --> C_ACTIVE
  376. style Orchestrator fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
  377. style AgenticTeam fill:#1a2e1a,stroke:#162e16,color:#e0e0e0
  378. style Collaboration fill:#2e241a,stroke:#4a321f,color:#e0e0e0
  379. ```
  380. The diagram shows co-location, not a runtime dependency: AI Collaboration observes supported agent hosts directly and writes only to its own local store. It does not call into the Orchestrator or Agentic Team, and neither execution runtime needs the plugin installed.
  381. ### Orchestrator Workflow Execution
  382. The Orchestrator processes tasks through a configurable pipeline of AI agents. Each step in a workflow maps to a specific agent and role.
  383. ```mermaid
  384. sequenceDiagram
  385. participant User
  386. participant CLI as CLI / Web UI
  387. participant Engine as Core Engine
  388. participant WF as Workflow Manager
  389. participant Codex as Codex Adapter
  390. participant Gemini as Gemini Adapter
  391. participant Claude as Claude Adapter
  392. participant FB as Fallback Manager
  393. User->>CLI: Submit task
  394. CLI->>Engine: execute(task, workflow="default")
  395. Engine->>WF: load workflow steps
  396. WF->>Codex: Step 1 -- implement
  397. alt Codex unavailable
  398. Codex-->>FB: error
  399. FB->>FB: route to local-code
  400. end
  401. Codex-->>WF: implementation
  402. WF->>Gemini: Step 2 -- review
  403. Gemini-->>WF: review feedback
  404. WF->>Claude: Step 3 -- refine
  405. Claude-->>WF: refined code
  406. WF-->>Engine: final result
  407. Engine-->>CLI: display output
  408. CLI-->>User: code + report
  409. ```
  410. ### Agentic Team Communication Flow
  411. The Agentic Team uses free role-to-role communication. Agents speak in turns, address each other by role, and the team lead decides when the task is complete.
  412. ```mermaid
  413. sequenceDiagram
  414. participant User
  415. participant PM as Project Manager (Lead)
  416. participant Arch as Software Architect
  417. participant Dev as Software Developer
  418. participant QA as QA Engineer
  419. participant DevOps as DevOps Engineer
  420. User->>PM: "Build a REST API with auth"
  421. PM->>Arch: Define architecture and constraints
  422. Arch->>Dev: Provide interface specs
  423. Dev->>Dev: Implement code
  424. Dev->>QA: Request quality review
  425. QA->>Dev: Report edge cases
  426. Dev->>Dev: Fix issues
  427. Dev->>DevOps: Request deployment review
  428. DevOps->>PM: Confirm operational readiness
  429. PM->>User: Final consolidated response
  430. ```
  431. ### Adapter Resolution Flow
  432. Both systems resolve which AI backend to use at runtime. The adapter layer abstracts cloud CLIs and local model servers behind a common interface.
  433. ```mermaid
  434. flowchart TD
  435. REQ[Incoming Task Step] --> CHECK{Agent Enabled?}
  436. CHECK -->|Yes| HEALTH{Health Check}
  437. CHECK -->|No| SKIP[Skip Agent]
  438. HEALTH -->|Healthy| EXEC[Execute via Adapter]
  439. HEALTH -->|Unhealthy| FB{Fallback Configured?}
  440. FB -->|Yes| LOCAL[Route to Local Adapter<br/>Ollama / llama.cpp]
  441. FB -->|No| ERR[Raise AgentUnavailableError]
  442. EXEC --> PARSE[Parse CLI Output]
  443. LOCAL --> PARSE
  444. PARSE --> RESULT[Return AgentResponse]
  445. style EXEC fill:#2b6cb0,stroke:#2c5282,color:#fff
  446. style LOCAL fill:#276749,stroke:#22543d,color:#fff
  447. style ERR fill:#9b2c2c,stroke:#742a2a,color:#fff
  448. ```
  449. ### Local model execution semantics and limitation
  450. Local models are deeply integrated for routing, offline mode, and fallback, but they are **not direct workspace editors** in the current implementation.
  451. | Path | How it runs | Direct file edits |
  452. |---|---|---|
  453. | Cloud CLI adapters (Codex/Claude/Gemini/Copilot) | CLI process + workspace execution path | Yes (tool-dependent) |
  454. | Local adapters (Ollama/llama.cpp/OpenAI-compatible) | HTTP prompt-completion (`/api/generate` or `/v1/completions`) | No (text output only) |
  455. Best use for local models: offline drafting, review feedback, and cloud-to-local fallback continuity.
  456. > [!CAUTION]
  457. > While it is possible to make local LLMs directly edit files (e.g., via a `file-editor` tool), this approach is currently disabled to prevent unintended destructive changes. Local adapters are advisory β€” they provide text output that the Orchestrator can use to inform the next steps, but they do not have direct write access to the workspace. This design choice prioritizes safety and predictability while still leveraging local models for their strengths in drafting and feedback. The hard part is not feasibility, it’s safety and reliability: permissions, diff constraints, validation/tests before write, rollback, and preventing bad edits.
  458. ### Technology Stack Overview
  459. ```mermaid
  460. graph LR
  461. subgraph Backend
  462. PY[Python 3.8+]
  463. FL[Flask 3.x]
  464. SIO[Socket.IO 4.x]
  465. PD[Pydantic 2.x]
  466. CL[Click 8.x]
  467. end
  468. subgraph Frontend
  469. VUE[Vue 3]
  470. NUXT[Nuxt 3]
  471. TW[Tailwind CSS 3.x]
  472. MON[Monaco Editor]
  473. PIN[Pinia]
  474. end
  475. subgraph Observability
  476. PROM[Prometheus]
  477. GRAF[Grafana]
  478. SL[structlog]
  479. end
  480. subgraph Infrastructure
  481. DOCK[Docker]
  482. K8S[Kubernetes]
  483. TF[Terraform]
  484. end
  485. PY --> FL --> SIO
  486. PY --> PD
  487. PY --> CL
  488. VUE --> NUXT --> TW
  489. VUE --> MON
  490. VUE --> PIN
  491. PROM --> GRAF
  492. DOCK --> K8S
  493. style Backend fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
  494. style Frontend fill:#1a2e1a,stroke:#162e16,color:#e0e0e0
  495. style Observability fill:#2e1a1a,stroke:#2e1616,color:#e0e0e0
  496. style Infrastructure fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
  497. ```
  498. ## System Comparison
  499. Each top-level system is independently useful. Choose the smallest runtime that solves the problem:
  500. | Need | Best fit | Why |
  501. |---|---|---|
  502. | Run a repeatable multi-agent implementation/review pipeline | **Orchestrator** | Executes ordered or dynamically planned workflow steps through configured adapters |
  503. | Let role-based agents discuss a problem until a lead accepts the result | **Agentic Team** | Provides turn-based, free-form team communication and lead-gated completion |
  504. | Continue the same coding task across Claude, Codex, Cursor, Gemini, or Copilot | **AI Collaboration** | Installs directly into agent hosts and preserves local task history without either runtime |
  505. | Build a searchable structural model of a repository | **Graphify** | Extracts code entities and relationships into a queryable knowledge graph |
  506. | Expose orchestrator and project-analysis operations to MCP clients | **MCP Server** | Publishes the repository's 34+ automation and analysis tools |
  507. | Explore graph memory visually | **Context Dashboard** | Aggregates the independent runtime context stores into an interactive UI |
  508. ### Orchestrator vs. Agentic Team
  509. The two execution runtimes serve different collaboration models:
  510. | Dimension | Orchestrator (`orchestrator/`) | Agentic Team (`agentic_team/`) |
  511. |---|---|---|
  512. | **Collaboration model** | Step-based pipeline (sequential) | Free role-to-role communication (turns) |
  513. | **Agent identity** | Tool names (codex, gemini, claude) | Roles (PM, Architect, Developer, QA, DevOps) |
  514. | **Control flow** | Dynamic metrics-based planner or workflow YAML step order | Team lead (PM) gates completion dynamically |
  515. | **When to use** | Dynamic planning, or repeatable pipelines: implement, review, refine | Open-ended tasks needing discussion and consensus |
  516. | **CLI entry point** | `ai-orchestrator shell` | `ai-orchestrator agentic-shell` |
  517. | **Web UI port** | `:5001` | `:5002` |
  518. | **Config file** | `orchestrator/config/agents.yaml` | `agentic_team/config/agents.yaml` |
  519. | **Built-in workflows** | Dynamic planner (metrics-based routing), plus 7 static (default, quick, thorough, review-only, document, offline-default, hybrid) | N/A (turn-based, no fixed pipeline) |
  520. | **Fallback strategy** | Per-step cloud-to-local routing | Independent fallback manager |
  521. | **Observability** | Prometheus metrics, structured logging, health probes, report generation | Health and readiness probes |
  522. | **Security module** | Input validation, rate limiting, audit logging | N/A (inherits from adapter layer) |
  523. | **Shared code** | None | None |
  524. ## Feature Highlights
  525. ### Orchestrator (`orchestrator/`)
  526. | Category | Features |
  527. |---|---|
  528. | **Workflows** | 7 built-in workflows (default, quick, thorough, review-only, document, offline-default, hybrid); define custom ones in YAML |
  529. | **Agents** | Claude, Codex, Gemini, Copilot (cloud); Ollama, llama.cpp (local) |
  530. | **CLI** | Interactive REPL shell, one-shot commands, context-aware follow-ups, readline support |
  531. | **Web UI** | Nuxt 3 + Vue 3 frontend, Flask + Socket.IO backend, Monaco code editor, Pinia state management |
  532. | **Local model behavior** | Local adapters are advisory (text output); direct file edits come from CLI-backed agents |
  533. | **Resilience** | Retry with exponential backoff, circuit breakers, cloud-to-local fallback, offline detection |
  534. | **Observability** | Prometheus metrics, structured logging via structlog, health and readiness probes |
  535. | **Reports** | Execution summaries, agent performance, workflow analytics, config audits, HTML dashboard with Chart.js charts |
  536. | **Security** | Input validation, rate limiting, secret management, audit logging |
  537. | **Infra** | Async executor, response caching, connection pooling, config manager |
  538. ### Agentic Team (`agentic_team/`)
  539. | Category | Features |
  540. |---|---|
  541. | **Runtime** | Free role-to-role communication, configurable turn limits, lead-gated final responses |
  542. | **Roles** | Project Manager, Software Architect, Software Developer, QA Engineer, DevOps Engineer |
  543. | **CLI** | Dedicated REPL (`agentic-shell`) with `--max-turns` and `--offline` flags |
  544. | **Web UI** | Dedicated Nuxt 3 + Flask UI with Config Studio, real-time turn streaming, team communication view |
  545. | **Local model behavior** | Local adapters contribute role outputs and fallback text, but do not directly write files |
  546. | **Fallback** | Independent fallback manager and offline detector |
  547. | **Configuration** | Separate `agents.yaml` with `agentic_team.roles` section for role-to-agent mapping |
  548. ### AI Collaboration (`AI-Collaboration-Skills/`)
  549. AI Collaboration is for developers who already work inside one or more coding agents and want continuity without adopting a new orchestration runtime. It can capture work passively during ordinary agent sessions, then expose only the relevant history when another agent resumes the task.
  550. | Category | Features |
  551. |---|---|
  552. | **Continuity** | Tasks, provider sessions, normalized events, checkpoints, test history, and live Git state |
  553. | **Hosts** | Claude Code, Codex, Cursor, Gemini CLI, and GitHub Copilot CLI |
  554. | **Portable layer** | Agent Plugins 1.0 manifest, five Agent Skills, and ten MCP tools |
  555. | **Passive capture** | Host-native lifecycle hooks with fail-open behavior and no model invocation |
  556. | **Storage** | Private local SQLite store plus SHA-256 content-addressed gzip objects |
  557. | **Privacy** | Recursive credential redaction, payload size bounds, no network service |
  558. | **Boundary** | Zero imports from `orchestrator/`, `agentic_team/`, or the root MCP server |
  559. Typical uses include:
  560. - hand off implementation from Claude Code to Codex for debugging, then to Cursor for UI work;
  561. - recover the current task, changed files, last checkpoint, and failing tests after a context-window reset;
  562. - search prior tool activity without injecting an entire transcript into the next model context;
  563. - create deliberate checkpoints before switching agents, machines, or work sessions;
  564. - retain a private, inspectable local event history with no hosted synchronization service.
  565. See [`AI-Collaboration-Skills/README.md`](AI-Collaboration-Skills/README.md) for installation and usage.
  566. ### Graphify (`graphify/`)
  567. | Category | Features |
  568. |---|---|
  569. | **Analysis** | Python AST (classes, functions, imports, calls, decorators, docstrings), JS/TS, Go, Rust, Java, C++, Markdown, YAML/JSON/TOML |
  570. | **Graph** | SQLite + FTS5, WAL mode, schema migrations (v1β†’v2β†’v3), thread-local connections, context manager |
  571. | **Search** | Full-text search, node explanation, path finding (BFS), community detection, god node analysis, complexity hotspots |
  572. | **Cache** | SHA-256 content-addressable cache, incremental scans (only changed files) |
  573. | **Export** | JSON, DOT (Graphviz), Markdown, GraphML, interactive HTML (vis.js), **Obsidian vault** |
  574. | **API** | Flask REST API with CORS, structured error handling, metrics/snapshot/diff endpoints |
  575. | **Operations** | File watching (watchdog + polling), graph snapshots & diffing, scan metrics collection |
  576. | **Security** | Path traversal protection, input sanitization, bounded parameters, no debug mode |
  577. ## Quick Start
  578. ### Use AI Collaboration Only (Minimal Setup)
  579. If you want cross-agent continuity rather than a complete orchestration platform, use the standalone plugin directly. It has no dependency on the root `requirements.txt`.
  580. ```bash
  581. git clone https://github.com/hoangsonww/AI-Agents-Orchestrator.git
  582. cd AI-Agents-Orchestrator
  583. # Example: install into Codex from the local plugin marketplace
  584. codex plugin marketplace add ./AI-Collaboration-Skills
  585. codex plugin add ai-collaboration@ai-collaboration
  586. # Start a continuity task from the repository you are editing
  587. cd /path/to/your-project
  588. /path/to/AI-Agents-Orchestrator/AI-Collaboration-Skills/bin/ai-collaboration \
  589. task start "Implement account recovery"
  590. ```
  591. The plugin begins recording supported lifecycle events locally. Open another supported agent in the same repository and invoke the `resume-task` skill or call `ai_collaboration.get_context`; both agents resolve the same active task from `~/.ai-collaboration/`.
  592. Claude Code, Cursor, Gemini CLI, and GitHub Copilot CLI installation commands are documented in [`AI-Collaboration-Skills/README.md`](AI-Collaboration-Skills/README.md#install-from-this-repository).
  593. ### Prerequisites
  594. - **Operating System**: Linux, macOS, or Windows (WSL recommended)
  595. - **Python**: 3.8 or higher
  596. - **Node.js**: 20+ (for Web UI)
  597. - **Memory**: Minimum 4GB RAM
  598. - **Disk Space**: 1GB for installation + workspace
  599. - **Network**: Required for AI CLI tools and updates
  600. - **Claude Code**: Installed, setup, and signed in on your machine (Required for any workflows using Claude Code - if you run `claude` in terminal and it works, you're good)
  601. - **OpenAI Codex**: Installed and authenticated (if using Codex agent, try running `codex` and see if it responds)
  602. - **Google Gemini CLI**: Installed and authenticated (if using Gemini agent, try `gemini --version` to verify)
  603. - **GitHub Copilot CLI**: Installed and authenticated (if using Copilot agent, try `copilot --version` to verify)
  604. - **Llama.cpp or Ollama**: If using local LLM agents, ensure they are installed and configured properly (try running `ollama list` or `llamacpp --help` to verify)
  605. - **Optional**: Docker and Docker Compose for containerized setup
  606. ### Install
  607. ```bash
  608. git clone https://github.com/hoangsonww/AI-Agents-Orchestrator.git
  609. cd AI-Agents-Orchestrator
  610. python3 -m venv venv
  611. source venv/bin/activate # Windows: venv\Scripts\activate
  612. pip install -r requirements.txt
  613. chmod +x ai-orchestrator
  614. ```
  615. ### Run the Orchestrator
  616. ```bash
  617. # Interactive shell
  618. ./ai-orchestrator shell
  619. # One-shot task
  620. ./ai-orchestrator run "Create a Python REST API" --workflow default
  621. # Start the Web UI
  622. make run-ui
  623. # Then open http://localhost:5001
  624. ```
  625. ### Run the Agentic Team
  626. ```bash
  627. # Interactive REPL
  628. ./ai-orchestrator agentic-shell
  629. # With options
  630. ./ai-orchestrator agentic-shell --max-turns 16 --offline
  631. # Start the Web UI
  632. make run-agentic-ui
  633. # Then open http://localhost:5002
  634. ```
  635. ### Verify Installation
  636. ```bash
  637. ./ai-orchestrator --help # Show all commands
  638. ./ai-orchestrator agents # List available agents
  639. ./ai-orchestrator workflows # List available workflows
  640. ./ai-orchestrator validate # Validate configuration
  641. ```
  642. ## Project Structure
  643. ```
  644. AI-Coding-Tools/
  645. |
  646. |-- .claude/ # Claude Code agentic infrastructure
  647. | |-- CLAUDE.md # Main Claude instructions (imports AGENTS.md)
  648. | |-- settings.json # Project settings and permissions
  649. | |-- agents/ # 11 specialized agent definitions
  650. | | |-- web-frontend.md
  651. | | |-- backend-api.md
  652. | | |-- security-specialist.md
  653. | | |-- devops-infrastructure.md
  654. | | |-- ai-ml-engineer.md
  655. | | |-- database-architect.md
  656. | | |-- mobile-developer.md
  657. | | |-- performance-engineer.md
  658. | | |-- documentation-writer.md
  659. | | |-- code-reviewer.md
  660. | | +-- test-runner.md
  661. | |-- skills/ # 23 reusable skill templates
  662. | | |-- development/ # 6 skills (react, REST, async, DB, GraphQL, errors)
  663. | | |-- testing/ # 4 skills (unit, integration, TDD, perf)
  664. | | |-- security/ # 4 skills (validation, auth, secure-coding, vuln)
  665. | | |-- devops/ # 3 skills (Docker, CI/CD, K8s)
  666. | | |-- ai-ml/ # 3 skills (embeddings, LLM, RAG)
  667. | | |-- documentation/ # 3 skills (API docs, arch docs, code docs)
  668. | | |-- generate-reports/ # Standalone: report generation
  669. | | |-- health-check/ # Standalone: system health checks
  670. | | |-- run-tests/ # Standalone: test suite execution
  671. | | +-- context-graph-builder/ # Standalone: context graph operations
  672. | +-- rules/ # 11 domain rule files
  673. | |-- adapters.md
  674. | |-- api-design.md
  675. | |-- testing.md
  676. | |-- performance.md
  677. | |-- config.md
  678. | |-- ai-ml.md
  679. | |-- observability.md
  680. | |-- frontend.md
  681. | |-- ci-cd.md
  682. | |-- security.md
  683. | +-- database.md
  684. |
  685. |-- .codex/ # Codex agentic infrastructure
  686. | |-- config.toml # Codex project configuration
  687. | |-- agents/ # 13 specialized agent definitions (.toml)
  688. | | |-- code-reviewer.toml
  689. | | |-- explorer.toml
  690. | | |-- security-specialist.toml
  691. | | |-- web-frontend.toml
  692. | | |-- devops-infrastructure.toml
  693. | | |-- implementer.toml
  694. | | |-- database-architect.toml
  695. | | |-- performance-engineer.toml
  696. | | |-- test-runner.toml
  697. | | |-- ai-ml-engineer.toml
  698. | | |-- backend-api.toml
  699. | | |-- documentation-writer.toml
  700. | | +-- mobile-developer.toml
  701. | |-- hooks/ # Git hook integrations
  702. | +-- rules/ # Codex-specific rules
  703. |
  704. |-- AI-Collaboration-Skills/ # Standalone cross-agent task continuity plugin
  705. | |-- plugin.json # Agent Plugins 1.0 portable manifest
  706. | |-- mcp.json # Portable stdio MCP server
  707. | |-- skills/ # Resume, history, status, checkpoint, handoff
  708. | |-- adapters/ # Claude, Codex, and Cursor native hooks/config
  709. | |-- ai_collaboration/ # Dependency-free Python core
  710. | |-- hooks/ # Shared ingest dispatcher + Gemini hooks
  711. | |-- com.github.copilot/ # Copilot-specific lifecycle hooks
  712. | +-- tests/ # Standalone continuity test suite
  713. |
  714. |-- mcp_server/ # MCP server (FastMCP 3.x) β€” 34+ tools
  715. | |-- server.py # Server entry point + core tools
  716. | |-- engines.py # Engine adapters for both systems
  717. | |-- repl.py # Interactive REPL mode
  718. | |-- tools/ # Tool modules by category
  719. | | |-- orchestrator_tools.py # Orchestrator execution tools
  720. | | |-- agentic_team_tools.py # Agentic team execution tools
  721. | | |-- shared_tools.py # Shared utility tools
  722. | | |-- code_analysis.py # 4 code analysis tools
  723. | | |-- security_tools.py # 4 security scanning tools
  724. | | |-- testing_tools.py # 4 testing tools
  725. | | |-- devops_tools.py # 5 DevOps tools
  726. | | +-- context_tools.py # 7 context memory tools
  727. | +-- resources/ # MCP resource definitions
  728. |
  729. |-- orchestrator/ # Self-contained orchestrator system
  730. | |-- __init__.py
  731. | |-- adapters/ # AI agent adapters
  732. | | |-- base.py # Abstract base adapter
  733. | | |-- claude_adapter.py # Claude Code CLI
  734. | | |-- codex_adapter.py # OpenAI Codex CLI
  735. | | |-- gemini_adapter.py # Google Gemini CLI
  736. | | |-- copilot_adapter.py # GitHub Copilot CLI
  737. | | |-- ollama_adapter.py # Ollama local models
  738. | | |-- llama_cpp_adapter.py # llama.cpp / OpenAI-compatible
  739. | | +-- cli_communicator.py # Robust CLI subprocess handling
  740. | |-- core/ # Core orchestration logic
  741. | | |-- engine.py # Main orchestration engine
  742. | | |-- workflow.py # Workflow definitions and runner
  743. | | |-- task_manager.py # Task lifecycle management
  744. | | +-- exceptions.py # Custom exception hierarchy
  745. | |-- resilience/ # Fault tolerance
  746. | | |-- retry.py # Retry with exponential backoff
  747. | | |-- fallback.py # Cloud-to-local fallback routing
  748. | | +-- offline.py # Offline detection
  749. | |-- observability/ # Monitoring, logging, and reports
  750. | | |-- metrics.py # Prometheus metrics
  751. | | |-- logging_config.py # Structured logging setup
  752. | | |-- health.py # Health and readiness probes
  753. | | +-- report_generator.py # Execution, performance, and HTML reports
  754. | |-- security_module/ # Security layer
  755. | | +-- security.py # Validation, rate limiting, audit
  756. | |-- infra/ # Infrastructure utilities
  757. | | |-- cache.py # Response caching
  758. | | |-- async_executor.py # Async task execution
  759. | | +-- config_manager.py # Configuration loading
  760. | |-- cli/ # CLI interface
  761. | | +-- shell.py # Interactive REPL shell
  762. | |-- context/ # Graph-based context memory
  763. | | |-- memory_manager.py # High-level memory API
  764. | | |-- models/ # Node and edge schemas
  765. | | | +-- schemas.py
  766. | | |-- store/ # Graph persistence layer
  767. | | | +-- graph_store.py
  768. | | |-- search/ # Search engines
  769. | | | |-- bm25_index.py # BM25 keyword search
  770. | | | |-- embeddings.py # Embedding generation
  771. | | | |-- hybrid_search.py # Hybrid BM25 + semantic
  772. | | | +-- advanced_search.py # Advanced query support
  773. | | +-- ops/ # Operational utilities
  774. | | |-- analytics.py # Graph analytics
  775. | | |-- export.py # Data export
  776. | | |-- pruning.py # Node/edge pruning
  777. | | |-- versioning.py # Version tracking
  778. | | +-- project_scanner.py # Project directory scanning
  779. | |-- config/
  780. | | +-- agents.yaml # Agents, workflows, settings
  781. | |-- ui/ # Web UI
  782. | | |-- app.py # Flask + Socket.IO backend
  783. | | |-- frontend/ # Nuxt 3 + Vue 3 + Tailwind
  784. | | |-- static/
  785. | | +-- templates/
  786. | +-- README.md # Orchestrator-specific docs
  787. |
  788. |-- agentic_team/ # Self-contained agentic team system
  789. | |-- __init__.py
  790. | |-- engine.py # Role-based communication engine
  791. | |-- shell.py # Agentic team REPL
  792. | |-- decision_parser.py # Turn decision parsing
  793. | |-- config_utils.py # Config loading utilities
  794. | |-- constants.py # Shared constants
  795. | |-- fallback.py # Independent fallback manager
  796. | |-- offline.py # Independent offline detector
  797. | |-- adapters/ # Own copy of AI agent adapters
  798. | | |-- base.py
  799. | | |-- claude_adapter.py
  800. | | |-- codex_adapter.py
  801. | | |-- gemini_adapter.py
  802. | | |-- copilot_adapter.py
  803. | | |-- ollama_adapter.py
  804. | | |-- llama_cpp_adapter.py
  805. | | +-- cli_communicator.py
  806. | |-- context/ # Independent graph-based context memory
  807. | | |-- memory_manager.py # High-level memory API
  808. | | |-- models/ # Node and edge schemas
  809. | | |-- store/ # Graph persistence layer
  810. | | |-- search/ # BM25 + FTS5 hybrid search
  811. | | +-- ops/ # Analytics, export, pruning, project scanning
  812. | |-- config/
  813. | | +-- agents.yaml # Agents, roles, team settings
  814. | |-- ui/ # Dedicated Web UI
  815. | | |-- app.py # Flask + Socket.IO backend
  816. | | |-- frontend/ # Nuxt 3 + Vue 3 + Tailwind
  817. | | |-- static/
  818. | | +-- templates/
  819. | +-- README.md # Agentic team-specific docs
  820. |
  821. |-- tests/ # Unified test suite
  822. | |-- conftest.py
  823. | |-- test_orchestrator.py
  824. | |-- test_adapters.py
  825. | |-- test_adapter_execution.py
  826. | |-- test_agentic_team_engine.py
  827. | |-- test_agentic_ui_backend.py
  828. | |-- test_integration.py
  829. | |-- test_functional_e2e.py
  830. | |-- test_enterprise_hardening.py
  831. | |-- test_production_hardening.py
  832. | +-- ...
  833. |
  834. |-- reports/ # Generated reports (JSON + HTML dashboard)
  835. | |-- INDEX.json # Report catalog
  836. | |-- exec_*.json # Per-task execution summaries
  837. | |-- perf_*.json # Agent performance analytics
  838. | |-- workflow_*.json # Workflow-level analytics
  839. | |-- health_*.json # System health snapshots
  840. | |-- config_*.json # Configuration audits
  841. | +-- dashboard_*.html # Interactive HTML dashboard with charts
  842. |
  843. |-- deployment/ # Deployment configurations
  844. | |-- kubernetes/
  845. | |-- azure/
  846. | |-- systemd/
  847. | |-- load-balancer/
  848. | +-- scripts/
  849. |
  850. |-- docs/ # Documentation
  851. | |-- images/ # Screenshots
  852. | |-- orchestrator-architecture.md
  853. | |-- orchestrator-api-reference.md
  854. | |-- agentic-team-architecture.md
  855. | |-- agentic-team-api-reference.md
  856. | |-- configuration-guide.md
  857. | |-- testing-guide.md
  858. | |-- security.md
  859. | +-- offline-mode.md
  860. |
  861. |-- examples/ # Usage examples
  862. | |-- orchestrator/
  863. | +-- agentic_team/
  864. |
  865. |-- context_dashboard/ # Unified context visualization (port 5003)
  866. | |-- app.py # Flask app aggregating both context stores
  867. | |-- templates/
  868. | | +-- dashboard.html # Interactive graph visualization
  869. | +-- README.md # Dashboard-specific docs
  870. |
  871. |-- scripts/ # Helper scripts
  872. | |-- install.sh
  873. | |-- start-ui.sh
  874. | |-- start-agentic-ui.sh
  875. | |-- start-mcp-server.sh
  876. | |-- start-all.sh
  877. | |-- seed_context_graphs.py
  878. | |-- health-check.sh
  879. | |-- format.sh
  880. | |-- lint.sh
  881. | +-- test.sh
  882. |
  883. |-- ai-orchestrator # Main CLI entry point
  884. |-- Dockerfile # Multi-stage production image
  885. |-- docker-compose.yml # Both UIs + monitoring stack
  886. |-- Makefile # Development commands
  887. |-- pyproject.toml # Project metadata and tool config
  888. |-- requirements.txt # Python dependencies
  889. |-- AGENTS.md # Shared instructions for all AI coding agents
  890. |-- AGENTIC_INFRA.md # Full agentic infrastructure documentation
  891. |-- SETUP.md # Installation and setup guide
  892. |-- ARCHITECTURE.md
  893. |-- FEATURES.md
  894. |-- AGENTIC_TEAM.md
  895. |-- OFFLINE_MODE.md
  896. |-- DEPLOYMENT.md
  897. +-- LICENSE
  898. ```
  899. > [!IMPORTANT]
  900. > **Key design decision:** `orchestrator/` and `agentic_team/` are fully self-contained. Each carries its own `adapters/`, `config/`, and `ui/` directories. There are no shared root-level `adapters/`, `ui/`, or `config/` directories. The two systems share zero code and zero imports.
  901. ## Configuration
  902. Both systems read their configuration from their own `orchestrator/config/agents.yaml` file. The files follow the same schema but are independent.
  903. ```mermaid
  904. graph LR
  905. subgraph Orchestrator Config
  906. OC["orchestrator/config/agents.yaml"]
  907. OC --> OA["agents: codex, gemini, claude, ..."]
  908. OC --> OW["workflows: default, quick, thorough, ..."]
  909. OC --> OS["settings: max_iterations, output_dir, ..."]
  910. OC --> OAT["agentic_team: roles (shared schema)"]
  911. end
  912. subgraph Agentic Team Config
  913. AC["agentic_team/config/agents.yaml"]
  914. AC --> AA["agents: codex, gemini, claude, ..."]
  915. AC --> AW["workflows: (same schema)"]
  916. AC --> AS["settings: (same schema)"]
  917. AC --> AAT["agentic_team: lead_role, max_turns, roles"]
  918. end
  919. style OC fill:#2d3748,stroke:#4a5568,color:#e2e8f0
  920. style AC fill:#22543d,stroke:#276749,color:#e2e8f0
  921. ```
  922. ### Available Workflows
  923. | Workflow | Pipeline | Use Case |
  924. |---|---|---|
  925. | `default` | Codex --> Gemini --> Claude | Production-quality code with full review |
  926. | `quick` | Codex only | Fast prototyping |
  927. | `thorough` | Codex --> Copilot --> Gemini --> Claude --> Gemini | Mission-critical code |
  928. | `review-only` | Gemini --> Claude | Analyzing existing code |
  929. | `document` | Claude --> Gemini | Documentation generation |
  930. | `offline-default` | local-code --> local-instruct | Local-only, no cloud dependency |
  931. | `hybrid` | local-code --> Claude (fallback: local-instruct) | Local drafts with cloud review |
  932. ## Deployment
  933. ### Docker Compose (Recommended)
  934. Both systems are packaged in a single multi-stage Docker image. The `docker-compose.yml` runs each as a separate service.
  935. ```mermaid
  936. graph TD
  937. subgraph Docker Compose
  938. direction TB
  939. OUI["orchestrator-ui<br/>:5001"]
  940. AUI["agentic-team-ui<br/>:5002"]
  941. PROM["prometheus<br/>:9091<br/>(monitoring profile)"]
  942. GRAF["grafana<br/>:3000<br/>(monitoring profile)"]
  943. end
  944. OUI --> SHARED_VOL["Shared Volumes<br/>output/ workspace/ logs/ sessions/"]
  945. AUI --> SHARED_VOL
  946. PROM --> OUI
  947. PROM --> AUI
  948. GRAF --> PROM
  949. style OUI fill:#2b6cb0,stroke:#2c5282,color:#fff
  950. style AUI fill:#276749,stroke:#22543d,color:#fff
  951. style PROM fill:#c05621,stroke:#9c4221,color:#fff
  952. style GRAF fill:#6b46c1,stroke:#553c9a,color:#fff
  953. ```
  954. ```bash
  955. # Start both UIs
  956. docker compose up --build -d
  957. # Start with monitoring (Prometheus + Grafana)
  958. docker compose --profile monitoring up --build -d
  959. # Stop everything
  960. docker compose down
  961. ```
  962. ### Kubernetes
  963. ```bash
  964. kubectl create namespace ai-coding-tools
  965. kubectl apply -f deployment/kubernetes/
  966. kubectl get pods -n ai-coding-tools
  967. ```
  968. See [DEPLOYMENT.md](DEPLOYMENT.md) for systemd, Azure, load balancer, and production hardening guides.
  969. ## Testing
  970. The unified test suite (386 tests across 60+ modules) covers both systems independently.
  971. ```mermaid
  972. flowchart LR
  973. subgraph "make all"
  974. FMT[format<br/>black + isort] --> LINT[lint<br/>flake8 + pylint]
  975. LINT --> TYPE[type-check<br/>mypy]
  976. TYPE --> TEST[test<br/>314 tests]
  977. TEST --> SEC[security<br/>bandit + safety]
  978. end
  979. subgraph "Test Targets"
  980. TEST --> T_ORCH[test-orchestrator]
  981. TEST --> T_AGENT[test-agentic]
  982. TEST --> T_UNIT[test-unit]
  983. TEST --> T_INT[test-integration]
  984. TEST --> T_E2E[test-e2e]
  985. end
  986. style FMT fill:#2b6cb0,stroke:#2c5282,color:#fff
  987. style TEST fill:#276749,stroke:#22543d,color:#fff
  988. style SEC fill:#9b2c2c,stroke:#742a2a,color:#fff
  989. ```
  990. ```bash
  991. # Run all tests
  992. make test
  993. # Orchestrator tests only
  994. make test-orchestrator
  995. # Agentic team tests only
  996. make test-agentic
  997. # Unit tests only
  998. make test-unit
  999. # Integration tests only
  1000. make test-integration
  1001. # Tests with coverage report
  1002. make test-coverage
  1003. ```
  1004. ### Code Quality
  1005. The codebase maintains a **perfect 10.00/10 pylint score** with zero warnings across the entire project, enforced by 15 pre-commit hooks (black, isort, flake8, mypy, bandit, pyupgrade, and more).
  1006. | Metric | Value |
  1007. |--------|-------|
  1008. | **Pylint Score** | 10.00 / 10 |
  1009. | **Warnings** | 0 |
  1010. | **Tests Passing** | 386 |
  1011. | **Pre-commit Hooks** | 15 / 15 passing |
  1012. ```bash
  1013. make lint # Lint all Python source (flake8 + pylint)
  1014. make format # Format with black + isort
  1015. make type-check # Run mypy on both subsystems
  1016. make security # Run bandit + safety
  1017. make all # Run everything (format, lint, type-check, test, security)
  1018. ```
  1019. ## Monitoring
  1020. Prometheus metrics are exposed by the orchestrator UI backend on port 9090.
  1021. | Metric | Description |
  1022. |---|---|
  1023. | `orchestrator_tasks_total` | Total tasks executed |
  1024. | `orchestrator_task_duration_seconds` | Task execution time |
  1025. | `orchestrator_agent_calls_total` | Agent invocations |
  1026. | `orchestrator_agent_errors_total` | Agent error count |
  1027. | `orchestrator_cache_hits_total` | Cache performance |
  1028. ### Reports
  1029. The orchestrator automatically generates reports in `reports/` when `create_reports: true` is set in `agents.yaml`. Reports include:
  1030. | Report Type | Description |
  1031. |---|---|
  1032. | **Execution Summary** | Per-task results: steps, agents used, fallbacks, suggestions, duration |
  1033. | **Agent Performance** | Aggregated success rates, call counts, task type distribution |
  1034. | **Workflow Analytics** | Per-workflow run counts, success rates, average iterations |
  1035. | **System Health** | Health check results, disk/memory, Python version, platform |
  1036. | **Config Audit** | Agent availability, workflow structure, settings snapshot |
  1037. | **HTML Dashboard** | Interactive Chart.js dashboard with KPI cards, bar/line/doughnut charts |
  1038. Reports are also generated programmatically via:
  1039. ```python
  1040. from orchestrator.observability import ReportGenerator
  1041. gen = ReportGenerator(reports_dir="./reports")
  1042. gen.seed_reports(config=config) # Generate all report types with sample data
  1043. ```
  1044. Health checks:
  1045. - Orchestrator: `http://localhost:5001/health`, `http://localhost:5001/ready`
  1046. - Agentic Team: `http://localhost:5002/health`, `http://localhost:5002/ready`
  1047. ## Documentation
  1048. | Document | Description |
  1049. |------------------------------------------------------|------------------------------------------------------------------|
  1050. | **[SETUP.md](SETUP.md)** | Prerequisites, installation, environment setup, troubleshooting |
  1051. | **[ARCHITECTURE.md](ARCHITECTURE.md)** | System architecture and design patterns |
  1052. | **[FEATURES.md](FEATURES.md)** | Comprehensive feature documentation |
  1053. | **[AGENTIC_TEAM.md](AGENTIC_TEAM.md)** | Agentic team runtime details |
  1054. | **[OFFLINE_MODE.md](OFFLINE_MODE.md)** | Offline mode and local model guide |
  1055. | **[DEPLOYMENT.md](DEPLOYMENT.md)** | Docker, Kubernetes, systemd, Azure deployment |
  1056. | **[ADD_AGENTS.md](ADD_AGENTS.md)** | Guide for adding new AI agents |
  1057. | **[orchestrator/README.md](orchestrator/README.md)** | Orchestrator subsystem documentation |
  1058. | **[agentic_team/README.md](agentic_team/README.md)** | Agentic team subsystem documentation |
  1059. | **[AI-Collaboration-Skills/README.md](AI-Collaboration-Skills/README.md)** | Standalone cross-agent continuity installation and usage |
  1060. | **[AI-Collaboration-Skills/ARCHITECTURE.md](AI-Collaboration-Skills/ARCHITECTURE.md)** | Event model, storage, hooks, MCP, and host adapter design |
  1061. | **[docs/](docs/)** | API references, architecture deep-dives, testing guide, security |
  1062. ## Screenshots
  1063. Some screenshots of the Web UIs and CLI interfaces:
  1064. <p align="center">
  1065. <img src="docs/images/ui.png" alt="Orchestrator Web UI" width="100%"/>
  1066. <br/>
  1067. <em>Orchestrator Web UI β€” real-time task execution dashboard with agent status and workflow controls</em>
  1068. </p>
  1069. <p align="center">
  1070. <img src="docs/images/agentic-team.png" alt="Agentic Team Web UI" width="100%"/>
  1071. <br/>
  1072. <em>Agentic Team Web UI β€” role-based multi-agent collaboration with live communication view</em>
  1073. </p>
  1074. <p align="center">
  1075. <img src="docs/images/graph.png" alt="Context Graph Dashboard" width="100%"/>
  1076. <br/>
  1077. <em>Context Graph Dashboard β€” interactive knowledge graph visualization with node inspection and hybrid search</em>
  1078. </p>
  1079. <p align="center">
  1080. <img src="docs/images/cli.png" alt="Orchestrator CLI" width="100%"/>
  1081. <br/>
  1082. <em>Orchestrator CLI β€” command-line interface for task execution and agent management</em>
  1083. </p>
  1084. <p align="center">
  1085. <img src="docs/images/cli-3.png" alt="Agentic Shell REPL" width="100%"/>
  1086. <br/>
  1087. <em>Agentic Shell REPL β€” interactive shell for direct agent communication and debugging</em>
  1088. </p>
  1089. <p align="center">
  1090. <img src="docs/images/mcp.png" alt="MCP Tools REPL" width="100%"/>
  1091. <br/>
  1092. <em>MCP Tools REPL β€” interactive console for exploring and testing 34+ MCP tools across both engines</em>
  1093. </p>
  1094. ## MCP Server (Optional -- Model Context Protocol)
  1095. Both systems are optionally exposed via a [FastMCP](https://github.com/jlowin/fastmcp) server (`mcp_server/`, port 8000), letting any MCP-compatible client (Claude Desktop, other LLM agents, or custom Python scripts) drive task execution programmatically.
  1096. ```bash
  1097. # Start MCP server (stdio -- for Claude Desktop integration)
  1098. python -m mcp_server.server
  1099. # Start MCP server (HTTP -- for remote clients)
  1100. python -m mcp_server.server --transport http --port 8000
  1101. # Interactive REPL mode -- explore and test tools from the terminal
  1102. python -m mcp_server repl
  1103. # Launch the Context Dashboard (port 5003)
  1104. python -m context_dashboard
  1105. ```
  1106. ```mermaid
  1107. graph LR
  1108. subgraph "MCP Clients"
  1109. CD[Claude Desktop]
  1110. LA[LLM Agent]
  1111. PY[Python Client]
  1112. REPL[REPL Mode]
  1113. end
  1114. subgraph "MCP Server :8000 β€” 34+ Tools"
  1115. direction TB
  1116. CORE["Core (10)<br/>orchestrator_execute, agentic_team_execute,<br/>list_engines, health, config, validate"]
  1117. CODE["Code Analysis (4)<br/>code_complexity, find_patterns,<br/>analyze_deps, code_summary"]
  1118. SEC["Security (4)<br/>secrets_scan, security_headers_check,<br/>dependency_audit, injection_scan"]
  1119. TEST["Testing (4)<br/>suggest_tests, test_coverage_analysis,<br/>parse_tests, create_test_stub"]
  1120. DEVOPS["DevOps (5)<br/>dockerfile_analysis, compose_analysis,<br/>ci_config_check, deploy_checklist, env_config_analysis"]
  1121. CTX["Context (7)<br/>context_store_conversation, context_store_task,<br/>context_log_mistake, context_store_pattern,<br/>context_search, context_get_relevant, context_stats"]
  1122. end
  1123. subgraph "Engines"
  1124. O[Orchestrator :5001]
  1125. A[Agentic Team :5002]
  1126. D[Context Dashboard :5003]
  1127. end
  1128. CD & LA & PY & REPL -->|MCP Protocol| CORE & CODE & SEC & TEST & DEVOPS & CTX
  1129. CORE --> O & A
  1130. CTX --> D
  1131. ```
  1132. **34+ MCP tools** organized across 6 categories:
  1133. | Category | Count | Tools |
  1134. |----------|-------|-------|
  1135. | **Core Orchestration** | 10 | `orchestrator_execute`, `agentic_team_execute`, `list_engines`, `orchestrator_health`, `agentic_team_health`, `list_workflows`, `list_agents`, `validate_config`, `team_config`, `agentic_team_validate` |
  1136. | **Code Analysis** | 4 | `code_complexity`, `find_patterns`, `analyze_deps`, `code_summary` |
  1137. | **Security** | 4 | `secrets_scan`, `security_headers_check`, `dependency_audit`, `injection_scan` |
  1138. | **Testing** | 4 | `suggest_tests`, `test_coverage_analysis`, `parse_tests`, `create_test_stub` |
  1139. | **DevOps** | 5 | `dockerfile_analysis`, `compose_analysis`, `ci_config_check`, `deploy_checklist`, `env_config_analysis` |
  1140. | **Context Memory** | 7 | `context_store_conversation`, `context_store_task`, `context_log_mistake`, `context_store_pattern`, `context_search`, `context_get_relevant`, `context_stats` |
  1141. See [`mcp_server/tools/`](mcp_server/tools/) for the full tool implementations.
  1142. > [!TIP]
  1143. > The MCP server is entirely optional. Both the Orchestrator and Agentic Team work fully via their own CLIs and Web UIs without it. Use `python -m mcp_server repl` for an interactive REPL to explore and test tools from the terminal.
  1144. ## Contributing
  1145. Contributions are welcome. Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
  1146. 1. Fork the repository.
  1147. 2. Create a feature branch: `git checkout -b feature/your-feature`
  1148. 3. Make your changes and add tests.
  1149. 4. Run checks: `make all`
  1150. 5. Commit using [conventional commits](https://www.conventionalcommits.org/): `git commit -m "feat: add amazing feature"`
  1151. 6. Push and open a Pull Request.
  1152. ## Security
  1153. For security issues, please email hoangson091104@gmail.com. Do not open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the full security policy.
  1154. ## License
  1155. This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
  1156. ## Support
  1157. - **Maintainer**: [@hoangsonww](https://github.com/hoangsonww)
  1158. - **Issues**: [GitHub Issues](https://github.com/hoangsonww/AI-Agents-Orchestrator/issues)
  1159. - **Discussions**: [GitHub Discussions](https://github.com/hoangsonww/AI-Agents-Orchestrator/discussions)
  1160. ---
  1161. <div align="center">
  1162. **Made with care and love by [Son Nguyen](https://github.com/hoangsonww) for the AI development community πŸ€–**
  1163. [Back to Top](#ai-coding-tools-orchestrator-and-agentic-team-runtime)
  1164. > **Easter egg:** Go to our [wiki page](https://hoangsonww.github.io/AI-Agents-Orchestrator/) and enter Konami code (↑ ↑ ↓ ↓ ← β†’ ← β†’ B A) for a surprise!
  1165. </div>
.claude/settings.json Β· Bundled script Β· 39 lines Β· 1 finding marked
  1. {
  2. "permissions": {
  3. "allow": [
  4. "Bash(python -m pytest *)",
  5. "Bash(python3 -m pytest *)",
  6. "Bash(pip install *)",
  7. "Bash(pip3 install *)",
  8. "Bash(black *)",
  9. "Bash(isort *)",
  10. "Bash(flake8 *)",
  11. "Bash(mypy *)",
  12. "Bash(bandit *)",
  13. "Bash(python -m mcp_server*)",
  14. "Bash(python3 -m mcp_server*)",
  15. "Bash(./ai-orchestrator *)",
  16. "Bash(make *)",
  17. "Bash(docker compose *)",
  18. "Bash(npm *)",
  19. "Bash(node *)",
  20. "Bash(wc *)",
  21. "Bash(python -c *)",
  22. "Bash(python3 -c *)"
  23. ],
  24. "deny": ["Bash(rm -rf /)", "Bash(rm -rf ~)", "Bash(git push --force *)"]
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 24 on GitHub
  25. },
  26. "hooks": {
  27. "PostToolUse": [
  28. {
  29. "matcher": "Write|Edit",
  30. "hooks": [
  31. {
  32. "type": "command",
  33. "command": "file=$(jq -r '.tool_input.file_path // .tool_input.filePath // empty' 2>/dev/null); if [ -n \"$file\" ] && echo \"$file\" | grep -qE '\\.py$'; then black --quiet \"$file\" 2>/dev/null; isort --quiet \"$file\" 2>/dev/null; fi"
  34. }
  35. ]
  36. }
  37. ]
  38. }
  39. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.