how do I understand a large ruby codebase I just inherited

Start with codebase_search, not with the file tree. Ask a plain-language question such as "how are requests authenticated" and Atlas's semantic index returns ranked snippets with real Ruby paths. Then glob the top level to see app/, lib/, config/, spec/, and the Gemfile before you open anything.

how do I find where authentication happens in a rails app

Ask codebase_search directly. Because Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, it surfaces a before_action, a concern, or a Rack middleware even when none of those files contain the word you searched for.

how do I know if a ruby project uses rspec or minitest

Run glob on the top-level directories. A spec/ directory with a .rspec file means the suite is RSpec, so the command is bundle exec rspec and new examples belong under spec/. Atlas checks the layout with glob before assuming a test framework.

does atlas read my gemfile and rakefile

Yes. Run atlas in a project with a Gemfile and let Atlas read your modules, gems, and Rakefile tasks. Bundler pins the gem versions, so Atlas prefixes commands with bundle exec when running the RSpec suite through its bash tool.

how do I trace a method call in ruby when there are no imports

Use the lsp tool's goToDefinition operation, which Atlas calls directly. Ruby autoloading and metaprogramming mean a constant may have no visible require to follow, so the symbol graph is the only reliable way to walk from a controller action into the service object and model concern behind it.

how do I keep track of open questions while onboarding to a codebase

Record them as a todowrite list. Atlas writes open questions, such as which initializer configures an auth gem or whether a Rakefile task runs on deploy, as tracked items so they survive into the next turn instead of being lost with the conversation context.

will atlas follow the rubocop rules in my project

Atlas reads .rubocop.yml as part of mapping the project, so the style contract RuboCop enforces is visible before any code is written. Atlas also computes a unified diff for every file edit and surfaces it for approval before writing, so you review style along with substance.

Onboard to an Unfamiliar Ruby Codebase with Atlas in 2026

Atlas onboards you to an unfamiliar Ruby codebase by starting from meaning, not filenames. You ask codebase_search a plain-language question such as "how are requests authenticated", the semantic index returns ranked snippets with real paths like app/controllers/concerns/authenticable.rb, glob maps the directory shape around your Gemfile, and read opens only the two or three files that actually matter. Heavy fan-out goes to the explore subagent, which is permissioned read-only so it cannot change anything while it looks around your Rakefile, your gems, or your RSpec suite.

Key takeaways

Start from meaning: codebase_search answers "how are requests authenticated" in a Ruby repo where autoloading and metaprogramming defeat grep.
Glob the top level first: a Gemfile, a Rakefile, a spec/ directory, and a .rubocop.yml tell you Bundler, RSpec, and RuboCop govern the project.
The explore subagent is deny-by-default and only allows grep, glob, read, bash, webfetch, and websearch, so onboarding cannot accidentally edit your Ruby code.
Atlas indexes code by AST declarations using tree-sitter, so a hit is a real Ruby module, class, or method definition rather than an arbitrary line window.
The lsp tool's goToDefinition operation traces a Ruby call path that has no visible import statement to follow.
Record unresolved questions as a todowrite list, because the open questions are the most perishable output of onboarding.

How do you get up to speed on an unfamiliar Ruby codebase fast?

Atlas builds a mental model of an unfamiliar Ruby repository without reading every file, using 6 tools: codebase_search, glob, read, the lsp tool, task, and todowrite. You start with a plain-language question rather than a filename, because in a Gemfile project you rarely know the filename yet.

The job is to build a working mental model of a repository you have never seen before, without reading every file. A mature Ruby application defeats brute force. Rails-style autoloading means there are no import statements to follow, metaprogramming means a method may never appear as a literal def, and a Gemfile with sixty gems means half the behavior lives outside app/ entirely. Atlas therefore starts from meaning. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a hit is a real Ruby module, class, or method definition.

What should you ask codebase_search first in a Ruby repo?

