--plan Option

Generate execution plans without running any actions

Overview

The --plan option (via --approval-mode plan) runs Qwen Code in plan-only mode, where the AI generates detailed execution plans without actually executing any tools or making changes. This is perfect for reviewing what actions would be taken before committing to them.

Syntax

qwen --approval-mode plan

There is no short -p flag for plan mode (that’s reserved for --prompt). Use the full --approval-mode plan syntax.

What It Does

With plan mode enabled:

✅ Generates detailed execution plans
✅ Lists all tools that would be called
✅ Describes what each action would do
❌ Does NOT execute any actions
❌ Does NOT modify any files
❌ Does NOT run any commands

Basic Usage

Review Changes Before Applying

qwen --approval-mode plan --prompt "Refactor the authentication module"

Output:

Execution Plan:

1. [read] Read src/auth/login.ts
   Purpose: Analyze current authentication implementation

2. [read] Read src/auth/register.ts  
   Purpose: Understand registration flow

3. [edit] Modify src/auth/login.ts
   Purpose: Extract common validation logic
   Changes: Create validateCredentials() function

4. [edit] Modify src/auth/register.ts
   Purpose: Use extracted validation logic
   Changes: Import and call validateCredentials()

5. [write] Create src/auth/validators.ts
   Purpose: Centralize validation functions
   Content: Export validateCredentials, validateEmail, etc.

6. [bash] Run npm test
   Purpose: Verify refactoring didn't break tests
   Command: npm test -- --testPathPattern=auth

Estimated changes: 3 files modified, 1 file created

No actual changes are made to your codebase.

When to Use Plan Mode

Before Large Refactorings

# Generate plan first
qwen --approval-mode plan --prompt "Refactor entire codebase to use async/await"

# Review the plan
# If satisfied, execute
qwen --yolo --prompt "Refactor entire codebase to use async/await"

Understanding AI Approach

# See what the AI would do
qwen --approval-mode plan --prompt "Optimize database queries"

# Learn from the plan
# Implement manually or let AI do it

Cost Estimation

# Estimate token usage without executing
qwen --approval-mode plan --prompt "Generate comprehensive test suite" \
     --output-format json

Code Reviews

# Get AI's proposed approach
qwen --approval-mode plan --prompt "Fix the memory leak in Worker class"

# Share plan with team for review
# Execute if approved

Learning Tool

# See how AI approaches problems
qwen --approval-mode plan --prompt "Implement pagination for API endpoints"

# Use as educational reference

Detailed Plan Output

Tool Call Details

Each step in the plan includes:

• Tool name: Which tool would be called (read, write, edit, bash, etc.)
• Target: What file or command
• Purpose: Why this action is needed
• Changes: What modifications would be made

Example Plan Structure

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Execution Plan: Add User Authentication
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1: Setup
  1. [write] Create src/auth/jwt.ts
     Purpose: JWT token generation and validation
     Size: ~150 lines
     
  2. [write] Create src/auth/middleware.ts
     Purpose: Authentication middleware
     Size: ~80 lines

