> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# --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

```bash theme={null}
qwen --approval-mode plan
```

<Note>
  There is no short `-p` flag for plan mode (that's reserved for `--prompt`). Use the full `--approval-mode plan` syntax.
</Note>

## 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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Estimate token usage without executing
qwen --approval-mode plan --prompt "Generate comprehensive test suite" \
     --output-format json
```

### Code Reviews

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
qwen --approval-mode plan --prompt "Add logging" --output-format json
```

Output:

```json theme={null}
{
  "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

```bash theme={null}
# Use powerful model for detailed plans
qwen --model qwen-coder-plus --approval-mode plan \
     --prompt "Migrate from REST to GraphQL"
```

### Plan in CI/CD

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
qwen --approval-mode plan --prompt "Refactor payment processing" > plan.txt
```

### Step 2: Review Plan

```bash theme={null}
cat plan.txt
# Review the proposed changes
```

### Step 3: Execute Plan

```bash theme={null}
# If satisfied with plan, execute
qwen --yolo --prompt "Refactor payment processing"

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

### Alternative: Manual Implementation

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
qwen --approval-mode plan --prompt "Identify and fix security vulnerabilities"
```

Review proposed fixes before applying.

### Performance Optimization

```bash theme={null}
qwen --approval-mode plan --prompt "Optimize database queries in the checkout flow"
```

Understand optimization strategy first.

### Dependency Updates

```bash theme={null}
qwen --approval-mode plan --prompt "Update all dependencies to latest versions"
```

See what would be updated and test impact.

## Automation Examples

### Plan Generation Script

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Use for Complex Tasks">
    Plan mode is most valuable for complex operations:

    ```bash theme={null}
    # Simple task - just do it
    qwen --prompt "Add a comment"

    # Complex task - plan first
    qwen --approval-mode plan --prompt "Refactor entire architecture"
    ```
  </Accordion>

  <Accordion title="Review Plans Critically">
    Plans are suggestions, not guarantees:

    * Verify file paths exist
    * Check if tools are available
    * Ensure commands are safe
    * Validate dependencies exist
  </Accordion>

  <Accordion title="Save Plans for Reference">
    Keep plans for documentation:

    ```bash theme={null}
    qwen --approval-mode plan --prompt "Migration plan" > migration-plan.md
    git add migration-plan.md
    git commit -m "Add AI-generated migration plan"
    ```
  </Accordion>

  <Accordion title="Iterate on Plans">
    Refine plans before executing:

    ```bash theme={null}
    # 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"
    ```
  </Accordion>
</AccordionGroup>

## Advanced Techniques

### Multi-Stage Planning

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
#!/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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="--yolo Option" icon="forward-fast" href="/cli/options/yolo">
    Execute plans automatically
  </Card>

  <Card title="Approval Modes" icon="shield-check" href="/features/approval-modes">
    Understanding all approval modes
  </Card>

  <Card title="Planning Best Practices" icon="list-check" href="/advanced/planning">
    Advanced planning techniques
  </Card>

  <Card title="Interactive Mode" icon="messages" href="/features/interactive-mode">
    Use plan mode interactively
  </Card>
</CardGroup>