Hybrid-CLI-Agent

Hybrid-CLI-Agent is an MCP server that coordinates a multi-model, multi-source workflow for AI engineering tasks. It leverages the Hybrid-CLI-Agent CLI to route tasks to the most cost-effective and capable models (Gemini for reading and data ingestion, Claude Code for high-cost, high-quality reasoning, and OpenRouter for model debates and extra capabilities). Through MCP mode, Claude Code can drive the workflow by reading task definitions, delegating heavy reading to Gemini, and returning structured results, enabling you to implement cost-saving, supervisor-verified automation in your projects. Use the included CLI commands to ask questions, perform research, draft code, or review code, while the MCP server handles routing, context sharing, and supervisor checks where enabled.

Prerequisites:

• Node.js >= 20.0.0
• Git
• npm (bundled with Node.js)

Install and set up:

1. Clone the repository git clone https://github.com/SneezeGUI/Hybrid-CLI-Agent.git
2. Navigate into the project cd hybrid-cli-agent
3. Install dependencies npm install
4. Optional: link the CLI globally for convenience npm link
5. Start setup to configure API keys and registration with Claude Code (recommended) npm run setup

If you prefer running directly without setup, you can start the MCP server with: node bin/hybrid.js status

Environment setup (examples):

• GEMINI_AGENT_MODE=true
• OPENROUTER_API_KEY=your-openrouter-api-key
• GEMINI_API_KEY=your-gemini-api-key (if not using OAuth)

For a fresh environment, ensure you have .env configured as described in the README (GEMINI_AGENT_MODE, OPENROUTER_API_KEY, GEMINI_API_KEY).

Tips and caveats:

• The server relies on Gemini for large-scale reading/analysis, Claude Code for reasoning/supervision, and OpenRouter for additional model options and debates. The MCP mode enables Claude Code to interact with Gemini worker tools via the Gemini MCP server.
• Cost management is handled by routing tasks to cheaper models first; the system falls back to paid options only when needed. Monitor usage using the hybrid_metrics tool when available.
• Ensure API keys are kept secure and never committed to version control. Use a .env file and environment variable management in your deployment environment.
• If you encounter authentication or quota issues, check gemini_auth_status and gemini_health_check (as described in the Features section) to diagnose connectivity and tier limits.
• When deploying, consider setting OPENROUTER_API_KEY and GEMINI_API_KEY only if you plan to use those models; otherwise, you can rely on OAuth-based Gemini access.