Multi-CLI Pilot

Live Demo

• Open the public Cloudflare Pages demo
• Scope: credential-free, synthetic-data demo for reviewers and evaluators.

English | 한국어

One orchestration harness, multiple coding-agent CLIs. Drive Gemini CLI or Qwen CLI from the same agents, workflows, prompts, hooks, MCP tools, and team primitives.

Multi-CLI Pilot is the successor to gemini-pilot and qwen-pilot. Both repos have been consolidated here and the Gemini-only APIs are preserved as deprecated aliases — existing gp / gemini-pilot commands continue to work.

System Overview

A multi-agent CLI harness that shows how complex coding work can be coordinated without losing traceability.

Area	Details
Users	Engineering teams, automation leads, and internal platform groups experimenting with agent-assisted development.
System scope	Prompt management, workflows, coordination, task queues, and MCP support in a reviewable CLI surface.
Operating boundary	Agent output remains advisory and approval-required; production repositories should keep human approval and CI gates.
Evaluation path	Run the local test/build scripts and inspect the workflow examples and coordination docs.

Evaluation Path

• Start here: Run a simple workflow, then inspect how provider switching and team coordination are represented.
• Local demo: Run the installer or npm install && npm run build, then use the CLI examples under Quick Start.
• Checks: Run npm run verify; it covers lint, typecheck, tests, and build.

Service Launch Playbook

• Service launch playbook maps the repository to its product scope, operating gates, operating boundaries, and risk controls.

Architecture Notes

• Architecture guide summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

Why

Coding-agent CLIs ship fast but each one ends up with its own agents, workflows, and tmux scripts. Multi-CLI Pilot abstracts the CLI behind a provider adapter so the harness, HUD, MCP server, and tool- reliability pipeline stay the same regardless of which CLI you target.

Architecture

flowchart LR
  subgraph UX["UX"]
    CLI[mcp / gp]
    HUD[HUD display]
  end

  subgraph Core["Multi-CLI Pilot Core"]
    Config[Config + Env<br/>provider, models, approval]
    Agents[16 Agents + Registry]
    Workflows[10 Workflows]
    Hooks[Hook Manager]
    Team[Team Coordinator<br/>plan/execute/verify/fix]
    Harness[Harness<br/>session + metrics + state]
    MCP[MCP Server<br/>tools exported]
    ToolRel[Tool-Call Reliability<br/>parser + middleware]
  end

  subgraph Providers["Provider Adapters"]
    Gemini[Gemini CLI<br/>gemini]
    Qwen[Qwen CLI<br/>qwen]
  end

  CLI --> Config
  CLI --> Workflows
  CLI --> Agents
  Config --> Harness
  Harness --> Providers
  Workflows --> Harness
  Team --> Harness
  Hooks --> Harness
  MCP --> Harness
  HUD --> Harness
  ToolRel --> Harness

Loading

Features

• 16 Specialized Agents — architect, executor, debugger, architecture-reader, test-engineer, and more, each with a role prompt plus a tool-calling optimization prompt.
• 10 Built-in Workflows — autopilot, deep-plan, sprint, investigate, tdd, architecture-cycle, refactor, deploy-prep, clarification, team-sync.
• Provider Adapter — pick gemini or qwen via config or env. Swapping providers swaps the binary, default models, and install instructions.
• Team Coordination — phase-based pipeline (Plan → Execute → Verify → Fix) with quality gates and shared state.
• Session Metrics — prompts sent, estimated tokens, latency samples, wall-clock elapsed — persisted to session state.
• Tool-Call Reliability — parser and middleware for hardening tool-call output across providers.
• Hook System — event-driven hooks for extending harness behavior (session-start, session-end, error, …).
• MCP Server — Model Context Protocol integration so the harness can be driven from any MCP-aware client.
• HUD Dashboard — real-time metrics display with tmux integration.
• State Persistence — JSON state, memory, and notepad stored in .gemini-pilot/ (directory name kept for backward compatibility).

Installation

macOS

1. Download or clone this repo
2. Double-click Install-Mac.command
3. Open Terminal and type mcp --help (or the legacy gp --help)

Windows

1. Download or clone this repo
2. Double-click Install-Windows.bat
3. Open CMD and type mcp --help

Linux

git clone https://github.com/KIM3310/multi-cli-pilot.git
cd multi-cli-pilot
chmod +x Install-Linux.sh && ./Install-Linux.sh

Source Install

npm install
npm run build
npm link

