how to plan a large ruby refactor with an AI agent before it edits code

Use Atlas's plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas researches your Ruby modules and RSpec specs with codebase_search, grep, read, and the lsp tool, and writes the design into a plan markdown file. Nothing in app/ or lib/ changes until you approve plan_exit.

can atlas edit my rails models while in plan mode

No. The Atlas plan agent is described as "Plan mode. Disallows all edit tools." Its permissions deny edit for every path except .atlas/plans/*.md, and every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so a .rb file under app/models cannot be written while plan mode is active.

what does plan_exit do in atlas

plan_exit ends Atlas's plan mode. It asks "Plan at is complete. Would you like to switch to the build agent and start implementing?" Answering Yes hands off to the build agent that can edit Ruby files and run Bundler, RSpec, and RuboCop. Answering No raises Question.RejectedError and keeps you refining the plan.

how does atlas find every caller of a ruby method across files

Atlas combines three signals. codebase_search queries a semantic index that indexes code by AST declarations using tree-sitter, grep matches the exact method or constant name, and the lsp tool walks the symbol graph to surface callers, including methods mixed in through an included module rather than defined locally.

does atlas run bundle exec rspec automatically after a change

The Atlas build agent can run bundle exec rspec, and every tool call including bash is permission-gated against allow, ask, and deny rules before it runs. The plan agent cannot run edits at all. Atlas's documented Ruby setup is to run atlas in a project with a Gemfile, let it read your modules, gems, and Rakefile tasks, then review the diff.

how do i review an atlas diff before it writes to my ruby files

Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to a .rb file or a *_spec.rb file is shown as a patch you approve or reject. Atlas also snapshots file changes as git patches, so an approved edit can still be diffed and rolled back.

can atlas run rubocop on the files it changed in ruby

Yes, once you have handed off to the build agent through plan_exit. RuboCop is the formatter in the documented Ruby toolchain alongside Bundler as the package manager and RSpec as the test runner, and the build agent runs shell commands through Atlas's permission-gated tooling.

is atlas a terminal tool or an IDE plugin for ruby development

Atlas is a terminal-native TUI rendered with SolidJS through the OpenTUI renderer. You run atlas inside a Ruby project that has a Gemfile, and it works against your existing Bundler, RSpec, and RuboCop setup rather than replacing your editor.

Plan a multi-file change before editing in Ruby with Atlas (2026)

To plan a multi-file change in a Ruby project before editing, run Atlas and switch to its plan agent, whose description is literally "Plan mode. Disallows all edit tools." The plan agent denies edit for every path except .atlas/plans/*.md, so Atlas can read your Gemfile, your app/models and lib/ directories, your Rakefile tasks, and your spec/ suite without touching a single .rb file. You research with codebase_search, grep, read, and the lsp tool, you write the design into the plan markdown, and only when you call plan_exit and answer Yes does Atlas hand off to the build agent that can actually run Bundler, RSpec, and RuboCop against your code.

How does Atlas plan a multi-file Ruby change without editing any code?

Atlas ships a plan agent described as "Plan mode. Disallows all edit tools." In a Ruby repo with a Gemfile, its permission set denies edit for "*" and allows writes under exactly 1 path, .atlas/plans/*.md, so research across app/, lib/, and spec/ cannot silently become an edit.

The plan agent is a permission boundary, not a suggestion. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and in plan mode the deny rule for edit covers every path in the repository except the plan markdown. That means Atlas can open app/models/subscription.rb, follow the module into lib/billing/, and cross-reference spec/models/subscription_spec.rb, all while being structurally incapable of rewriting any of them. For a Ruby change that touches a model, a service object, a Rake task, and three RSpec files at once, this is exactly the property you want: the design gets written down and reviewed before Bundler installs anything or RSpec runs anything against modified code.

Which Atlas tools stay available in plan mode for a Ruby codebase?

The Atlas plan agent keeps 4 research tools available: codebase_search, grep, read, and the lsp tool. In a Ruby project that is enough to map every include, every mixin, and every RSpec describe block a multi-file change will disturb, without a single write to a .rb file.

codebase_search runs against Atlas's semantic index, which indexes code by AST declarations using tree-sitter rather than blind line windows, so a query like "where do we memoize the current account" returns real Ruby method declarations rather than an arbitrary 40-line slice. grep gives you exact-text confirmation when you already know the constant or the method name. read pulls the file. The lsp tool walks the symbol graph, which matters in Ruby where a method can arrive through an included module rather than being defined in the class you are looking at. Atlas also searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so the constant name and the plain-language description of the behavior both pull the same file to the top.

Where does Atlas write the Ruby change plan, and what goes in it?

Atlas writes the Ruby change plan into .atlas/plans/*.md, the 1 path the plan agent is allowed to write. For a Ruby refactor that plan should name each .rb file to be touched, each RSpec spec file that will need a new example, and the Bundler gems the change depends on.

The plan markdown is the deliverable of plan mode. Because the plan agent's permission set allows edit only under .atlas/plans/*.md, the plan file is where all of Atlas's design output has to land. A good Ruby plan enumerates the concrete surface: the modules in lib/ that get extracted, the classes in app/services/ that change signature, the Rakefile tasks that call them, and the RSpec examples in spec/ that pin current behavior. It is a document a human reviews before any code moves, and because Atlas computes a unified diff for every file edit and surfaces it for approval before writing, the plan is the first of two review gates, not the only one.

What is plan_exit and how does the handoff to the build agent work?

plan_exit is the Atlas tool that ends plan mode, and it offers 2 answers. It asks "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?" Answer Yes and Atlas moves to the build agent. Answer No and Atlas raises Question.RejectedError and keeps refining the Ruby plan.

plan_exit is deliberately a question, routed through Atlas's question tool, not an automatic transition. Answering No is a first-class outcome: Question.RejectedError is raised and you stay in the read-only plan agent, still able to run codebase_search and grep against your Ruby sources, still unable to edit them. Answering Yes hands off to the build agent, which is the agent that can finally edit app/ and spec/, run bundle install, run bundle exec rspec, and run bundle exec rubocop. The gate is explicit, so the moment a design turns into an edit is a moment you chose.

How do you review the Ruby diff after the build agent starts implementing?

Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to app/models/*.rb or spec/*_spec.rb arrives as a reviewable patch. Atlas also snapshots file changes as git patches, so in 2026 a bad edit to a Ruby module can be diffed and rolled back.

Review in Atlas happens at the diff, not after the fact. When the build agent rewrites a class in lib/ or adds an RSpec example, the unified diff is shown and the write is permission-gated against allow, ask, and deny rules before it runs. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, so once bundle exec rspec is green and bundle exec rubocop is clean, the commit is one more approval away. Because Atlas snapshots file changes as git patches, a half-applied multi-file Ruby refactor is recoverable rather than a manual cleanup job.

Step by step

01Run atlas in the root of a Ruby project that has a Gemfile, so Atlas can read your gems, modules, and Rakefile tasks.
02Switch to the Atlas plan agent, whose permissions deny edit for "*" and allow it only under .atlas/plans/*.md, so no .rb file can change while you design.
03Ask codebase_search a plain-language question about the behavior you are changing, then confirm the exact constants and method names with grep across app/, lib/, and spec/.
04Walk the Ruby symbol graph with the lsp tool to find every caller, including methods that arrive through an included module rather than a local def.
05Write the design into the plan markdown under .atlas/plans/, listing each .rb file to touch, each RSpec spec file that needs an example, and any Bundler gem the change requires.
06Call plan_exit and read the prompt: "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?" Answer No to keep refining, which raises Question.RejectedError and returns you to plan mode.
07Answer Yes to hand off to the build agent, then review the unified diff Atlas computes for each Ruby file before it is written to disk.
08Have the build agent run bundle exec rspec for the RSpec suite and bundle exec rubocop for RuboCop, then let Atlas stage and create the commit once both are clean.

Frequently asked questions

how to plan a large ruby refactor with an AI agent before it edits code: Use Atlas's plan agent. Its permission set denies edit for "*" and allows writes only under .atlas/plans/*.md, so Atlas researches your Ruby modules and RSpec specs with codebase_search, grep, read, and the lsp tool, and writes the design into a plan markdown file. Nothing in app/ or lib/ changes until you approve plan_exit.
can atlas edit my rails models while in plan mode: No. The Atlas plan agent is described as "Plan mode. Disallows all edit tools." Its permissions deny edit for every path except .atlas/plans/*.md, and every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so a .rb file under app/models cannot be written while plan mode is active.
what does plan_exit do in atlas: plan_exit ends Atlas's plan mode. It asks "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?" Answering Yes hands off to the build agent that can edit Ruby files and run Bundler, RSpec, and RuboCop. Answering No raises Question.RejectedError and keeps you refining the plan.
how does atlas find every caller of a ruby method across files: Atlas combines three signals. codebase_search queries a semantic index that indexes code by AST declarations using tree-sitter, grep matches the exact method or constant name, and the lsp tool walks the symbol graph to surface callers, including methods mixed in through an included module rather than defined locally.
does atlas run bundle exec rspec automatically after a change: The Atlas build agent can run bundle exec rspec, and every tool call including bash is permission-gated against allow, ask, and deny rules before it runs. The plan agent cannot run edits at all. Atlas's documented Ruby setup is to run atlas in a project with a Gemfile, let it read your modules, gems, and Rakefile tasks, then review the diff.
how do i review an atlas diff before it writes to my ruby files: Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each change to a .rb file or a *_spec.rb file is shown as a patch you approve or reject. Atlas also snapshots file changes as git patches, so an approved edit can still be diffed and rolled back.
can atlas run rubocop on the files it changed in ruby: Yes, once you have handed off to the build agent through plan_exit. RuboCop is the formatter in the documented Ruby toolchain alongside Bundler as the package manager and RSpec as the test runner, and the build agent runs shell commands through Atlas's permission-gated tooling.
is atlas a terminal tool or an IDE plugin for ruby development: Atlas is a terminal-native TUI rendered with SolidJS through the OpenTUI renderer. You run atlas inside a Ruby project that has a Gemfile, and it works against your existing Bundler, RSpec, and RuboCop setup rather than replacing your editor.

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.

Trace a Runtime Bug From a Stack Trace in Ruby with Atlas (2026)

How to go from a Ruby backtrace to the responsible line with Atlas in 2026: read each frame at its offset, grep the error string, walk callers, then lock it with RSpec.

Rename a Symbol Across a Ruby Repo with Atlas (2026)

How Atlas renames a Ruby method, class, or constant repo-wide in 2026: lsp findReferences for the true reference set, grep for strings, edit with replaceAll, RSpec to prove it.

Audit a Repo with Parallel Subagents in Ruby with Atlas in 2026

Sweep your Ruby repository for issues without context window limits using Atlas's parallel subagents. Leverage Bundler, RSpec, and RuboCop for efficient, targeted audits.

Self-review your working diff before committing in Ruby with Atlas in 2026

In 2026, Ruby developers use Atlas to self-review uncommitted diffs, catching mistakes before CI. Leverage RSpec, Bundler, and RuboCop with Atlas's terminal-native AI agent.

Locate Where a Behavior Is Implemented in Ruby with Atlas (2026)

Find the exact Ruby file and method behind a behavior in 2026. Atlas combines codebase_search, grep, read, and lsp across your Gemfile, app tree, and RSpec suite.

Upgrade a Ruby Dependency and Fix Breakage with Atlas in 2026

Upgrade Ruby gems and fix breaking changes with Atlas in 2026. Atlas drives Bundler, reads RSpec output, and repairs code, ensuring your Ruby projects stay current and functional.

Run Atlas Headless in CI for Ruby Projects in 2026

Automate Atlas in your Ruby CI/CD pipelines by 2026. Get machine-readable output for RSpec, Bundler, and RuboCop tasks, ensuring safe, non-interactive code generation.

Browse this resource hub