# Onboard to an Unfamiliar Astro Codebase in 2026 with Atlas

> Atlas helps Astro developers build a working mental model of unfamiliar codebases by starting from meaning, not filenames, and focusing on core Astro configuration and content collections.

To build a working mental model of an unfamiliar Astro repository without reading every file, Atlas leverages its semantic index, allowing you to query concepts directly. It then guides you through key Astro files like "astro.config.mjs" and "src/content.config.ts", using tools like "glob" and "read", before delegating wider exploration to a read-only subagent. This approach helps Astro developers quickly grasp project structure and logic, integrating with "pnpm" for package management and "vitest" for testing.

## Key takeaways

- Atlas uses semantic search to understand Astro code, starting from meaning, not just filenames.
- `glob` and `read` tools quickly map Astro project structure and dive into `astro.config.mjs` or `src/content.config.ts`.
- The `explore` subagent provides safe, read-only wide sweeps across `.astro` components and content collections.
- Every Atlas action, from adding Zod schemas to formatting with `prettier (prettier-plugin-astro)`, is permission-gated and diff-reviewed.
- Atlas integrates directly with Astro's toolchain, including `pnpm` for dependencies and `vitest` for testing.

## How does Atlas semantically search an Astro codebase?

Atlas helps Astro developers in 2026 quickly grasp unfamiliar codebases by starting with meaning, not just filenames. Its "codebase_search" tool queries a semantic index built using tree-sitter, allowing you to ask plain-language questions about Astro concepts like 'how requests are authenticated' or 'where are the 3 main content collections defined'.

Atlas's "codebase_search" tool is your initial entry point into an unfamiliar Astro project. Instead of blindly opening files, you can ask a plain-language question, such as 'how are requests authenticated in this Astro project?'. Atlas queries its semantic index, which is built by parsing AST declarations using tree-sitter, not blind line windows. This means Atlas understands the structure of your `.astro` components, `src/content.config.ts` schemas, and `astro.config.mjs` integrations. The tool returns ranked snippets with file paths, pointing you directly to the most relevant code, whether it is a specific `.astro` island or a configuration file. Atlas can build this code index with local Ollama embeddings, ensuring your Astro codebase remains off third-party servers.

## How to map Astro project structure with Atlas glob?

After an initial semantic search, Atlas helps you map the physical layout of an Astro project using the "glob" tool. This allows you to quickly inspect top-level directories and understand naming conventions, such as identifying "src/pages" for routing or "src/content" for content collections, all within 1 to 2 commands.

Once "codebase_search" has given you a conceptual starting point, the "glob" tool helps you understand the physical layout of the Astro repository. Running `glob 'src/*'` will quickly reveal the common Astro directory structure, showing you `src/pages` for file-based routing, `src/components` for reusable UI elements, `src/layouts` for page templates, and `src/content` for content collections. This step is crucial for building a mental model of where `.astro` components, Markdown, MDX, or other assets are organized. It allows you to grasp the project's conventions and anticipate where specific types of Astro-related code reside before you even open a file.

## How does Atlas read and navigate Astro files?

Once you have a high-level understanding, Atlas allows you to deep dive into specific Astro files using the "read" tool, often focusing on the 2 to 3 most relevant files identified by "codebase_search". For instance, you might `read astro.config.mjs` to understand integrations or `src/content.config.ts` to review content collection schemas.

With a structural overview from "glob" and semantic pointers from "codebase_search", you can use the "read" tool to inspect the actual contents of key Astro files. This is where you might `read astro.config.mjs` to understand which integrations are active or how the build process is configured. You can also `read src/content.config.ts` to examine the schemas for content collections, which is vital for understanding data structures. Furthermore, Atlas's "lsp" tool, with its `goToDefinition` operation, allows you to follow imports and navigate dependencies within `.astro` components or TypeScript files. This means you can jump from a component's import statement directly to the definition of a utility function or a Zod schema, building a precise mental map of the Astro project's internal connections.

## How to safely explore an Astro codebase with subagents?

For wider, read-only sweeps across an unfamiliar Astro codebase, Atlas delegates work to the "explore" subagent, which operates with a deny-by-default permission set. This ensures that while the subagent can `grep` for specific patterns across `.astro` files or `glob` for new directories, it cannot make any changes, providing a safe environment for exploration in 2026.

