Project Guide | Multi-CLI Pilot

Live Demo

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

Multi-CLI Pilot

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.

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.

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

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).

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 test suite (225 tests)

Commands

Backward Compatibility

source distribution.

are retained as deprecated type aliases pointing at the new MultiCliPilotConfig / MultiCliPilotConfigSchema names.

don't need to migrate anything.

• The legacy binary aliases gp and gemini-pilot continue to work in the
• Existing imports of GeminiPilotConfig / GeminiPilotConfigSchema
• The state directory is still .gemini-pilot/ so existing projects

Development

npm install
npm run typecheck      # strict TypeScript
npm test               # 225 tests across config, harness, team, MCP, …
npm run lint           # biome
npm run build          # emit to dist/

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