Phase 2: Implementation
  3. [edit] Modify src/api/routes.ts
     Purpose: Add authentication to protected routes
     Changes: 
       - Import auth middleware
       - Apply to /api/user/* routes
       - Add /api/auth/login endpoint
       
  4. [edit] Modify src/models/User.ts
     Purpose: Add password hashing
     Changes:
       - Add hashPassword() method
       - Add comparePassword() method
       - Use bcrypt for hashing

Phase 3: Testing
  5. [write] Create tests/auth.test.ts
     Purpose: Test authentication flow
     Tests:
       - User can login with valid credentials
       - Login fails with invalid credentials
       - Protected routes require authentication
       - JWT tokens are validated correctly
       
  6. [bash] npm install bcrypt jsonwebtoken
     Purpose: Install required dependencies
     
  7. [bash] npm test -- tests/auth.test.ts
     Purpose: Verify authentication works

Summary:
  Files created: 3
  Files modified: 2
  Tests added: 4
  Dependencies: 2
  Estimated time: 5-10 minutes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

JSON Plan Output

For programmatic processing:

qwen --approval-mode plan --prompt "Add logging" --output-format json

Output:

{
  "type": "result",
  "isError": false,
  "plan": {
    "steps": [
      {
        "tool": "write",
        "target": "src/utils/logger.ts",
        "purpose": "Create centralized logging utility",
        "estimatedSize": 120
      },
      {
        "tool": "edit",
        "target": "src/app.ts",
        "purpose": "Import and initialize logger",
        "changes": ["Add logger import", "Initialize logger"]
      }
    ],
    "summary": {
      "filesCreated": 1,
      "filesModified": 1,
      "dependencies": ["winston"],
      "estimatedDuration": "2-3 minutes"
    }
  }
}

Combining with Other Options

Plan with Specific Model

# Use powerful model for detailed plans
qwen --model qwen-coder-plus --approval-mode plan \
     --prompt "Migrate from REST to GraphQL"

Plan in CI/CD

# Generate plan as part of PR review
qwen --approval-mode plan --prompt "Implement requested feature" \
     --output-format json > ai-plan.json

# Review plan in PR comments

Iterative Planning

# Generate multiple plans
qwen --approval-mode plan --prompt "Approach 1: Use microservices"
qwen --approval-mode plan --prompt "Approach 2: Use monolith"

# Compare and choose
qwen --yolo --prompt "Implement approach 2"

Plan -> Execute Workflow

Step 1: Generate Plan

qwen --approval-mode plan --prompt "Refactor payment processing" > plan.txt

Step 2: Review Plan

cat plan.txt
# Review the proposed changes

Step 3: Execute Plan

# If satisfied with plan, execute
qwen --yolo --prompt "Refactor payment processing"

# Or execute with manual approval
qwen --prompt "Refactor payment processing"

Alternative: Manual Implementation

# Use plan as a guide
cat plan.txt

# Implement manually following the plan

Plan Mode vs Other Modes

Mode	Generates Plan	Executes Actions	Prompts User
plan	Yes	No	No
default	No	Yes	Yes
auto-edit	No	Yes (edits only)	Partial
yolo	No	Yes (all)	No

Use Cases

Architecture Review

qwen --approval-mode plan --prompt "
Propose an architecture for:
- User authentication
- Role-based access control
- API rate limiting
- Caching layer
"

Get a detailed plan without any implementation.

Security Audit

qwen --approval-mode plan --prompt "Identify and fix security vulnerabilities"

Review proposed fixes before applying.

Performance Optimization

qwen --approval-mode plan --prompt "Optimize database queries in the checkout flow"

Understand optimization strategy first.

Dependency Updates

qwen --approval-mode plan --prompt "Update all dependencies to latest versions"

See what would be updated and test impact.

Automation Examples

Plan Generation Script

#!/bin/bash
# generate-plans.sh

TASKS=(
  "Add unit tests for all services"
  "Implement caching layer"
  "Add API documentation"
  "Setup CI/CD pipeline"
)

for task in "${TASKS[@]}"; do
  echo "Generating plan for: $task"
  qwen --approval-mode plan --prompt "$task" \
       --output-format json > "plan-$(echo $task | tr ' ' '-').json"
done

echo "All plans generated!"

Compare Approaches

#!/bin/bash
# compare-approaches.sh

APPROACHES=(
  "Use Redux for state management"
  "Use Context API for state management"
  "Use Zustand for state management"
)

for approach in "${APPROACHES[@]}"; do
  qwen --approval-mode plan --prompt "$approach" \
       --output-format json > "plan-${approach// /-}.json"
done

# Compare plans
echo "Compare the generated plans to choose the best approach"

Weekly Planning

#!/bin/bash
# weekly-plan.sh

# Generate plans for the week's tasks
qwen --approval-mode plan --prompt "Review backlog and create implementation plans" \
     --output-format text > weekly-plan.md

echo "Weekly plan saved to weekly-plan.md"

Limitations

No Actual Feedback

Plans are based on assumptions:

# Plan assumes file exists
qwen --approval-mode plan --prompt "Edit config.ts"
# But config.ts might not exist!

# Execution might differ from plan

Cannot Test Feasibility

# Plan might suggest:
"Run npm install some-package"

# But package might not exist or be incompatible

No Tool Feedback

Plans don’t include tool results:

# Plan says: "Read database.ts"
# But can't see what's actually in the file
# So next steps might not be accurate

Workaround

Generate plan, then execute incrementally:

# Get overall plan
qwen --approval-mode plan --prompt "Task"

# Execute step-by-step with feedback
qwen --prompt "Do step 1 from the plan"
> Review result

qwen --prompt "Do step 2 from the plan"
> Review result

Best Practices

Use for Complex Tasks

Plan mode is most valuable for complex operations:

# Simple task - just do it
qwen --prompt "Add a comment"

# Complex task - plan first
qwen --approval-mode plan --prompt "Refactor entire architecture"

Review Plans Critically

Plans are suggestions, not guarantees:

• Verify file paths exist
• Check if tools are available
• Ensure commands are safe
• Validate dependencies exist

Save Plans for Reference

Keep plans for documentation:

qwen --approval-mode plan --prompt "Migration plan" > migration-plan.md
git add migration-plan.md
git commit -m "Add AI-generated migration plan"

Iterate on Plans

Refine plans before executing:

# Get initial plan
qwen --approval-mode plan --prompt "Implement feature"

# Refine the approach
qwen --approval-mode plan --prompt "Implement feature using approach B instead"

# Execute final plan
qwen --yolo --prompt "Implement feature using approach B"

Advanced Techniques

Multi-Stage Planning

# Stage 1: High-level plan
qwen --approval-mode plan --prompt "Migrate to microservices architecture"

# Stage 2: Detailed plan for each service
qwen --approval-mode plan --prompt "Detailed plan for User service migration"
qwen --approval-mode plan --prompt "Detailed plan for Order service migration"

# Execute incrementally
qwen --yolo --prompt "Migrate User service"
# Test
qwen --yolo --prompt "Migrate Order service"

Plan Templates

# Create reusable plan templates
cat > plan-template.txt << 'EOF'
Generate a plan to:
1. Analyze current implementation
2. Identify issues and improvements
3. Propose refactoring approach
4. List required changes
5. Suggest testing strategy
EOF

qwen --approval-mode plan --prompt "$(cat plan-template.txt) for the authentication module"

Conditional Plans

#!/bin/bash
# Generate different plans based on conditions

if [ "$PROJECT_TYPE" = "microservices" ]; then
  qwen --approval-mode plan --prompt "Add service mesh"
else
  qwen --approval-mode plan --prompt "Add API gateway"
fi

Troubleshooting

Plan Too Vague

If plans lack detail:

# Vague prompt = vague plan
qwen --approval-mode plan --prompt "Improve the code"

# Specific prompt = detailed plan
qwen --approval-mode plan --prompt "Reduce response time of /api/users endpoint from 500ms to 100ms"

Plan Incomplete

If plans are missing steps:

# Ask for comprehensive plan
qwen --approval-mode plan --prompt "
Create a comprehensive plan including:
- All file changes
- Dependency updates
- Configuration changes
- Testing strategy
- Deployment steps

For: Implementing user authentication
"

Plan Doesn’t Match Needs

If the approach isn’t right:

# Specify constraints
qwen --approval-mode plan --prompt "
Plan for adding caching, but:
- Don't use Redis (not available)
- Must work in serverless environment
- Prefer in-memory caching
"

See Also

--yolo Option

Execute plans automatically

Approval Modes

Understanding all approval modes

Planning Best Practices

Advanced planning techniques

Interactive Mode

Use plan mode interactively