# Onboard to an Unfamiliar Assembly Codebase in 2026 with Atlas > Atlas enables Assembly developers to build a working mental model of unfamiliar codebases by understanding register allocation, calling conventions, and the ABI, without reading every file. In 2026, Atlas helps Assembly developers quickly build a working mental model of unfamiliar x86-64 and ARM64 codebases by leveraging semantic search, AST indexing, and direct interaction with tools like `make check` for testing and `asmfmt` for formatting. Atlas understands the nuances of Assembly, from register allocation to calling conventions, allowing you to grasp complex projects without reading every single `.asm` or `.S` file. ## Key takeaways - Atlas indexes Assembly code by AST declarations, understanding sections, labels, and calling conventions like System V or AAPCS64. - Semantic search with `codebase_search` quickly identifies relevant `.asm` or `.S` files for specific Assembly concepts. - The `glob` tool provides a rapid overview of an Assembly project's directory structure and naming conventions. - Atlas's `lsp` tool enables precise navigation through Assembly code, following label definitions and routine calls. - The `explore` subagent performs safe, read-only wide sweeps across Assembly codebases using `grep` and `read`. - All Assembly code modifications are permission-gated, with unified diffs for approval and verification via `make check`. ## How Atlas Understands Assembly Codebases for Rapid Onboarding Atlas, in 2026, accelerates Assembly onboarding by indexing code with AST declarations using tree-sitter, rather than relying on blind line windows. This allows Atlas to understand the structure of `.asm` and `.S` files, recognizing sections, labels, and the specific calling conventions like System V or AAPCS64 honored by each routine. Atlas starts from meaning, not just filenames, when you begin onboarding to an unfamiliar Assembly codebase. It builds a robust code index using AST declarations, which is crucial for Assembly where the structure of sections and labels defines the program flow. This deep understanding allows Atlas to identify critical elements such as register allocation, calling conventions (like System V for x86-64 or AAPCS64 for ARM64), and the Application Binary Interface (ABI) that forms the contract between routines. When you run Atlas where your `.asm` or `.S` sources and `Makefile` reside, it automatically processes these files, creating a semantic map of the repository. This initial indexing can even use local Ollama embeddings, ensuring your proprietary Assembly code remains off third-party servers, a significant security advantage for sensitive projects. ## Exploring Assembly Project Structure and Conventions with Atlas To quickly grasp the layout of an unfamiliar Assembly project, Atlas provides the `glob` tool, allowing developers in 2026 to map top-level directories and understand naming conventions. This initial structural overview complements semantic search, providing context before diving into specific `.asm` or `.S` files. After Atlas has indexed the Assembly codebase, you can use the `glob` tool to get a high-level understanding of the project's directory structure and naming conventions. For instance, running `glob` on the top-level directories might reveal a `src/` folder for `.asm` files, a `tests/` directory for `make check` harnesses, and a `build/` output location. This visual map helps you understand where different components of the Assembly project are located. Following this, the `codebase_search` tool can be used to ask plain-language questions, such as 'how are requests authenticated in this x86-64 Assembly project?' It queries the semantic index and returns ranked snippets with file paths, pointing you directly to relevant `.asm` or `.S` files that define authentication routines, often involving specific register usage or system calls. ## Deep Diving into Assembly Code with Atlas's LSP and Read Tools Once Atlas identifies key Assembly files, the `read` tool allows developers to inspect the two or three highest-ranked `.asm` or `.S` files directly within the terminal. For deeper exploration, the `lsp` tool's `goToDefinition` operation enables following label definitions and routine calls, crucial for understanding complex control flow in 2026. After `codebase_search` provides initial insights, you can use the `read` tool to pull the most relevant Assembly source files into your terminal. For example, if `codebase_search` points to `src/auth.asm` and `src/crypto.S`, you can `read` these files to examine their contents. To understand how a specific label or routine is defined or used across the codebase, the `lsp` tool's `goToDefinition` operation is invaluable. This allows you to navigate through the Assembly code, following jumps, calls, and data references, which is essential for understanding register allocation and how different parts of the program interact via the ABI. Atlas's AST indexing ensures that `goToDefinition` works accurately, even for complex Assembly macros or nested routines, providing a precise understanding of the code's dependencies. ## Delegating Wide Sweeps and Recording Learnings in Assembly Projects For extensive exploration of an Assembly codebase, Atlas delegates wide sweeps to the `explore` subagent, which operates with a deny-by-default permission set, ensuring read-only safety. In 2026, this subagent can use `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch` to gather information without altering any `.asm` or `.S` files. When you need to perform a broader investigation across an unfamiliar Assembly project, the `task` tool allows you to delegate this to the `explore` subagent. This subagent is specifically designed for safe, read-only exploration. It operates with a strict permission set, allowing it to use tools like `grep` to find specific instruction patterns or register usage across all `.asm` files, `glob` to map out subdirectories, and `read` to inspect files. It can even use `bash` for simple commands or `webfetch` and `websearch` to look up documentation for specific Assembly instructions or calling conventions if needed. This ensures that while the subagent is looking around, it cannot accidentally modify any of your `.asm` or `.S` sources or the `Makefile`. As you learn new details about the Assembly codebase, you can record open questions or findings using the `todowrite` tool, creating a persistent list that survives across turns and helps you maintain your mental model. ## Ensuring Safety and Review for Assembly Code Modifications with Atlas Atlas ensures safety when modifying Assembly code by drafting a plan in a read-only agent and seeking approval before switching to a build agent. Every proposed change to `.asm` or `.S` files generates a unified diff for approval, and Atlas can assemble with `nasm` or GNU assembler, running `make check` behind a permission prompt in 2026. Before Atlas makes any changes to your Assembly codebase, it operates with a robust safety and review mechanism. First, it drafts a plan in a read-only plan agent, outlining the proposed modifications to `.asm` or `.S` files, perhaps to optimize a hot loop or adjust register usage. This plan is presented for your review and approval. Only after your explicit permission does Atlas switch to a build agent. For every file edit, Atlas computes a unified diff, surfacing it for your approval before writing any changes. This allows you to meticulously review every instruction change, ensuring correctness and adherence to the ABI. Furthermore, Atlas can assemble your code using `nasm` or the GNU assembler and run your test harness with `make check` behind a permission prompt, verifying that proposed changes do not introduce regressions. It also keeps alignment and column style consistent with `asmfmt` on all touched files, maintaining code quality and readability. ## Steps 1. Run `atlas` in your Assembly project's root directory where `.asm` or `.S` sources and your `Makefile` are located to allow Atlas to index sections, labels, and calling conventions. 2. Ask `codebase_search` a plain-language question, such as 'how are requests authenticated in this x86-64 Assembly project?', to get ranked snippets and file paths. 3. Run `glob` on the top-level directories to visualize the Assembly package layout and naming conventions before opening any `.asm` or `.S` files. 4. Use `read` to inspect the two or three `.asm` or `.S` files `codebase_search` ranked highest, then follow label definitions with the `lsp` tool's `goToDefinition` operation. 5. Delegate wide sweeps to the `explore` subagent via the `task` tool, allowing it to use `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch` to gather more context without modifying files. 6. Record what you learned about the Assembly codebase as a `todowrite` list, ensuring open questions and insights persist for future turns. 7. If proposing changes, review Atlas's unified diff for any modifications to `.asm` or `.S` files, and approve its use of `make (nasm toolchain)` for assembly and `make check` for testing. ## FAQ ### How does Atlas understand x86-64 and ARM64 Assembly calling conventions? Atlas indexes Assembly code by AST declarations, allowing it to recognize and understand specific calling conventions like System V for x86-64 and AAPCS64 for ARM64. This includes awareness of register allocation and the ABI contract for each routine. ### Can Atlas help me find specific Assembly instructions or register usage patterns? Yes, Atlas can. You can use `codebase_search` with a plain-language query to find semantic matches, or delegate to the `explore` subagent with `grep` to search for specific instruction mnemonics or register usage patterns across your `.asm` or `.S` files. ### How does Atlas ensure my Assembly code changes are safe? Atlas drafts plans in a read-only agent and requires your approval before switching to a build agent. Every proposed change to `.asm` or `.S` files generates a unified diff for your review. Atlas also runs `make check` behind a permission prompt to verify changes. ### Does Atlas support both `nasm` and GNU Assembler for Assembly projects? Yes, Atlas is designed to work with your existing Assembly toolchain. It can assemble your code using either `nasm` or the GNU assembler, integrating direct with your `Makefile` and `make (nasm toolchain)` commands. ### How does Atlas maintain Assembly code style with `asmfmt`? Atlas integrates with `asmfmt` to ensure consistency. When Atlas touches `.asm` or `.S` files, it automatically keeps alignment and column style consistent with `asmfmt`, maintaining the project's established formatting standards. ### Can Atlas help me understand the ABI of an unfamiliar Assembly codebase? Absolutely. Atlas's AST indexing and semantic understanding allow it to identify and explain the ABI contracts between routines, including register usage and stack frame conventions, which are critical for understanding Assembly code interactions. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-assembly Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-assembly` (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.