# Onboard to an Unfamiliar React Codebase with Atlas (2026) > Atlas onboards you to a React codebase by asking codebase_search a plain-language question, mapping src/ with glob, and reading only the files that actually matter. To onboard to an unfamiliar React codebase with Atlas, start from meaning rather than filenames. Ask codebase_search a plain-language question, such as how requests are authenticated, and Atlas queries the semantic index and returns ranked snippets with file paths, even when the component is not named anything you would have guessed. Run glob over the top-level directories to see the package layout before opening anything, read only the two or three files codebase_search ranked highest, and follow imports with the lsp tool's goToDefinition operation. Heavy fan-out goes to the explore subagent, which is permissioned read-only so it cannot change a line of your React app while it looks around. ## Key takeaways - Start from meaning: codebase_search answers how requests are authenticated even when the React logic lives in a hook named useSession. - Run glob on top-level directories first, so you learn whether components live in src/components or src/features before you read one. - The lsp tool's goToDefinition operation follows the React import graph, which is the app's real structure, not the directory tree. - The explore subagent is deny-by-default and read-only, allowing only grep, glob, read, bash, webfetch, and websearch, so it cannot change a .tsx file. - Subagent file reads stay in the subagent's own session, so a wide React sweep never fills your main context window. - Record open questions as a todowrite list, and run Vitest with React Testing Library to see what the suite already covers. ## How do I understand a React codebase without reading every file? Ask Atlas's codebase_search a plain-language question, for example how requests are authenticated. Atlas queries the semantic index and returns ranked snippets with file paths, so a React app with 400 components in src/ collapses to the 3 files that actually answer your question. Onboarding fails when it starts with a file tree. A React repository presents hundreds of .tsx files, and the component that owns the behavior you care about is rarely named after it: the auth logic lives in a custom hook called useSession, not in Auth.tsx. Atlas starts from meaning instead. codebase_search takes the question as you would ask a colleague and queries the semantic index, returning ranked snippets with paths. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and indexes by AST declarations using tree-sitter, so the hits come back as real React components and hooks rather than arbitrary windows of a file. ## How do I map a React project's structure before opening files? Run glob on the top-level directories to see the package layout and naming conventions before opening anything. In a React app that means learning in 1 command whether components live in src/components or src/features, whether hooks are colocated, and whether the build is Vite or Next. Structure is context, and it is cheap to acquire. Atlas runs glob over the top-level directories to reveal the shape: src/components next to src/hooks tells you one architecture, src/features with colocated hooks and tests tells you a different one. The config files at the root are equally informative, a vite.config.ts or a next.config.js says what the build is, package.json names the scripts you will actually run, and the presence of a pnpm-lock.yaml tells you the package manager is pnpm. Knowing the conventions before you read a component means you read it as an example of a pattern rather than as an isolated file. ## How do I follow a React component's imports and hooks? Read the two or three files codebase_search ranked highest, then follow imports with the lsp tool's goToDefinition operation. In React that is how you get from a component in src/features/ to the custom hook it calls to the context provider that hook consumes, in 3 hops instead of a filename hunt. React's real structure is the import graph, not the directory tree. A component renders, calls useSession, and that hook reads a context whose provider is mounted somewhere in the app shell, and none of that is visible from the file you are reading. Atlas walks it with the lsp tool's goToDefinition operation, hopping from the call to the declaration, from the hook to the context, from the context to the provider. Reading the highest ranked files first and following the graph from there is far cheaper than opening src/ and working alphabetically, and it produces an understanding shaped like the app instead of shaped like the filesystem. ## How do I sweep a large React repo without filling the context window? Delegate wide sweeps to Atlas's explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that allows only 6 tools, grep, glob, read, bash, webfetch, and websearch, so it cannot modify a single .tsx file while it maps your React app. Some onboarding questions are wide rather than deep: which components still use class syntax, which routes exist, which features import a deprecated hook. Answering those means reading a lot of files, and reading a lot of files into your main session ruins it. Atlas's task tool launches the explore subagent in its own session, so the file dumps stay there and only the conclusions come back. The permission posture matches the intent exactly: explore is deny-by-default and read-only, allowing grep, glob, read, bash, webfetch, and websearch and nothing that writes, which is what you want from an agent whose whole job is to look around. ## How do I keep what I learned about a React codebase? Record what you learned as a todowrite list so the open questions survive into the next turn. Onboarding to a React app produces 10 answers and 5 new questions, and the questions are the part that evaporates when the session ends unless something is holding them. Understanding that lives only in a chat scrollback is understanding you will rebuild next week. Atlas writes what it found into a todowrite list, both the confirmed structure and the loose ends: the hook whose dependency array looks wrong, the component that seems dead, the route with no test. That list is what you actually work from. When you start changing things, run Vitest with React Testing Library through bash to see the existing coverage, and prettier before any commit. Every Atlas tool call is permission-gated against allow, ask, and deny rules, so the exploration phase cannot alter the React app you are still learning. ## Steps 1. Run atlas in a React project with a package.json and let Atlas read your components, hooks, and bundler configuration. 2. Ask codebase_search a plain-language question, for example how requests are authenticated; it queries the semantic index and returns ranked snippets with file paths. 3. Run glob on the top-level directories to see the package layout and naming conventions before opening anything, including whether the build is Vite or Next. 4. Read the two or three files codebase_search ranked highest, rather than opening src/ and working alphabetically. 5. Follow imports with the lsp tool's goToDefinition operation, hopping from a component to the custom hook it calls to the context provider that hook consumes. 6. Delegate 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. 7. Run Vitest with React Testing Library through the bash tool to see what the existing suite already covers and where it does not. 8. Record what you learned as a todowrite list so the open questions survive into the next turn, and run prettier before any commit. ## FAQ ### how to understand a new react codebase quickly Ask Atlas's codebase_search a plain-language question like how requests are authenticated, run glob on the top-level directories to learn the layout, then read only the two or three files codebase_search ranked highest and follow imports with the lsp tool. ### how do i find which react hook handles authentication Describe the behavior to codebase_search rather than guessing at filenames. React auth logic usually lives in a custom hook such as useSession rather than in a file named Auth.tsx, and the semantic index finds it by meaning. ### atlas explore subagent permissions The explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch. It cannot modify a .tsx file, which makes it the right agent for mapping a React app you do not yet understand. ### how do i follow imports in a react app with an ai agent Use the lsp tool's goToDefinition operation through Atlas. It hops from a component to the custom hook it calls to the context provider that hook consumes, which is far faster than hunting through src/ by filename. ### will exploring a codebase with atlas change my files No. codebase_search, glob, and read are read-only, the explore subagent is deny-by-default, and every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs. ### how do i see what tests a react project already has Run Vitest with React Testing Library through Atlas's bash tool and read the results. Knowing which components already have coverage tells you which parts of the React app the team considers load bearing. ### how do i set up atlas in a react project Run atlas in a React project with a package.json and let Atlas read your components, hooks, and bundler configuration. From there you can have it convert class components to hooks or add React Testing Library tests, reviewing the diff. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-react Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-react` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.