Ask codebase_search the plain-language question you actually have, for example "how are requests authenticated". The semantic index returns ranked snippets with real Ruby file paths, so in a Rails-shaped repo you land in app/controllers/concerns/ or lib/ within 1 query instead of grepping for a method name you do not know yet.

Ruby rewards semantic search more than most languages because Ruby code hides its intent behind idiom. Authentication might be a before_action in an ApplicationController, a Rack middleware in config/application.rb, a concern mixed in with include, or a gem configured in an initializer. None of those necessarily contain the word you searched for. codebase_search queries the semantic index for the concepts you care about and returns declarations with paths and line numbers, which is a starting point you can actually read. Follow the ranked snippets, not your assumptions about where a Ruby project keeps things.

How do you map the directory layout of a Ruby project?

Atlas runs glob on the top-level directories to see the package layout and naming conventions before opening anything. In a Ruby project that reveals the shape in 1 command: a Gemfile and Gemfile.lock at the root, app/ and lib/, a Rakefile, config/, and a spec/ directory that tells you the suite is RSpec rather than Minitest.

Layout is a fact, and Atlas gathers it before forming opinions. The presence of spec/ and a .rspec file means the project runs RSpec, so the test command is bundle exec rspec and new examples belong in spec/models or spec/requests to match. A Gemfile plus Gemfile.lock means dependencies are managed by Bundler and every command should be prefixed with bundle exec so gem versions resolve the way CI resolves them. A .rubocop.yml means RuboCop governs style and any code you or Atlas add will be judged by it. Glob answers all of that without reading a single line of Ruby.

What is the Atlas explore subagent and why is it read-only?

Atlas delegates wide sweeps of a Ruby repo to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that only allows 6 tools: grep, glob, read, bash, webfetch, and websearch. No edit tool is in that list, so exploration cannot change your code.

Onboarding is exactly when you least want an agent writing to files. You do not yet know which Ruby modules are load-bearing, so a well-meaning refactor of a concern in app/models/concerns/ is the worst possible outcome of a reading session. The explore subagent's deny-by-default permission set removes the possibility rather than relying on good behavior. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so several explore sweeps across app/, lib/, and spec/ can run at once while you read the answers. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and the explore subagent is that mechanism turned all the way up.

How do you follow a Ruby call path once you have found the entry point?

Atlas reads the 2 or 3 files codebase_search ranked highest, then follows the code with the lsp tool's goToDefinition operation. In Ruby, where a require in lib/ or an autoloaded constant gives you no visible import to click, goToDefinition is the difference between tracing a call path and guessing at one.

Reading the top-ranked Ruby files gives you the surface. The lsp tool gives you the graph. From a controller action, goToDefinition takes you into the service object it delegates to; from there, into the model concern; from there, into the gem boundary where the code stops being yours. Atlas records the tour as it goes. Every step is anchored to a real file and line in app/, lib/, or spec/, so the mental model you end up with is checkable rather than a plausible story. Confirming a hypothesis with a quick bundle exec rspec spec/requests run through bash turns an assumption about behavior into an observation.

How do you keep what you learned about a Ruby repo?

Atlas records what you learned as a todowrite list, so the open questions survive into the next turn instead of evaporating when the context window rolls. After a 2-hour tour of an unfamiliar Ruby application, the list of unresolved questions is the most valuable artifact you have.

Onboarding produces two outputs: things you now understand and things you now know you do not understand. The todowrite list captures the second, which is the one people lose. Typical entries in a Ruby repo look like: confirm which initializer configures the auth gem, find out whether spec/support helpers are shared across the RSpec suite, check whether the Rakefile task that reindexes search is run in deploy. Atlas keeps those as tracked items rather than paragraphs of prose. When you come back and start changing code, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back.

Step by step

