Tutorial: Plandex for plan-then-apply multi-file refactors

Professional Firms & Consultants

IT consultants and firms working on legacy client codebases who need tools making every change reversible and inspectable.

Discover →

Preliminary notes

Content provided “as-is”. Before using in production:

• Work on a copy or a dedicated branch of the repo.
• Back up before every session: even though Plandex keeps its own change sandbox, a workflow mistake can still apply unwanted diffs.
• Never place secrets in prompts or config files. Plandex ships context to the configured LLM provider.
• For NDA-bound code or regulated data, prefer a local or private LLM endpoint.
• Plandex is a moving project: command syntax (new, tell, apply, diff) may vary between versions. Check the docs for the version installed.

What Plandex is

Plandex (plandex.ai, github.com/plandex-ai/plandex) is a terminal-based multi-file code-editing agent released as open source in 2024. What sets it apart from Aider or similar pair-programming tools is the plan-then-apply model: the agent’s proposed changes do not touch the working tree immediately; they accumulate in a separate plan, inspectable via plandex diff, and hit disk only after an explicit plandex apply.

Operationally this means the agent can iterate across dozens of files of a plan (e.g. extracting a module across 40 files of a monolith) without ever leaving the repo in an intermediate inconsistent state. For consultants intervening on third-party code, that safety trait is valuable.

Use case: naming migration from camelCase to snake_case in a legacy Python library

An internal Python library has historically used camelCase functions — clashing with PEP 8 and with the convention adopted in the client’s new modules. We want to rename them to snake_case and update every call site across about fifty files, while keeping backwards-compatibility via deprecated aliases.

1. Preparation

cd ~/projects/client/libX
git checkout -b refactor/snake_case
python -m pytest           # green baseline

2. Install Plandex

# Official binary (Go):
curl -sL https://plandex.ai/install.sh | bash
plandex --version

# Cloud or local provider: use whatever config you prefer.
# Example via env (avoid committing keys):
read -rs OPENROUTER_API_KEY && export OPENROUTER_API_KEY

3. New plan in the working tree

plandex new
# Plandex creates a state associated with the current directory.
# The git working tree is untouched.

4. Provide targeted context

Plandex uses explicit context: you declare which files are relevant. Avoiding a full-repo load keeps cost and noise low.

plandex load src/libX/*.py tests/*.py
plandex ls                  # check what is in context

5. Plan instruction

plandex tell "Rename all public functions from camelCase to snake_case. \
Update every call site inside src/libX/ and tests/. \
Keep a deprecated alias with DeprecationWarning for every previous name. \
Do not touch docstrings. \
Proceed file by file."

Plandex starts the model and produces changes. Changes land in the plan sandbox, not on disk. While it runs, you can:

plandex diff                # see accumulated diffs
plandex diff src/libX/core.py   # one file
plandex log                 # the plan's steps

6. Review and per-task rollback

If a step produces a wrong diff, you can roll back selectively without losing the rest of the plan:

plandex log
# output like:
#   [step 7]  update test_core.py
#   [step 8]  update core.py
plandex rewind 7            # undo step 7 and subsequent; keep 1..6

This is Plandex’s most useful trait in a consulting context: if step 12 introduces a bug, you do not throw away the 11 previously approved steps.

7. Final apply

When the sandbox is consistent:

plandex diff                 # full review
plandex apply                # write to the git working tree
pytest                       # regression check
git status
git add -p                   # granular staging, not a blanket commit
git commit -m "refactor: migrate public API to snake_case with deprecated aliases"

If tests fail, git state is still recoverable with git restore because selective staging limited what entered the index.

Limits and caveats

• A plan is not a substitute for a git branch: at the end, plandex apply lands changes on the working tree. Working on a dedicated branch is still the main safety net.
• Loaded context strongly affects quality: if load is too narrow, the agent will rename functions in one file while missing call sites in other modules. Too broad and cost/noise explode. The balance depends on the refactor.
• The model can fabricate non-existent names: on codebases with heavy metaprogramming (dynamic getattr, string-based factories) a pure rename refactor can miss things. Regression tests are the required check.
• Token cost on long plans: 50 files in one plan means many model calls. Monitor spend, split into smaller plans where possible, and for repetitive tasks consider cheaper models (DeepSeek Coder, local CodeLlama).
• Use parallel plans carefully: Plandex supports multiple plans in the same directory. Running two concurrent plans on overlapping code areas causes conflicts — behave as you would with crossing git branches.

Link: plandex.ai — github.com/plandex-ai/plandex

Stefano Noferi — Founder e CEO/CTO di noze
Tech Entrepreneur — AI Governance & Security Architect