How do I stop an AI agent from editing my Next.js files while it is still researching?

Use Atlas plan mode. The plan agent's permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so research across the App Router cannot accidentally write app/layout.tsx or a route handler.

What is plan mode in Atlas?

Plan mode is an Atlas agent whose description is literally Plan mode. Disallows all edit tools. It researches with codebase_search, grep, read, and the lsp tool, writes a plan markdown, and calls plan_exit to ask whether to switch to the build agent.

Can Atlas plan a Next.js server component migration before touching code?

Yes. In plan mode Atlas reads your app directory and server and client boundaries, greps for every "use client" directive, and writes the migration order into .atlas/plans/*.md. No file outside that path can be edited until plan_exit is answered with Yes.

What happens if I reject the Atlas plan_exit prompt?

Answering No to plan_exit raises Question.RejectedError and returns you to the plan agent with the plan markdown intact. You keep refining the plan with codebase_search and the lsp tool instead of implementing it.

Does Atlas run Vitest with React Testing Library on a Next.js change?

Yes, once the build agent takes over after plan_exit. Run Vitest with React Testing Library after each file in the plan lands rather than once at the end, so a broken component spec is caught next to the change that broke it.

Where does Atlas store the plan file in a Next.js repo?

Atlas writes it under .atlas/plans/*.md, which is the only path the plan agent's permission set allows it to edit. Keeping the plan in the repo means it is reviewable and diffable alongside the change itself.

How does Atlas find every file a Next.js change will touch?

Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion through codebase_search, then uses grep for literal matches like next/headers imports and the lsp tool to find callers of a type that is changing.

Plan a Multi-File Change Before Editing in Next.js with Atlas (2026)

To plan a multi-file change in Next.js before editing anything, switch Atlas to the plan agent. The plan agent's description is literally Plan mode. Disallows all edit tools, and its permission set denies edit for every path except the plan markdown under .atlas/plans/*.md. Research still works: codebase_search, grep, read, and the lsp tool all stay allowed, so you can trace an App Router change from app/layout.tsx through every server component and route handler it touches. When the plan is written, plan_exit asks whether to switch to the build agent, and only then can pnpm install, Vitest with React Testing Library, and prettier come into play against real edits.

How do you plan a multi-file Next.js change before editing with Atlas?

Atlas plans a multi-file Next.js change in the plan agent, whose description is literally Plan mode. Disallows all edit tools. The plan agent's permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so 2026 research across the App Router cannot quietly become an edit.

A Next.js change is rarely one file. Converting a client component tree to server components touches app/(dashboard)/page.tsx, the components it imports, the route handler in app/api/orders/route.ts that it fetches from, and often next.config.ts. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, which is precisely the shape that work needs. In plan mode Atlas can read your app directory, your routes, and your server and client boundaries, list every file with a "use client" directive, and write the design down. What it cannot do is edit app/layout.tsx. The single writable path is the plan markdown, and that constraint is enforced by the permission set, not by the model's good intentions.

Which Atlas tools stay available in Next.js plan mode?

Atlas plan mode keeps 4 research tools available for Next.js work: codebase_search, grep, read, and the lsp tool. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a question about where the session is read returns the right server component even when the code never says session.

Plan mode is not a downgrade in what Atlas can learn, only in what it can change. Use codebase_search for the conceptual questions, such as where the App Router revalidates cached data. Use grep for the literal ones, such as every file containing "use client" or every import of next/headers. Use read to pull app/api/orders/route.ts in full, and use the lsp tool to check which components import a type you are about to change. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a Next.js page component and its generateMetadata export come back as whole declarations. All of that research runs while the edit tool is denied for every path except the plan markdown.

Where does Atlas write the Next.js plan file?

Atlas writes the Next.js plan into .atlas/plans/*.md, the one path the plan agent's permission set allows it to edit, and denies edit for every other path. That includes next.config.ts, app/layout.tsx, and every route handler, so in 2026 a design document is still the only artifact a plan session can produce.

The plan markdown is where the multi-file change actually gets designed. A good Next.js plan names the files in order: the server component that moves first, the client boundary that has to be pushed down, the route handler whose response shape changes, and the Vitest with React Testing Library specs that must be updated alongside them. Writing it into .atlas/plans/*.md means the plan is reviewable in the same pull request as the change and diffable if the design shifts. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so even the plan file itself lands only after you have seen the exact content going in.

What does plan_exit do in a Next.js Atlas session?

The plan_exit tool ends Atlas plan mode by asking 1 question: Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answering Yes hands the Next.js change to the build agent. Answering No raises Question.RejectedError and keeps you refining the plan.

The handoff is a deliberate gate rather than a silent transition. Until plan_exit is answered with Yes, no Atlas tool can write app/page.tsx or app/api/orders/route.ts. After Yes, the build agent picks up the plan and starts implementing against it, and every file edit still arrives as a unified diff you approve. If the plan is wrong, answering No is not a failure state: Question.RejectedError just returns you to the plan agent with the markdown intact, and you keep researching with codebase_search and the lsp tool. In a large Next.js migration this is often the loop you spend the most time in, and spending it there is much cheaper than spending it in a half-applied refactor.

How do you verify a planned Next.js change after the build agent takes over?

Once plan_exit hands a Next.js change to the Atlas build agent, verification runs on the project's real toolchain in 3 moves: pnpm installs, Vitest with React Testing Library runs the component specs, and prettier formats the touched files. Atlas snapshots file changes as git patches so edits can be diffed and rolled back.

The plan told you which files change and in what order, so verification can follow the same order. After the build agent converts a client component to a server component, run Vitest with React Testing Library on that component's spec before moving to the next file, not once at the end. Run pnpm against package.json when the plan called for a dependency change, and run prettier so the diff is style-clean before review. If a step in the plan turns out to be wrong once real code exists, Atlas snapshots file changes as git patches so edits can be diffed and rolled back, and you can return to the plan agent to revise .atlas/plans/*.md rather than improvising in the middle of the App Router.

Step by step

01Run atlas in a Next.js project with a next.config file so Atlas can read your app directory, routes, and server and client boundaries.
02Switch to the plan agent; its permissions deny edit for "*" and allow it only under .atlas/plans/*.md.
03Research the change with codebase_search, grep, read, and the lsp tool; all four stay allowed in plan mode.
04Grep for "use client" across the app directory to enumerate every client boundary the multi-file change will have to move.
05Write the plan into the allowed plan markdown path under .atlas/plans/*.md, listing the route handlers, server components, and Vitest with React Testing Library specs in the order they change.
06Call plan_exit: it asks Plan at <path> is complete. Would you like to switch to the build agent and start implementing?
07Answer Yes to hand off to the build agent; answering No raises Question.RejectedError and keeps you refining the plan.
08Let the build agent apply the change file by file, approving each unified diff Atlas surfaces before it writes.
09Run Vitest with React Testing Library after each file lands, and run pnpm when package.json changes.
10Run prettier on the touched files so the Next.js diff is style-clean before you open the pull request.

Frequently asked questions

How do I stop an AI agent from editing my Next.js files while it is still researching?: Use Atlas plan mode. The plan agent's permission set denies edit for "*" and allows it only under .atlas/plans/*.md, so research across the App Router cannot accidentally write app/layout.tsx or a route handler.
What is plan mode in Atlas?: Plan mode is an Atlas agent whose description is literally Plan mode. Disallows all edit tools. It researches with codebase_search, grep, read, and the lsp tool, writes a plan markdown, and calls plan_exit to ask whether to switch to the build agent.
Can Atlas plan a Next.js server component migration before touching code?: Yes. In plan mode Atlas reads your app directory and server and client boundaries, greps for every "use client" directive, and writes the migration order into .atlas/plans/*.md. No file outside that path can be edited until plan_exit is answered with Yes.
What happens if I reject the Atlas plan_exit prompt?: Answering No to plan_exit raises Question.RejectedError and returns you to the plan agent with the plan markdown intact. You keep refining the plan with codebase_search and the lsp tool instead of implementing it.
Does Atlas run Vitest with React Testing Library on a Next.js change?: Yes, once the build agent takes over after plan_exit. Run Vitest with React Testing Library after each file in the plan lands rather than once at the end, so a broken component spec is caught next to the change that broke it.
Where does Atlas store the plan file in a Next.js repo?: Atlas writes it under .atlas/plans/*.md, which is the only path the plan agent's permission set allows it to edit. Keeping the plan in the repo means it is reviewable and diffable alongside the change itself.
How does Atlas find every file a Next.js change will touch?: Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion through codebase_search, then uses grep for literal matches like next/headers imports and the lsp tool to find callers of a type that is changing.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Plan a Multi-File Change Before Editing with Atlas in 2026

How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.

Atlas for Next.js in 2026

Adopt Atlas, the terminal-native AI coding agent, for Next.js development in 2026. Enhance productivity across App Router, server components, and API routes with secure, reviewable AI assistance.

Trace a runtime bug from a stack trace in Next.js with Atlas in 2026

Pinpoint and fix Next.js runtime bugs from production stack traces without a debugger. Atlas leverages its AI tools to navigate your Next.js codebase, identify root causes, and propose fixes with `Vitest with React

Write Unit Tests for Untested Next.js Code with Atlas in 2026

In 2026, Atlas helps Next.js developers write unit tests for untested code using Vitest and React Testing Library. Automate test generation, match existing conventions, and ensure code quality in your Next.js projects

Diagnose a hanging or long-running command in Next.js with Atlas in 2026

In 2026, use Atlas to diagnose hanging or slow Next.js builds, tests, or scripts. Pinpoint if `pnpm build` or `pnpm vitest` is blocked on input or genuinely slow, and get unstuck quickly.

Locate where a behavior is implemented in Next.js with Atlas in 2026

In 2026, Atlas helps Next.js developers pinpoint exact file and symbol implementations for any behavior, leveraging semantic search, grep, and LSP across your app directory and API routes.

Self-review your working diff before committing in Next.js with Atlas in 2026

Next.js developers in 2026 use Atlas to self-review uncommitted diffs, catching mistakes before CI. Leverage Vitest, prettier, and pnpm with Atlas's AI agent.

Add a Regression Test for a Next.js Bug Fix with Atlas in 2026

Lock in Next.js bug fixes with robust regression tests using Atlas. Learn to write failing tests with Vitest and React Testing Library, then apply fixes and verify passes in your Next.js project.

Browse this resource hub