# Onboard to an Unfamiliar Quarkus Codebase with Atlas in 2026 > Atlas empowers Quarkus developers to quickly grasp unfamiliar codebases by focusing on meaning, not just filenames, and interacting directly with `Maven` and `JUnit 5 (@QuarkusTest)`. Atlas helps Quarkus developers in 2026 rapidly build a working mental model of unfamiliar codebases by leveraging semantic search, AST indexing, and direct interaction with `Maven` and `JUnit 5 (@QuarkusTest)` to pinpoint relevant code without exhaustive file reading. It understands Quarkus-specific constructs like CDI beans, JAX-RS resources, and `application.properties` configurations, allowing you to grasp project architecture and behavior efficiently. ## Key takeaways - Atlas indexes Quarkus code by AST declarations, understanding CDI beans, JAX-RS resources, and `application.properties`. - `codebase_search` uses semantic indexing with local Ollama embeddings to answer Quarkus-specific questions. - `glob` and `lsp goToDefinition` help navigate Quarkus project structure and dependencies efficiently. - The `explore` subagent provides a safe, read-only environment for deep dives into unfamiliar Quarkus code. - Atlas assists with Quarkus native-image compatibility and validates changes using `JUnit 5 (@QuarkusTest)` via `Maven`. - All proposed changes are presented as unified diffs for approval and formatted with `Spotless` before committing. ## How Atlas Understands Quarkus Project Structure and Idioms In 2026, Atlas builds its understanding of a Quarkus codebase by indexing AST declarations using tree-sitter, not blind line windows. This allows it to precisely map CDI beans, JAX-RS resources, and `application.properties` configurations, providing a 10x faster initial grasp of project architecture compared to manual file exploration. Atlas is designed to deeply understand the specific nuances of Quarkus projects. It starts by analyzing your `pom.xml` to identify the `quarkus-bom` and other dependencies, establishing the project's foundational context. Unlike tools that rely on simple keyword matching, Atlas uses Abstract Syntax Tree (AST) declarations to index your code. This means it recognizes the structural roles of your CDI beans, the definitions of your JAX-RS resources, and the specific properties within `application.properties`. This AST-based indexing allows Atlas to build a rich, semantic model of your Quarkus application, enabling it to answer complex questions about how different components interact, how services are injected, or how configurations are applied, all without you needing to open a single file initially. ## Semantic Search for Quarkus-Specific Concepts To quickly grasp how requests are authenticated in a Quarkus application, Atlas's `codebase_search` tool allows developers in 2026 to ask plain-language questions. It queries a semantic index built with local Ollama embeddings, ensuring code stays off third-party servers and providing highly relevant snippets within seconds. When faced with an unfamiliar Quarkus codebase, knowing where to start is often the biggest challenge. Atlas's `codebase_search` tool addresses this by allowing you to ask natural language questions directly related to your Quarkus application's functionality. For instance, you can ask 'how are requests authenticated?' or 'where are the JAX-RS endpoints defined for user management?'. Atlas leverages a semantic index, built locally using Ollama embeddings, to find code snippets that are conceptually related to your query, even if they don't contain the exact keywords. This approach is particularly effective in Quarkus, where build-time augmentation can sometimes obscure runtime behavior, allowing you to cut through the complexity and find the most relevant CDI beans, JAX-RS resources, or security configurations quickly. The results are ranked snippets with file paths, giving you immediate pointers to the most important areas of the codebase. ## Navigating Quarkus Project Layout and Dependencies Understanding the directory shape and naming conventions of a new Quarkus project is crucial, and Atlas facilitates this by running `glob` on top-level directories. This initial scan, often completed in under 1 second, reveals the package layout before any files are opened, allowing developers to then `read` key files and follow imports using the `lsp` tool's `goToDefinition` operation. After an initial semantic search, Atlas helps you orient yourself within the physical structure of the Quarkus project. The `glob` tool provides a high-level overview of the directory and package layout, helping you understand common Quarkus conventions for organizing source code, resources, and tests. Once you've identified a few key files from `codebase_search` results or `glob` output, you can use the `read` tool to inspect their contents. For deeper dives, the `lsp` tool's `goToDefinition` operation is invaluable. This allows you to direct navigate through the codebase by following imports, method calls, or bean injections, tracing the flow of control and data across different Quarkus components. This is especially powerful for understanding how a JAX-RS endpoint might interact with a CDI service, or how a configuration property from `application.properties` is consumed by a specific class, without manually searching for definitions. ## Safe and Controlled Exploration with Subagents For wide sweeps and deeper investigations into an unfamiliar Quarkus 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`, `glob`, `read`, `bash`, `webfetch`, and `websearch`, it cannot modify any files, providing a 100% safe environment for initial discovery. When you need to perform broader investigations or gather more context about a specific area of a Quarkus project, Atlas allows you to delegate these tasks to the `explore` subagent using the `task` tool. This subagent is specifically designed for read-only operations, making it an ideal companion for onboarding. Its permission set is strictly controlled, allowing it to use tools like `grep` to find patterns, `glob` to map directories, `read` to inspect files, `bash` for general system commands, and `webfetch` or `websearch` for external context, but it is explicitly denied any write access. This means you can confidently ask the `explore` subagent to 'find all JAX-RS endpoints that use a specific security annotation' or 'list all CDI beans that implement a certain interface' without any risk of unintended modifications to your Quarkus codebase. ## Validating and Refactoring Quarkus Code with Atlas When modifying a Quarkus application, Atlas can help replace runtime reflection with build-time-friendly patterns, crucial for native-image compatibility in 2026. It can also add `@QuarkusTest` cases with `RestAssured` and run `./mvnw test` behind a permission prompt, ensuring changes are validated against the existing `JUnit 5` test suite. Beyond just understanding, Atlas assists in making changes to a Quarkus codebase. A key challenge in Quarkus, especially for native-image compilation, is avoiding runtime reflection. Atlas can identify such patterns and suggest or implement build-time-friendly alternatives, ensuring your code remains compatible and performant. When you're ready to validate your understanding or proposed changes, Atlas can draft new `@QuarkusTest` cases, often leveraging `RestAssured` for robust API testing. Crucially, Atlas integrates directly with your `Maven` build system. It can execute your `JUnit 5 (@QuarkusTest)` suite by running the `./mvnw test` command, but only after presenting a permission prompt for your explicit approval. This ensures that any automated testing or refactoring actions are transparent and under your control, maintaining the integrity of your Quarkus application. ## Reviewing and Committing Changes in Quarkus Projects Every file edit proposed by Atlas in a Quarkus project generates a unified diff for approval, providing a clear overview of changes before they are written. After review, Atlas can apply `Spotless` to ensure code formatting consistency, a process that takes less than 5 seconds, and then stage and create commits on your behalf, integrating smoothly with your existing git workflow. Transparency and control are paramount when working with an AI agent. Atlas ensures this by presenting a unified diff for every proposed file edit in your Quarkus project. Before any changes are written to disk, you have the opportunity to review exactly what Atlas intends to do. Once you approve the changes, Atlas can take further steps to integrate them into your development workflow. This includes applying `Spotless`, your configured Quarkus formatter, to ensure that all modified files adhere to your project's coding style guidelines. Atlas can then interact with git to stage the changes and create commits on your behalf, complete with descriptive messages. This direct integration means that Atlas acts as an extension of your development process, not a replacement, allowing you to maintain full oversight and quality control over your Quarkus codebase. ## Steps 1. Run `atlas` in your Quarkus project directory, ensuring a `pom.xml` that pulls in `quarkus-bom` is present. 2. Allow Atlas to read your CDI beans, JAX-RS resources, and the properties in `application.properties` to build its semantic index. 3. Ask `codebase_search` a plain-language question, such as 'how are requests authenticated in this Quarkus application?', to get ranked snippets. 4. Run `glob` on the top-level directories to quickly visualize the Quarkus package layout and naming conventions. 5. Use `read` to inspect the two or three files `codebase_search` ranked highest, then follow imports and definitions with `lsp goToDefinition`. 6. Delegate wide sweeps to the `explore` subagent through the `task` tool, for example: `task explore find all JAX-RS endpoints that use @RolesAllowed`. 7. Record any open questions or areas for further investigation as a `todowrite` list, like 'todowrite What is the purpose of the `MyService` CDI bean?'. 8. If making changes, ask Atlas to replace runtime reflection with a build-time-friendly pattern to ensure native-image compatibility. 9. Let Atlas add `@QuarkusTest` cases with `RestAssured` for new or modified functionality, then run `./mvnw test` behind a permission prompt. 10. Review the unified diff of all proposed changes, then let Atlas apply `Spotless` for formatting consistency before it commits. ## FAQ ### How does Atlas understand my Quarkus project's specific structure? Atlas indexes your Quarkus project by AST declarations using tree-sitter, recognizing CDI beans, JAX-RS resources, and `application.properties` configurations directly from your `pom.xml` and source files. This provides a deep, semantic understanding. ### Can Atlas help with Quarkus native-image compilation issues? Yes, Atlas can identify and replace runtime reflection patterns with build-time-friendly alternatives, which is crucial for successful native-image generation in Quarkus, ensuring your application remains performant and compatible. ### How does Atlas ensure code quality in Quarkus projects? Atlas integrates with your existing Quarkus toolchain, allowing it to run `JUnit 5 (@QuarkusTest)` cases via `./mvnw test` and apply `Spotless` for consistent code formatting, all behind explicit permission prompts before any changes are committed. ### Is it safe to let Atlas explore an unfamiliar Quarkus codebase? Absolutely. Atlas's `explore` subagent operates with a deny-by-default permission set, allowing it only to `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This ensures no modifications are made during exploration, providing a 100% safe environment. ### How does Atlas handle dependencies in a Quarkus `pom.xml`? Atlas understands `pom.xml` files, including the `quarkus-bom` for dependency management. It uses this context to build its code index, provide relevant suggestions, and ensure its actions are aligned with your project's declared dependencies. ### Can Atlas help me write new `JUnit 5 (@QuarkusTest)` tests? Yes, Atlas can draft new `@QuarkusTest` cases, often leveraging `RestAssured` for API testing, and can execute them using `./mvnw test` after your approval. This helps you quickly add validation for new features or bug fixes. ### What if I need to understand a specific JAX-RS endpoint's implementation? You can use `codebase_search` to ask 'how are requests handled by the `/api/v1/users` JAX-RS endpoint?' or use `lsp goToDefinition` from a client call to trace its implementation through your Quarkus services and CDI beans. ### Does Atlas keep my Quarkus code private? Yes, Atlas can build its code index with local Ollama embeddings, keeping your Quarkus code off third-party servers. Every Atlas tool call is also permission-gated, ensuring your code's privacy and security. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-quarkus Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-quarkus` (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.