When you need to perform broad investigations without the risk of accidental modifications, Atlas's "explore" subagent is invaluable. This subagent is defined with a deny-by-default permission set, meaning it can only execute explicitly allowed tools like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This read-only constraint makes it ideal for tasks such as `explore task 'grep for all client:load directives in .astro files'` to understand hydration patterns, or `explore task 'find all instances of Zod schemas in src/content'` to map data validation. The "explore" subagent fans out work to subagents that can run in the foreground or in parallel background sessions, allowing for efficient and safe wide-ranging inquiries across your Astro project.

## How does Atlas ensure safety and review in Astro?

Atlas prioritizes safety and transparency throughout the onboarding process, ensuring every proposed change, even minor ones like dropping a `client:load` directive in an `.astro` component, is permission-gated. Before any file is written, Atlas computes a unified diff, which you must approve, providing 100% control over modifications in your Astro project.

Safety is a core tenet of Atlas. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs. When Atlas drafts a plan, it does so in a read-only plan agent, asking for your approval before switching to a build agent that can make changes. For any proposed modification, such as letting Atlas add a Zod schema to a content collection in `src/content.config.ts` and running `astro check`, or dropping an unnecessary `client:load` directive in an `.astro` component, Atlas computes a unified diff. This diff is surfaced for your approval, giving you 100% control over what gets written to your Astro codebase. Atlas also snapshots file changes as git patches, so edits can be diffed and rolled back, and can even stage and create commits on your behalf, ensuring a secure and auditable workflow.

## Steps

1. Run atlas in a project with an astro.config.mjs to allow Atlas to index your Astro codebase.
2. Ask codebase_search "how are requests authenticated in this Astro project?" to get semantic pointers to relevant `.astro` files or configuration.
3. Run glob 'src/*' to understand the layout of `src/pages`, `src/content`, and `src/components` within the Astro project.
4. Read the top 2 to 3 files identified by codebase_search, such as `astro.config.mjs` or `src/content.config.ts`, then use lsp goToDefinition to follow imports within `.astro` components.
5. Delegate a wide search to the explore subagent: task 'grep for all instances of client:load directives in .astro files' to understand hydration patterns safely.
6. Record your insights and open questions using todowrite, for example: 'TODO: Investigate the purpose of the custom Astro integration in astro.config.mjs'.
7. Review any proposed changes, approve the diff, and let Atlas format with prettier (prettier-plugin-astro) if modifications were made to maintain code style.

## FAQ

### How does Atlas understand Astro-specific files like .astro components?

Atlas indexes code by AST declarations using tree-sitter, allowing it to understand the structure and content of `.astro` files, content collection schemas in `src/content.config.ts`, and `astro.config.mjs` integrations, rather than just treating them as plain text.

### Can Atlas help me understand Astro content collections?

Yes, Atlas can read your `src/content.config.ts` to understand content collection schemas and even assist in adding a Zod schema to a content collection, running `astro check` behind a permission prompt to validate changes.

### Is it safe to let Atlas explore my Astro codebase?

Absolutely. Atlas's `explore` subagent operates with a deny-by-default permission set, allowing only read-only operations like `grep` and `glob`. It cannot modify any files in your Astro project without explicit approval.

### How does Atlas integrate with Astro's build process or package manager?

While Atlas focuses on code understanding and modification, it recognizes and works within your existing Astro environment. It understands `pnpm` as the package manager and can prompt for `astro check` or `prettier (prettier-plugin-astro)` for formatting, integrating with your established toolchain.

### What if Atlas makes a change I don't like in my Astro project?

Atlas computes a unified diff for every file edit and surfaces it for your approval before writing. You have 100% control, and Atlas also snapshots file changes as git patches, so edits can be diffed and rolled back easily.

### Can Atlas help me refactor Astro components or directives?

Yes, Atlas can assist with specific tasks like dropping an unnecessary `client:load` directive so a component ships as static HTML instead of an island, or suggesting changes to `src/pages` routes, always with a diff for your review.

### How does Atlas handle Astro's zero-JS-by-default rendering model?

Atlas understands Astro's rendering model through its AST indexing. It can identify `.astro` islands and client directives, and can even propose modifications to ensure components ship as static HTML when appropriate, aligning with Astro's core principles.

---

Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-astro
Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-astro` (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.