> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parsaa.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan Mode

> Let Parsaa analyze, plan, and execute complex multi-file changes with your approval

## Overview

For complex changes that span multiple files, Plan Mode keeps you in control. Parsaa analyzes the work, proposes a step-by-step plan, and executes only after you approve. Nothing runs without your explicit consent.

<Info>
  During the planning phase the agent works read-only — it gathers context but does not modify your project until the plan is approved.
</Info>

## How It Works

<Steps>
  <Step title="Analyze">
    Parsaa reads the relevant parts of your project to understand the architecture, files, and relationships involved in your request.
  </Step>

  <Step title="Design">
    Parsaa proposes a plan: the specific steps it will take, which files change, and in what order.
  </Step>

  <Step title="Approve">
    You review the plan before anything runs. Approve it, ask for changes (revise), or reject it.
  </Step>

  <Step title="Execute">
    Once approved, Parsaa runs the steps one at a time. Exactly one step is in progress at a time, and you can stop execution at any point.
  </Step>
</Steps>

## Plan & Step Status

A plan moves through these states, surfaced in the activity tray:

| Plan status       | Meaning                                    |
| ----------------- | ------------------------------------------ |
| Awaiting Approval | Plan proposed; waiting for your review     |
| Approved          | You approved the plan                      |
| Executing         | Steps are running                          |
| Completed         | All steps finished or skipped              |
| Rejected          | You rejected the plan or requested changes |
| Cancelled         | You stopped execution mid-run              |
| Failed            | An unrecoverable error occurred            |

Each step is tracked individually: **pending → in progress → completed** (or **failed** / **skipped**).

## When to Use Plan Mode

<CardGroup cols={2}>
  <Card title="Multi-file Refactors" icon="layer-group">
    Rename a protocol and update all conforming types, or restructure how data flows between layers.
  </Card>

  <Card title="New Features" icon="plus">
    Add a feature touching models, views, view models, and networking — Plan Mode maps out every change.
  </Card>

  <Card title="Architectural Changes" icon="sitemap">
    Introduce a coordinator pattern, restructure module boundaries, or adopt a new framework.
  </Card>

  <Card title="Pattern Migration" icon="right-left">
    Convert delegate-based APIs to async/await, or replace singletons with dependency injection.
  </Card>
</CardGroup>

## Safety

<AccordionGroup>
  <Accordion title="Nothing executes without approval">
    Every plan requires explicit approval before Parsaa writes any code. You see what will change and where.
  </Accordion>

  <Accordion title="Stop at any point">
    During execution you can cancel. Already-applied steps stay in place for you to review.
  </Accordion>

  <Accordion title="Review every change">
    Code changes surface as diffs in an approval card before they're applied, so you confirm each edit.
  </Accordion>
</AccordionGroup>

<Tip>
  For single-file, scoped edits, capture the Xcode selection and ask directly — see [Capture Code & Context](/features/context-capture). Use Plan Mode when a change touches multiple files or needs coordinated edits.
</Tip>