CliRouter

CliRouter is the project name. The internal routing skill lives under skills/src/CliRouter and delegates agent-level tasks to installed CLIs from CodeX or AntiGravity.

What it does

• Routes requests such as gac, kimi, codex, claude, gemini, and kimicc-backed profile names to the right local backend
• Treats gac, kimi, codex, claude, and gemini as standalone launchers when they are present in PATH
• Treats kimicc as the profile host, with glm, minimax, mimo, qwen, and deepseek mapped through kimicc profiles
• Treats glm, minimax, mimo, qwen, and deepseek as kimicc profile names, not standalone CLIs
• Treats glm as the preferred kimicc --glm entry, with --profile glm as fallback
• Records each backend's model-routing surface and selection constraints so routing can choose for speed, quality, or parallel fanout without requiring the user to hand-write CLI flags
• Applies lightweight budget-aware routing so cheap/standard/premium task packets can cap high-cost backends and lane count before execution
• Normalizes compound phrases like kimi cli, codex cli, and claude code to their backend tokens
• In interactive handoff, launches the backend first and submits the task prompt through the PTY instead of appending it to the command line
• The submitted prompt should explicitly allow the backend to use its own Agents / sub-agent capability when that helps complete the task
• Preserves a single canonical skill source under skills/src/CliRouter
• Supports both interactive handoff and deterministic --print validation runs
• Includes an interactive fanout MVP that launches independent interactive lanes, captures per-lane summary/status, and keeps lane-level run artifacts without shared live terminal control
• Includes a rule-based natural-language front-end that can infer a task packet from a user request before dispatch
• Freezes the stable-release surface around the registry-backed router, the validation gate, and the remaining five-item release checklist
• Records each delegated run as a structured artifact under artifacts/runs/<run_id>/

Design Boundary

CliRouter exists to turn external CLIs into observable capabilities inside CodeX or AntiGravity.

The success criteria are not just "the command started". A delegated run should make at least one of these visible:

• a final result or artifact path
• a visible progress signal such as launch, profile selection, or busy state
• a structured failure reason such as timeout, missing profile, or non-zero exit

If the integration only proves that a process was launched, but nothing about result, progress, or failure can be observed, that is not a complete delegation path yet.

The trigger surface is registry-backed. When a new launcher is added later, it should be added to the trigger vocabulary, backend registry, and model-routing reference together instead of being hardcoded in multiple places.

Repository Layout

• skills/src/CliRouter/: canonical skill source
• skills/registry.toml: registry for the skill package
• skills/src/CliRouter/references/backend-registry.json: machine-readable backend registry for router policy, router defaults, family grouping, capability flags, and default model selection
• skills/src/CliRouter/references/router-logic.md: logic diagram for routing, health, fanout, and synthesis
• skills/src/CliRouter/references/v2-execution-plan.md: execution plan and end-to-end acceptance matrix for the current V2 rollout
• skills/src/CliRouter/references/stable-release-plan.md: frozen stable-release plan and external surface definition
• skills/src/CliRouter/references/stable-release-checklist.md: the remaining five-item checklist for reaching a stable release
• skills/src/CliRouter/scripts/infer_task_packet.py: rule-based front-end that normalizes natural language into a dispatcher-ready task packet
• .codex/skills and .agents/skills: local projections for tool discovery
• scripts/validation/check_project_skill_links.sh: validates the repository projections
• scripts/install-global-symlinks.sh: installs global home-directory symlinks for this machine
• docs/codex-plugin-cc-learning-notes.md: concise learning reference for the Codex-plugin-cc bridge architecture
• artifacts/: runtime output, intentionally not versioned

Local Setup

bash scripts/install-global-symlinks.sh
bash scripts/validation/check_project_skill_links.sh

Private / Public Release

CliRouter now supports a split workflow:

1. Keep this checkout as the private source of truth.
2. Mirror it into the sibling public worktree with bash scripts/public-release/bootstrap.sh.
3. Commit locally as usual; the hooks will mirror the change into the public worktree.
4. Use the local git aliases for day-to-day release work: git public-sync, git public-validate, git public-push, or just git public-release for sync + push in one shot.
5. Push only from the public worktree, never from the private checkout.
6. git public-release runs the router contract gate before it mirrors and pushes.

For the exact branch/worktree contract, read skills/src/CliRouter/references/public-release.md.

For manual backend checks, run skills/src/CliRouter/scripts/dispatch.sh directly with one backend at a time. --launch-only is available for interactive startup capture when you want a quick validation without waiting for a long session to complete. The current interactive fanout is an MVP with lane-level launch capture and artifact aggregation, not a shared live control plane. To bootstrap a task packet from free-form text, use python3 skills/src/CliRouter/scripts/infer_task_packet.py "<request>" "<cwd>".

Validation

• bash scripts/validation/check_project_skill_links.sh is the repeatable local and CI gate for planner, health, budget, and fanout contracts.
• The same gate also validates the natural-language task-packet front-end.
• The gate exercises selector behavior with a clean health file, a pinned model request, a cheap-budget collapse, a diversified fanout, and a provider-family cooldown.
• For a full local end-to-end smoke run on this machine, use skills/src/CliRouter/scripts/dispatch.sh --backend codex --task-profile developer --task-file <packet.json> --cwd <path> --execution-mode print when the codex CLI is installed.
• For interactive fanout MVP acceptance, use skills/src/CliRouter/scripts/dispatch.sh --backend auto --task-profile developer --task-file <packet.json> --cwd <path> --execution-mode interactive --launch-only.
• For stable-release review, read skills/src/CliRouter/references/stable-release-plan.md first; it defines the frozen external surface and the five remaining closure items.

Usage

Trigger the skill naturally in CodeX or AntiGravity:

• 用 gac 支持审计 Agent 完成 X
• 调用 kimi / kimi cli 支持开发 Agent 完成 Y
• 调用 codex / codex cli 支持 review 完成 Z
• 调用 claude / claude code 支持 audit 完成 Z
• 调用 glm 支持开发 Agent 完成 Y
• 调用 minimax / mimo / qwen / deepseek 支持开发 Agent 完成 Z
• 用 kimicc 支持开发 Agent 完成 Z

For the authoritative procedure and backend mapping, read skills/src/CliRouter/SKILL.md. For machine-readable backend metadata, read skills/src/CliRouter/references/backend-registry.json. For the control-flow diagram, read skills/src/CliRouter/references/router-logic.md. For per-CLI model dispatch semantics and the current selection matrix, read skills/src/CliRouter/references/model-routing.md. For the current rollout plan and end-to-end acceptance matrix, read skills/src/CliRouter/references/v2-execution-plan.md. For the stable-release freeze surface and doc contract, read skills/src/CliRouter/references/stable-release-plan.md. For the remaining stable-release gap, read skills/src/CliRouter/references/stable-release-checklist.md. Current health routing now aggregates both backend-level and provider-family signals before automatic selection.