01Run atlas in the project root, the directory with the Gemfile, so Atlas can read your modules, gems, and Rakefile tasks.
02Ask codebase_search a plain-language question such as "how are requests authenticated"; it queries the semantic index and returns ranked snippets with real Ruby file paths.
03Run glob on the top-level directories to see the layout before opening anything: app/, lib/, config/, spec/, Gemfile, Gemfile.lock, Rakefile, .rubocop.yml.
04Read the two or three files codebase_search ranked highest, then follow the code with the lsp tool's goToDefinition operation, which matters in Ruby where autoloading leaves no import to click.
05Delegate wide sweeps to the explore subagent through the task tool; it is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot edit your Ruby files.
06Confirm a hypothesis about behavior by running the RSpec suite through bash with bundle exec rspec, letting Bundler resolve the gem versions the project pins.
07Check the style contract by reading .rubocop.yml, since RuboCop will judge anything you or Atlas add.
08Record open questions as a todowrite list so they survive into the next turn instead of being lost with the context.

Frequently asked questions

how do I understand a large ruby codebase I just inherited: Start with codebase_search, not with the file tree. Ask a plain-language question such as "how are requests authenticated" and Atlas's semantic index returns ranked snippets with real Ruby paths. Then glob the top level to see app/, lib/, config/, spec/, and the Gemfile before you open anything.
can an AI agent explore my ruby repo without changing anything: Yes. Atlas delegates wide sweeps to the explore subagent through the task tool, and that subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch. No edit tool is in the list, so it cannot modify your Ruby files.
how do I find where authentication happens in a rails app: Ask codebase_search directly. Because Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, it surfaces a before_action, a concern, or a Rack middleware even when none of those files contain the word you searched for.
how do I know if a ruby project uses rspec or minitest: Run glob on the top-level directories. A spec/ directory with a .rspec file means the suite is RSpec, so the command is bundle exec rspec and new examples belong under spec/. Atlas checks the layout with glob before assuming a test framework.
does atlas read my gemfile and rakefile: Yes. Run atlas in a project with a Gemfile and let Atlas read your modules, gems, and Rakefile tasks. Bundler pins the gem versions, so Atlas prefixes commands with bundle exec when running the RSpec suite through its bash tool.
how do I trace a method call in ruby when there are no imports: Use the lsp tool's goToDefinition operation, which Atlas calls directly. Ruby autoloading and metaprogramming mean a constant may have no visible require to follow, so the symbol graph is the only reliable way to walk from a controller action into the service object and model concern behind it.
how do I keep track of open questions while onboarding to a codebase: Record them as a todowrite list. Atlas writes open questions, such as which initializer configures an auth gem or whether a Rakefile task runs on deploy, as tracked items so they survive into the next turn instead of being lost with the conversation context.
will atlas follow the rubocop rules in my project: Atlas reads .rubocop.yml as part of mapping the project, so the style contract RuboCop enforces is visible before any code is written. Atlas also computes a unified diff for every file edit and surfaces it for approval before writing, so you review style along with substance.

Try Atlas in your terminal

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

Install Atlas

Related guides

Onboard to an Unfamiliar Codebase with Atlas in 2026

How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.

Diagnose a hanging or long-running command in Ruby with Atlas (2026)

How Atlas diagnoses a hanging or long-running Ruby command in 2026: read the shell_metadata block, tell a blocked Bundler prompt from a genuinely slow RSpec run.

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.

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.

Debug a Single Failing Test in Ruby with Atlas (2026)

Debug a single failing RSpec example in Ruby with Atlas in 2026. Run the spec in isolation with bash, walk the call path with lsp, and fix the code, not the assertion.

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.

Write unit tests for untested code in Ruby with Atlas (2026)

Add RSpec coverage to an untested Ruby module in 2026 with Atlas: enumerate methods with lsp documentSymbol, copy the repo's spec conventions, then run the suite.

Automate GitHub Issue and Pull Request Triage in Ruby with Atlas in 2026

Automate GitHub issue and pull request triage for Ruby projects using Atlas in 2026. Ensure safe, trusted responses with deep integration into `Bundler`, `RSpec`, and `RuboCop` workflows.

Browse this resource hub