Docs › Agent

Plan mode

Agree the approach before the agent changes any code.

Plan mode writes a plan instead of writing code. The agent reads what it needs, then produces a document listing the steps it intends to take, which you can edit before anything runs.

It is worth using when the change is large enough that finding out mid-way that the approach was wrong is expensive: a migration, a refactor across several files, anything touching a part of the codebase you do not know well.

The plan is saved as a real file so it survives the conversation. By default it goes in the repository under .astracode/plans; set astracode.plan.location to home to keep plans out of the repo.

When you switch to Agent and build the plan, its steps become the run's todo list, so progress is visible against the thing you agreed.

Which files a step may change

Each step that changes code ends with the files it changes, for example - [ ] Rename priceFor (files: gateway/src/pricing.ts, editor/src/agent/cost.ts). A path ending in / covers everything under it. While a step is being built, the agent can edit only the files that step names. An edit to any other file is refused, and so is an edit made while no step is marked in progress. To let a step touch another file, type its name into the step's (files: ...) in the plan file; the next edit sees it. A step with no tag, such as running the tests, holds nothing, and a plan written before tags existed builds as it always did.

If a build stops part-way through a step, whether you pressed Stop or it reached its step limit, the editor offers to revert just that step's files. Steps already finished are left alone, and so is any file you have edited since the run stopped. Every other way back is under Checkpoints and undo.

All documentation

Get started

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Reference