The npm registry package is not published. The repository is marked private until package ownership, release signing, and support policy are in place.

Requirements

• Node.js ≥ 20.0.0
• One of the supported coding-agent CLIs on $PATH:
  • Gemini — npm install -g @google/gemini-cli (default, gemini-3.1-pro family)
  • Qwen — npm install -g @qwen-code/qwen-code (qwen3-coder-plus family)

Quick Start

# Run with the default provider (Gemini)
mcp

# Switch to Qwen for the current session
MCP_PROVIDER=qwen mcp

# Legacy aliases still work
gp
gemini-pilot

Provider Selection

The provider is resolved from the first matching source:

1. MCP_PROVIDER (or the legacy GP_PROVIDER) environment variable
2. provider field in .gemini-pilot/config.json (project)
3. provider field in ~/.config/gemini-pilot/config.json (user)
4. Built-in default (gemini)

Example project config:

{
  "provider": "qwen",
  "session": { "approvalMode": "auto", "defaultTier": "balanced" }
}

When provider is set to qwen and models.* entries have not been overridden, the loader substitutes Qwen tier defaults (qwen3-coder-plus / qwen3-coder / qwen3-coder-flash) automatically.

Project Structure

multi-cli-pilot/
  AGENTS.md           # Master orchestration contract
  prompts/            # 16 agent role prompts (markdown)
  workflows/          # 10 workflow definitions (markdown with frontmatter)
  src/
    agents/           # Agent registry
    benchmark/        # Benchmark runner
    cli/              # CLI entry point
    config/           # Config loader, schema, provider resolution
    errors/           # Error codes
    harness/          # Session harness (provider-aware)
    hooks/            # Event hook manager
    hud/              # HUD renderer
    init/             # `mcp init` templates
    mcp/              # MCP server integration
    metrics/          # Runtime session metrics tracker
    plugins/          # Prompt/workflow plugin loader
    prompts/          # Prompt file loader
    providers/        # Provider adapter layer (Gemini, Qwen)
    state/            # State manager and schema
    team/             # Team coordinator (plan/execute/verify/fix)
    tool-bench/       # Tool-calling benchmark harness
    tool-reliability/ # Tool-call parser + middleware
    utils/            # fs, logger, small helpers
    workflows/        # Workflow runner
  __tests__/          # Vitest unit and integration suite

Commands

Command	Description
mcp init	Scaffold .gemini-pilot/ with config, memory, workflows
mcp	Launch an interactive session with the active provider
mcp config show	Print the resolved configuration
mcp workflows list	List available workflows
mcp workflows run <name>	Execute a workflow end-to-end
mcp agents list	List registered agents
mcp team	Start a tmux-based multi-agent team

Backward Compatibility

• The legacy binary aliases gp and gemini-pilot continue to work in the source distribution.
• Existing imports of GeminiPilotConfig / GeminiPilotConfigSchema are retained as deprecated type aliases pointing at the new MultiCliPilotConfig / MultiCliPilotConfigSchema names.
• The state directory is still .gemini-pilot/ so existing projects don't need to migrate anything.

Development

npm install
npm run typecheck      # strict TypeScript
npm test               # Current config, harness, team, and MCP suites
npm run lint           # biome
npm run build          # emit to dist/

License

MIT — see LICENSE.

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

System Architecture

• System architecture maps the runtime boundary, data/control flow, cloud or local deployment surface, and operating assumptions for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.

Search And Service Surface

• Public entry: free CLI recipes and demo tasks
• Paid boundary: team workflow library, hosted run history, and provider cost dashboard
• Canonical URL: https://multi-cli-pilot.pages.dev/
• Lead capture: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=multi-cli-pilot&inquiry=agent-reliability-audit#private-inquiry
• Resource route: https://kim3310-doeon-kim-portfolio.pages.dev/resources/multi-cli-pilot/
• Commercial route: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=multi-cli-pilot#service-offers
• Machine-readable offer: docs/service-offer.json
• Search growth implementation: docs/search-growth-implementation.md
• Revenue architecture: docs/revenue-architecture.md

Free Resource, Advertising, and Aggregate Data

• Public utility and architecture checklist
• Revenue model: contextual advertising on the policy-eligible central resource page.
• Aggregate value: anonymous aggregate CLI reliability topic interest and worksheet usage counts
• Boundary: ads allowed only on public CLI reliability resources; command traces, terminal logs, and diagnostics are ad-free
• Consent defaults off, DNT/GPC fail closed, and personal or sensitive data is never sold.