AI Planning System for the Claude Code

A comprehensive AI planning system that integrates Google's Gemini CLI as a planning backend with Claude Code for implementation. Features automatic plan-then-execute workflows, persistent context management, and seamless MCP integration.

Features

🤖 Gemini 2.5 Pro Integration: Uses Google's latest Gemini CLI for advanced planning
🔄 Context Management: Persistent context across planning and execution sessions
🔁 Plan-Then-Execute Workflow: Automatic planning followed by step-by-step implementation
🛠️ Claude Code Integration: Seamless integration via Model Context Protocol (MCP)
📊 Progress Monitoring: Real-time monitoring of planning and execution progress
🎯 Environment-Based Configuration: No hardcoded defaults, fully configurable via .env
🧩 Prompt-Based Library Auto-Resolution: Describe your stack in natural language or pass structured library specs

Quick Start

Prerequisites

Node.js 18+
Go 1.19+ (for Gemini CLI)
Claude Code installed
Gemini API key from Google AI Studio

Installation

Clone and setup the system:

git clone <repository-url>
cd revolver-orchestrator-mcp/
./scripts/setup-gemini-cli.sh

Create and configure environment file: cp .env.example .env Add your Gemini API key - GEMINI_API_KEY in .env
Install dependencies and build:
```
./scripts/install-dependencies.sh
```
Setup Claude integration:
```
./scripts/setup-claude-integration.sh
```
This script will:
- Detect your Claude installation (command or alias)
- Register the Gemini planning MCP server using claude mcp add-json
- Fall back to direct config file method if needed
- Build the MCP server with proper dependencies
Test the system:
```
./scripts/test-system.sh
```

Usage

Plan-Then-Execute Workflow (Recommended)

Use this pattern for automatic planning and implementation:

Build a React todo application with these requirements:
- Add, edit, delete todos
- Mark todos as complete
- Local storage persistence  
- Clean, modern UI

Workflow:
1. Create a project context for this task
2. Generate a detailed implementation plan using Gemini
3. Execute the plan step by step

Please follow this workflow automatically.

Manual Step-by-Step Process

Create a project context:

Create a project context for a real-time chat application with React frontend and Node.js backend

Generate detailed plans:

Use the Gemini MCP to generate a comprehensive implementation plan for the chat application context

Execute the plan:

Now implement the plan step by step, creating all necessary files and components

Rule of Thumb

Generally, if you want to activate the tool call just include in your prompt "Plan with Gemini".

Quick Examples

# Simple web app with automatic planning
Build a React todo app with local storage. First create a project context, generate a plan with Gemini, then implement it.

# API development with planning
Create a REST API for task management with JWT auth. Use the Gemini MCP to plan the architecture, then implement it step by step.

# Full-stack application  
Build a real-time chat app with React frontend and Node.js backend. Plan with Gemini first, then execute the implementation.

Architecture

┌─────────────────────┐    ┌─────────────────────┐
│    Claude Code      │    │   Gemini CLI        │
│   (Execution)       │────│   (Planning)        │
└─────────────────────┘    └─────────────────────┘
         │                           │
         └─────────┬─────────────────┘
                   │
   ┌─────────────────────────────────────┐
   │        MCP Integration              │
   │  - Context Management              │
   │  - Feedback Processing             │
   │  - Session Coordination            │
   └─────────────────────────────────────┘

Configuration

Environment Configuration

All configuration is done via the .env file (no hardcoded defaults):

# Gemini Configuration
GEMINI_API_KEY=you_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-pro
GEMINI_TEMPERATURE=0.3
GEMINI_MAX_TOKENS=4000
GEMINI_CLI_PATH=gemini

# Context7 MCP URL
CONTEXT7_URL=https://mcp.context7.com/mcp

# System Configuration
LOG_LEVEL=info
CONTEXT_STORAGE_PATH=./contexts

Available Models

NOTE: The Gemini models usage is free but limited for a Gemini CLI. Usually it's more than enough for a daily planning tasks.

gemini-2.5-pro - Latest and most capable model (recommended)
gemini-2.5-flash - General purpose, balanced performance
gemini-2.5-flash-lite - The most ligtweight model in a 2.5 family

Configuration Notes

GEMINI_API_KEY is required - get from Google AI Studio
GEMINI_MODEL determines which model to use for planning
GEMINI_TEMPERATURE controls response creativity (0.1-0.9)
Modern Gemini CLI may not use GEMINI_TEMPERATURE and GEMINI_MAX_TOKENS directly
System relies entirely on environment variables for configuration

Tools and Utilities

Context Monitoring

# View specific context
node tools/context-viewer.js <context-id>

# Monitor all contexts
./tools/monitor-contexts.sh

System Testing

# Test Gemini CLI connection
./scripts/test-system.sh

# Test MCP server
cd gemini-cli-mcp-server && npm test

Project Structure

ai-planning-system/
├── gemini-cli-mcp-server/     # Gemini CLI MCP wrapper
│   ├── src/
│   │   ├── services/          # Planning services  
│   │   ├── gemini-cli-wrapper.ts  # Gemini CLI integration
│   │   └── index.ts          # MCP server entry point
│   ├── tsconfig.json         # TypeScript configuration
│   └── package.json
├── shared-context/            # Context management
│   ├── types.ts              # TypeScript definitions
│   └── context-store.ts      # Context storage
├── contexts/                 # Stored project contexts
├── examples/                 # Usage examples and workflows
│   └── plan-then-execute-workflow.md
├── tools/                    # Utility tools
├── scripts/                  # Setup and utility scripts
│   ├── setup-gemini-cli.sh   # Gemini CLI installation
│   ├── setup-claude-integration.sh  # Claude Code setup
│   ├── install-dependencies.sh  # Dependency installation
│   └── test-system.sh        # System testing
├── .env                      # Environment configuration
├── CLAUDE.md                 # Claude Code integration guide
└── README.md

