Atlas onboards you to an unfamiliar Node.js codebase by starting from meaning, not filenames. codebase_search queries the semantic index for the concepts you care about, glob maps the directory shape around package.json, and read pulls only the files that actually matter, so you never open all 900 modules. Heavy fan-out goes to the explore subagent through the task tool, which is permissioned read-only and so cannot change anything while it looks around. The result is a working model of the npm scripts, the Express or Fastify route table, and the node:test suite, assembled in one terminal session.
How do you understand a new Node.js codebase without reading every file?
Ask Atlas's codebase_search a plain-language question such as "how are requests authenticated". Atlas queries the semantic index and returns ranked snippets with file paths, so a 900-module Node.js repo collapses to the 3 files that actually handle auth, typically an Express middleware in src/middleware/ and a helper in src/lib/.
Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and indexes code by AST declarations using tree-sitter, not blind line windows. In a Node.js project that means a hit is a whole exported function or a whole `router.post(...)` handler, not a 40-line window sliced through the middle of a callback chain. Start with the questions that map a service: how requests are authenticated, where the database connection is created, what runs on startup. Each answer names real files. Then read package.json first, before any source: the `scripts` block tells you how the maintainers actually run the thing, whether `npm test` shells out to node:test or to something else, and the `dependencies` list tells you whether you are looking at Express, Fastify, or a bare http server.
How does glob map the shape of a Node.js repository?
Run Atlas's glob tool on the top-level directories to see the package layout and naming conventions before opening anything. In a Node.js repo, glob patterns like `src/**/*.js`, `**/package.json`, and `test/**/*.test.js` reveal in seconds whether you are in a single service or an npm workspaces monorepo with 12 packages.
Structure carries information that no single file does. A glob for `**/package.json` that returns eight results tells you immediately that npm workspaces are in play and that the root package.json is a manifest, not the app. A glob for `src/routes/**/*.js` tells you the Express routing is file-organized; if it returns nothing, routing is probably registered imperatively in a single app.js. Glob for `*.config.js`, `.prettierrc`, and `tsconfig.json` to learn what the toolchain expects, and glob for `test/**` or `**/*.test.js` to see how the node:test suite is laid out. All of it is read-only, and every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so a mapping pass on an unfamiliar Node.js repo cannot modify anything.
How do you follow imports through a Node.js project with Atlas?
Read the 2 or 3 files codebase_search ranked highest, then follow imports with Atlas's lsp tool using its goToDefinition operation. In a Node.js service that walks you from a route handler in src/routes/users.js into the service layer and down to the database client, without you guessing at relative require paths.
Node.js module resolution is where manual tracing gets slow: a `require('../lib/db')` in one file and an `import { db } from '#lib/db'` using subpath imports in another can point at the same module, and a barrel file in src/index.js can re-export a symbol three hops from where it was defined. goToDefinition resolves that graph properly instead of pattern-matching on the string. Pair it with findReferences when you want the reverse direction, for example every place a `getUser` helper is called. Read files in full rather than in fragments, because in Node.js the top of a file is where the interesting parts live: the imports, the exported shape, and whether the module is CommonJS or ESM, which the `"type": "module"` field in package.json decides for the whole package.
What is the Atlas explore subagent and why is it safe on an unfamiliar repo?
Atlas delegates wide sweeps to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot edit a single file in your Node.js repo while it maps 900 modules for you.
Fan-out is the expensive part of onboarding, and it is also the part you least want an agent to do with write access. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so you can ask the explore subagent to characterize every route file under src/routes/ while you read the auth middleware yourself. Because the explore subagent's permission set is deny-by-default and allows only the six read-oriented tools, the worst it can do is read your Node.js source and report back. Its bash access still runs through Atlas's permission layer, so `npm ls` or `node --test` is a prompt you approve rather than a command that just happens. Record what the sweep learned as a todowrite list, so the open questions survive into the next turn instead of evaporating with the context window.
How do you check your understanding of a Node.js codebase is correct?
Prove your model of a Node.js repo by running its own tests. Execute `npm test` through Atlas's bash tool and read what node:test actually asserts, because the suite is the 1 executable specification the repo has. A behavior nobody asserts is a behavior nobody promised.
The fastest way to be wrong about a new codebase is to trust a mental model you never exercised. Run `npm test` and watch which node:test files touch the modules codebase_search pointed you at. If the auth middleware in src/middleware/auth.js has no test/auth.test.js, that is itself a finding worth a todowrite entry. Read the npm scripts too: a `start`, a `dev`, and a `test` script tell you the intended entry points, and `npm ls` shows the real dependency tree behind package.json. When you do start changing things, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and running `npx prettier --write` keeps prettier happy on anything you add. Atlas snapshots file changes as git patches, so a first-day experiment can be rolled back cleanly.
Step by step
- 01Run atlas where the Node.js package.json lives, so npm scripts, dependencies, and the source tree are all in scope.
- 02Ask codebase_search a plain-language question such as "how requests are authenticated"; it queries the semantic index and returns ranked snippets with file paths.
- 03Run glob on the top-level directories, using patterns like `**/package.json`, `src/**/*.js`, and `**/*.test.js`, to see the package layout and naming conventions before opening anything.
- 04Read package.json first: the scripts block tells you how the maintainers run the service, and the dependencies list tells you whether it is Express, Fastify, or bare http.
- 05Read the two or three files codebase_search ranked highest, then follow imports with the lsp tool's goToDefinition operation to walk from a route handler into the service layer.
- 06Delegate 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.
- 07Run `npm test` with bash and read what node:test asserts, because the suite is the only executable specification the repo has.
- 08Record what you learned as a todowrite list so the open questions survive into the next turn.
Frequently asked questions
- how to quickly understand a large Node.js codebase
- Ask Atlas's codebase_search plain-language questions like "how are requests authenticated", map the tree with glob on `**/package.json` and `src/**/*.js`, read package.json's scripts and dependencies, then run `npm test` to see what the node:test suite actually asserts.
- can an AI agent explore my Node.js repo without editing it
- Yes. Atlas's explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch. Every Atlas tool call is also permission-gated against allow, ask, and deny rules before it runs.
- how do I trace an Express route to the database layer
- Read the route handler in src/routes/, then use Atlas's lsp tool goToDefinition operation to follow the imports down through the service layer to the database client. goToDefinition resolves CommonJS requires and ESM barrel re-exports that string matching gets wrong.
- what should I read first in an unfamiliar Node.js project
- Read package.json before any source. Its scripts block shows how the maintainers run and test the service, its type field decides CommonJS versus ESM for the whole package, and its dependencies tell you whether you are looking at Express, Fastify, or bare http.
- how do I keep onboarding notes across Atlas sessions
- Record what you learned as a todowrite list. Atlas keeps the entries with their status, so the open questions about the Node.js repo survive into the next turn rather than evaporating with the context window.
- does Atlas need to upload my Node.js code to index it
- No. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, so codebase_search works over a private Node.js service while the index stays on your machine.
- can Atlas run npm test for me while onboarding
- Yes, through the bash tool, and the call is permission-gated against allow, ask, and deny rules before it runs. Running `npm test` and reading the node:test output is the fastest way to check that the model codebase_search gave you is actually right.
- how do I start Atlas in a Node.js project
- Run atlas where your Node package.json lives. Atlas reads your modules, npm scripts, and Express or Fastify routes, and you can then have it add middleware or supertest cases, reviewing the diff before anything is written.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated 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.
Atlas for Node.js in 2026
Node.js developers in 2026 can adopt Atlas, the terminal-native AI coding agent, for secure, efficient development. Leverage local embeddings, AST indexing, and robust safety features.
Debug a Single Failing Test in Node.js with Atlas in 2026
Pinpoint and fix failing Node.js tests with Atlas in 2026. Learn how Atlas uses `node:test` and `npm` to isolate issues, walk call graphs, and apply precise code fixes.
Diagnose a Hanging or Long-Running Command in Node.js with Atlas in 2026
Node.js developers in 2026 can use Atlas to diagnose hanging `npm` scripts or `node:test` runs. Identify if a command is genuinely slow or blocked on input, and get it unstuck efficiently.
Plan a Multi-File Node.js Change Before Editing with Atlas (2026)
Design a multi-file Node.js change before a line is edited: Atlas plan mode denies all edit tools in 2026, writes the plan, then asks before switching to build.
Run Node.js Test Suites and Triage Failures with Atlas in 2026
Streamline Node.js test triage in 2026 with Atlas. Turn walls of `node:test` output into prioritized fixes, leveraging `npm` for efficient debugging and tracking.
Locate where a behavior is implemented in Node.js with Atlas in 2026
Pinpoint Node.js code behavior with Atlas in 2026. Use semantic search, grep, and LSP tools to find exact files and symbols in your npm projects, ensuring precise code navigation and understanding.
Review a pull request in Node.js with Atlas in 2026
In 2026, Node.js developers use Atlas to review pull requests, leveraging its AI to fetch diffs, analyze code context, run `node:test` suites, and ensure code quality with `npm` and `prettier`.