Plan Mode Claude

A structured planning workflow for AI assistants with MCP (Model Context Protocol) integration. Design better software by planning first.

Quick Start

1. Install globally:

   npm install -g @nicolasmirson/plan-mode-claude

2. Add to your MCP configuration (.cursor/mcp.json):

   {
     "servers": {
       "plan-mode-claude": {
         "command": "plan-mode-claude"
       }
     }
   }

3. Restart your editor (Cursor/VS Code) to load the MCP server

4. Start planning with your AI assistant:

   "Enter plan mode and help me build a user authentication system"

What is Plan Mode?

Plan Mode transforms how AI assistants work by requiring structured planning before execution:

1. 🧠 Enter Plan Mode - Switch to planning state
2. 📋 Create Plan - Define title and description
3. ➕ Add Steps - Break down into manageable tasks with priorities
4. ✅ Review & Approve - Present complete plan for approval
5. 🚀 Execute - Track progress through each step

MCP Integration

Plan Mode Claude integrates seamlessly with editors through MCP:

Available Tools

| Tool | Purpose | Usage | |------|---------|-------| | enter_plan_mode | Start planning session | AI automatically enters planning state | | create_plan | Define plan title/description | create_plan(title, description) | | add_plan_step | Add step with priority/dependencies | add_plan_step(content, priority, deps) | | exit_plan_mode | Present plan for approval | Returns formatted plan for review | | update_step_status | Track progress | update_step_status(stepId, status) | | get_plan_status | Check current state | Shows plan overview and progress |

MCP Configuration

Cursor Setup

Add to .cursor/mcp.json:

{
  "servers": {
    "plan-mode-claude": {
      "command": "plan-mode-claude"
    }
  }
}

VS Code Setup

Add to your VS Code MCP configuration:

{
  "mcp": {
    "servers": {
      "plan-mode-claude": {
        "command": "plan-mode-claude"
      }
    }
  }
}

Manual Configuration

If you need custom paths:

{
  "servers": {
    "plan-mode-claude": {
      "command": "node",
      "args": ["/path/to/global/node_modules/@nicolasmirson/plan-mode-claude/bin/plan-mode-claude"]
    }
  }
}

Example Workflow

Here's how a typical planning session works:

👤 User: "Enter plan mode and help me build a user authentication system"

🤖 AI: I've entered plan mode. Let me create a structured plan for building a user authentication system.

📋 Plan: "Build User Authentication System"
   Description: Implement secure login/signup with JWT tokens and password hashing

📝 Steps:
   1. [HIGH] Set up database schema for users
   2. [HIGH] Create password hashing utilities  
   3. [HIGH] Build signup endpoint with validation
   4. [HIGH] Build login endpoint with JWT generation
   5. [MEDIUM] Add JWT middleware for protected routes
   6. [MEDIUM] Create logout functionality
   7. [LOW] Add password reset flow

👤 User: "Looks good, let's proceed"

🤖 AI: Perfect! I'll start with step 1...

Cursor Rules Integration

Plan Mode Claude automatically creates Cursor rules to optimize your AI assistant's behavior. After installation, you'll find enhanced planning prompts in .cursor/rules/plan-mode-claude.mdc.

Programming API

For advanced users who want to integrate Plan Mode into their own applications:

import { PlanManager } from '@nicolasmirson/plan-mode-claude';

const planManager = new PlanManager();

// Enter plan mode
planManager.enterPlanMode();

// Create a plan
const plan = planManager.createPlan(
  'Build User Authentication',
  'Implement secure login system with JWT tokens'
);

// Add steps with priorities and dependencies
const step1 = planManager.addStep('Set up database schema', 'high');
const step2 = planManager.addStep('Create login endpoint', 'high', [step1.id]);

// Handle approval workflow
planManager.setApprovalCallback(async (request) => {
  console.log('📋 Plan ready for review:');
  console.log(request.markdown);
  return { approved: true };
});

// Execute and track progress
const approval = await planManager.exitPlanMode();
if (approval.approved) {
  planManager.updateStepStatus(step1.id, 'in_progress');
  // ... implement step ...
  planManager.updateStepStatus(step1.id, 'completed');
}

Core Features

• 🎯 Structured Planning: Break complex tasks into manageable steps
• ✅ Approval Workflow: Review plans before execution
• 🔄 Progress Tracking: Monitor step completion in real-time
• 🔗 Dependency Management: Handle step dependencies with cycle detection
• 📊 Priority Support: Organize steps by priority (high/medium/low)
• 🎨 Markdown Export: Convert plans to readable format
• 🔌 MCP Integration: Native editor integration (Cursor, VS Code)
• 📝 Cursor Rules: Automatic setup of optimized AI prompts

TypeScript Support

Full TypeScript support with comprehensive types:

interface Plan {
  id: string;
  title: string;
  description: string;
  steps: PlanStep[];
  status: 'draft' | 'approved' | 'executing' | 'completed';
}

interface PlanStep {
  id: string;
  content: string;
  status: 'pending' | 'in_progress' | 'completed';
  priority: 'high' | 'medium' | 'low';
  dependencies?: string[];
}

Troubleshooting

MCP Server Not Loading

1. Check global installation:

   which plan-mode-claude
   # Should return: /usr/local/bin/plan-mode-claude or similar

2. Verify MCP configuration:

   • Ensure .cursor/mcp.json exists
   • Check JSON syntax is valid
   • Restart your editor after changes

3. Test server manually:

   plan-mode-claude
   # Should start without errors

Tools Not Available

1. Restart your editor after installing
2. Check MCP status in your editor's MCP panel
3. Verify permissions - ensure the binary is executable

License

MIT