API Reference

MCP Tools

`create_project_context`

Creates a new planning context for a project.

Parameters:

projectName: Name of the project
requirements: Project requirements and specifications
constraints: Any constraints or limitations

`generate_plan_with_gemini`

Generates a detailed implementation plan using Gemini CLI.

Parameters:

contextId (string): Project context ID (optional)
projectName (string): Required if contextId is not provided
requirements (string): Required if contextId is not provided
constraints (string, optional)
libraries (array, optional): Structured library specs to fetch docs from Context7
- name (string): Canonical package or repo name, e.g., react, next.js, supabase/supabase, tanstack/query
- topic (string, optional): Narrow focus such as routing, auth, storage
- tokens (number, optional): Approximate token budget for docs
librariesPrompt (string, optional): Natural language description of the desired stack; when provided and libraries is omitted, the system auto-resolves libraries

At least one of libraries or librariesPrompt must be provided. If both are provided, libraries takes precedence.

`test_gemini_connection`

Tests the connection to Gemini CLI.

`test_context7_connection`

Tests the connection to Context7 MCP and lists available tools.

`render_plan_checklist`

Renders a stored plan as a terminal-friendly checklist.

Parameters:

contextId (required)
planIndex (optional, defaults to latest)

Example output:

Overview: Personal site with Astro, Tailwind, MDX

Dependencies:
  - astro@^5.0.0 — Core framework
  - tailwindcss@^4.0.0 — CSS utility framework

File Structure:
  - src
  - src/components
  - src/sections
  - src/layouts
  - src/pages
  - src/content
  - src/styles
  - src/utils

Implementation Steps:
  setup:
  - [ ] step-1 Initialize Astro project
    - create package.json
    - create astro.config.mjs

Examples

Web Application Development

// Context creation and planning
const context = await createProjectContext(
  "E-commerce Platform",
  "React frontend, Node.js API, PostgreSQL database, user authentication, product catalog, shopping cart"
);

const plan = await generatePlanWithGemini(context.id);
// Plan includes: architecture, implementation steps, file structure, dependencies

API Development

Prompt-Based Library Resolution

Structured input example:

{
  "projectName": "Next.js + Supabase SaaS",
  "requirements": "Subscription app with auth, RLS, and Stripe integration",
  "constraints": "Server Components, App Router",
  "libraries": [
    { "name": "next.js", "topic": "routing" },
    { "name": "supabase/supabase", "topic": "auth" },
    { "name": "tanstack/query" }
  ]
}

Prompt-based example:

{
  "projectName": "Realtime notes",
  "requirements": "Next.js app with realtime notes, auth, optimistic UI",
  "librariesPrompt": "Use Next.js (App Router), Supabase for auth and storage, and TanStack Query for data fetching"
}

const apiContext = await createProjectContext(
  "Task Management API",
  "RESTful API with authentication, CRUD operations, real-time updates via WebSocket"
);

const apiPlan = await generatePlanWithGemini(apiContext.id);
// Detailed API design with endpoints, models, middleware, testing strategy

Troubleshooting

Common Issues

Gemini CLI not found:

# Add Go bin to PATH
export PATH=$PATH:$(go env GOPATH)/bin
# Or reinstall Gemini CLI
go install github.com/google-gemini/gemini-cli/cmd/gemini@latest

API key issues:

# Test with correct modern CLI syntax
GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Say hello"

MCP server build errors:

cd gemini-cli-mcp-server
npm install
npm run build

MCP server not showing up after setup:

# MCP servers require Claude to be restarted to load
# 1. Close all Claude sessions
# 2. Wait a few seconds
# 3. Start a new Claude session
# 4. Check MCP server status
claude mcp list

Claude integration issues:

# Re-run the setup script
./scripts/setup-claude-integration.sh
# Restart Claude after setup
# Test MCP connection
claude --message "Test the Gemini planning MCP connection"

Environment variable issues:

# Verify .env file exists and has correct values
cat .env
# Test system end-to-end
./scripts/test-system.sh

Performance Tips

For faster responses:
- Use gemini-1.5-flash model in .env
- Provide more focused requirements
- Break large projects into smaller contexts
For better plan quality:
- Use gemini-2.5-pro model (recommended)
- Provide detailed requirements and constraints
- Include specific technology preferences

Debug Commands

# Test Gemini CLI directly
GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Test message"

# Check MCP server logs
cd gemini-cli-mcp-server && node build/index.js

# Verify all environment variables are set
env | grep GEMINI

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Additional Resources

CLAUDE.md - Detailed guide for Claude Code integration
examples/plan-then-execute-workflow.md - Comprehensive workflow examples
scripts/setup-claude-integration.sh - Automated setup script

Support

For issues and questions:

Check the troubleshooting section above
Review examples in examples/plan-then-execute-workflow.md
Test system health: ./scripts/test-system.sh
Check MCP server status: claude mcp list
Test MCP integration: claude --message "Test the Gemini planning MCP connection"
Check environment variables: env | grep GEMINI
Open an issue with detailed error information and logs

Getting Help

Setup Issues: Run ./scripts/setup-claude-integration.sh again
Planning Issues: Check Gemini CLI works: GEMINI_API_KEY="your-key" gemini --model gemini-2.5-pro --prompt "Hello"
MCP Issues: Verify ~/.config/claude/mcp_settings.json exists and has correct paths
Build Issues: Run cd gemini-cli-mcp-server && npm install && npm run build

Built with ❤️ for the AI development community

Revolver Orchestrator