codex-ai-team-router

# Codex AI Team Router Let Codex act as the project manager and final reviewer, while delegating tasks such as broad searches, preliminary analyses, repetitive scripting, test drafts, and partial implementations to Qwen and DeepSeek. The project utilizes a lightweight MCP Router to automatically select assistants and complete project reconnaissance, controlled execution, and acceptance reports using local PowerShell scripts. The entire process is saved to disk, and Codex only receives concise summaries, avoiding command outputs and lengthy logs that could continuously expand the main conversation context. > The goal is not to pursue the lowest token count but to achieve a practical balance between capability, speed, cost, and context volume. ## Work Mode ```mermaid flowchart LR U[User Task] --> C[Codex\nProject Manager / Architect] C --> R[AI Team MCP Router] R -->|Documentation, Organization, Broad Drafts| Q[Qwen] R -->|Code, Error Correction, Implementation Ideas| D[DeepSeek] R -->|Complex Cross-Tasks| B[Qwen + DeepSeek] C --> S[Scout\nFile and Log Reconnaissance] C --> W[Worker\nControlled Implementation] S --> A[Disk Complete Report + Concise Summary] W --> A A --> C C --> G[Gate\nBuild / Test / Type / Lint / Diff / Secrets] G --> O[Final Result] ``` Role Division: - **Codex**: Task decomposition, architectural judgment, result integration, and final response. - **Qwen**: Organization, summarization, documentation, test drafts, and broad first-round investigations. - **DeepSeek**: Code analysis, bug hypothesis, implementation drafts, and diff review. - **Scout / Worker / Gate**: Local mechanical work, complete record-keeping on disk, and providing necessary summaries to Codex. ## Why Keep a Single MCP Loading separate MCPs for Qwen and DeepSeek would add more tool definitions and parameter explanations to each Codex session. This project exposes only two tools: - `delegate_task`: Automatically routes tasks; with `dry_run=true`, it previews routing without calling models. - `worker_gate_review`: Performs lightweight acceptance of diffs produced by workers. Qwen and DeepSeek remain independent model lines, scheduled through a single entry point. ## Main Features - Automatic routing to Qwen, DeepSeek, or parallel dual-track. - `dry_run` routing preview without consuming model API. - Three output budget levels: `low`, `normal`, `deep`. - MCP returns have a character limit to prevent abnormally long responses from entering Codex context. - Worker complete output written to disk, with a default summary limit of 30 lines / 3000 characters. - Scout specializes in large directory, log, file location, and first-round project investigation. - Gate checks build, test, type checking, lint, diff size, dependency changes, and secret traces. - API keys are read from environment variables, not written to code or Codex configuration examples. - Router based on Node.js; local worker scripts target Windows PowerShell. ## Repository Structure ```text codex-ai-team-router/ ├─ mcp-server/ │ ├─ server.mjs # Qwen / DeepSeek MCP Master Router │ ├─ smoke-test.mjs # API non-call smoke test │ └─ package.json ├─ scripts/ │ ├─ codex-scout.ps1 # Read-only reconnaissance, returns short conclusions │ ├─ codex-worker.ps1 # Qwen Code / Claude Code-DeepSeek executor │ └─ codex-gate.ps1 # Local acceptance script ├─ examples/ │ ├─ AGENTS.md │ └─ config.toml.example ├─ install.ps1 └─ README.md ``` ## Prerequisites MCP Router: - Node.js 20 or higher - npm - Codex Desktop or Codex environment supporting local MCP server - At least one model API key configured Optional Worker: - Qwen Code CLI for Qwen agent mode - Claude Code CLI for DeepSeek agent mode via Anthropic compatible interface - Git for diff and repository checks - Project-specific npm / Python / compilation tools ## Installation ```powershell git clone https://github.com/kennedymike936-lang/codex-ai-team-router.git cd codex-ai-team-router powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 ``` The installation script: 1. Checks Node.js and npm. 2. Installs MCP SDK in `mcp-server`. 3. Runs a smoke test without calling Qwen / DeepSeek API. 4. Outputs Node and MCP server absolute paths. ## API Environment Variables Do not write keys to the repository, README, `config.toml`, or worker prompts. Qwen reads in the following order: ```text DASHSCOPE_API_KEY OPENAI_API_KEY QWEN_API_KEY ``` DeepSeek reads in the following order: ```text ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN DEEPSEEK_API_KEY ``` Windows user-level environment variable example: ```powershell [Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_KEY", "User") [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_KEY", "User") ``` Restart Codex after setting to allow desktop processes to re-read environment variables. ## Integration with Codex Open `~/.codex/config.toml`, refer to [examples/config.toml.example](examples/config.toml.example) to add MCP server. Windows example: ```toml [mcp_servers.ai_team_mcp] command = 'C:\Program Files\nodejs\node.exe' args = ['C:\absolute\path\codex-ai-team-router\mcp-server\server.mjs'] startup_timeout_sec = 60 [mcp_servers.ai_team_mcp.env] QWEN_MCP_BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1' QWEN_MCP_MODEL = 'qwen3.7-plus' DEEPSEEK_MCP_BASE_URL = 'https://api.deepseek.com/anthropic' DEEPSEEK_MCP_MODEL = 'deepseek-v4-pro[1m]' ``` Find Node absolute path with: ```powershell (Get-Command node).Source ``` After restarting Codex, tools should appear in the list: ```text delegate_task worker_gate_review ``` ## MCP Usage Example Automatic routing: ```json { "task": "Analyze this TypeScript error and provide a minimal fix", "preferred": "auto", "budget": "low" } ``` Dry run: ```json { "task": "Organize project structure and draft README", "preferred": "auto", "dry_run": true } ``` Forced dual-track: ```json { "task": "Compare two architectures and check code risks", "preferred": "both", "budget": "normal" } ``` ## Scout: Delegate Broad Investigation to Assistant Scout does not modify files, suitable for: - Searching project entries and key modules - Locating functionality within files - Reading large logs and returning relevant lines - First-round structure investigation for unfamiliar projects ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\codex-scout.ps1 ` -Task "Find login process, key files, and related tests, return only paths and key lines" ` -Cwd "C:\path\to\project" ` -Worker auto ``` Complete results saved by default in: ```text %USERPROFILE%\.codex-ai-team\runs ``` Codex terminal receives only concise summaries. ## Worker: Controlled Task Execution ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\codex-worker.ps1 ` -Worker qwen ` -Task "Complete duplicate input validation in src/utils and run existing tests" ` -Cwd "C:\path\to\project" ` -Approval auto ` -MaxWallTime 8m ``` DeepSeek worker: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\codex-worker.ps1 ` -Worker deepseek ` -Task "Locate failed tests and submit minimal fixes" ` -Cwd "C:\path\to\project" ` -DeepSeekMaxBudgetUsd 0.03 ``` `yolo` bypasses more confirmations, use with caution in low-risk, recoverable workspaces. `auto` is recommended by default. ## Gate: Lightweight Acceptance ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\codex-gate.ps1 ` -Cwd "C:\path\to\git-project" ``` Gate checks as much as possible: 1. Code builds or runs 2. Tests pass 3. Type checking passes 4. Lint passes 5. No sensitive or prohibited file modifications 6. Diff is not overly large 7. No dependency file changes 8. Diff does not contain suspected API keys / private keys Gate relies on Git diff; non-Git directories return `CHECK` instead of false positives `PASS`. ## Token Saving Principle The project mainly reduces **Codex conversation context growth**, not guaranteeing to lower all model total costs: - Large directories and logs investigated by external workers. - Complete worker processes saved to disk, not repeated in Codex. - Codex receives only conclusions, paths, line numbers, and short summaries. - A single MCP Router replaces two sets of redundant model tool definitions. - Simple tasks use smaller output budgets by default. - Low-risk results do not enforce second-round model review. In a local debugging record, context grew from ~18k to 153k without output limits; after optimization, similar processes grew to ~63k. This illustrates the impact of long tool output, not a universal benchmark. ## Security Notes - This project does not write API keys into source code. - MCP and scripts read keys from user environment variables. - Workers can run tools and modify workspaces; ensure target directories are correct before running. - Complete worker logs may contain sensitive information appearing in tasks; **the project does not automatically ensure log desensitization**. - Do not provide `.env`, private keys, payment data, account credentials, or private chat content to external models. - It is recommended to run workers in Git repositories or directories with backups. - Manually inspect content before publishing or sharing `runs` directories. ## Optional Path Variables If Node, Git, Qwen Code, or Claude Code are not in system PATH: ```text AI_TEAM_NODE_DIR AI_TEAM_GIT_DIR AI_TEAM_TOOLS_DIR ``` Scripts also attempt `%APPDATA%\npm`. ## Troubleshooting ### MCP Tools Not Visible in Codex - Check `command` and `args` for absolute paths. - Run `npm run smoke`. - Restart Codex after modifying `config.toml`. ### Qwen Request Failure - Check `DASHSCOPE_API_KEY`. - Verify model name and endpoint compatible with Baidu Qianfan. - Confirm account region matches model permissions. ### DeepSeek Request Failure - Check `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`. - Confirm interface supports Anthropic Messages compatible format. - Adjust `DEEPSEEK_MCP_MODEL` according to actual model names provided by the service provider. ### Worker Stuck or Overly Long Output - Reduce `MaxWallTime`. - Use Scout for read-only investigation. - Check complete results in `%USERPROFILE%\.codex-ai-team\runs`. - Keep `SummaryLines` and `SummaryMaxChars` in a smaller range. ## Design Trade-offs - MCP Router is lightweight, without a full multi-agent framework. - Routing rules are heuristic, not guaranteeing the best model selection. - PowerShell worker primarily targets Windows; MCP Router itself is Node.js-based and can be adapted to other systems. - Tool descriptions and return content are intentionally kept brief to reduce long-term context burden. ## License [MIT](LICENSE)