How does Atlas understand my OCaml project's structure?

Atlas understands your OCaml project by reading the `dune-project` at the root, parsing each `dune` stanza, and analyzing `.mli` interface files and `opam` switches to build a semantic index based on AST declarations.

Can Atlas run OCaml tests like `dune runtest`?

Yes, Atlas can run `dune runtest` behind a permission prompt. It then reads the compiler errors and test results back into its plan, allowing for iterative debugging and refinement of your OCaml code.

How does Atlas ensure OCaml code style and formatting?

Atlas integrates with `ocamlformat`. After making any code changes, Atlas can run `ocamlformat` to ensure the diff is style-clean and adheres to your project's OCaml formatting standards before you approve the write operation.

Is my OCaml code sent to third-party servers when using Atlas?

No, Atlas can build its code index with local Ollama embeddings, keeping your OCaml code entirely off third-party servers. This ensures your proprietary OCaml codebase remains secure and private.

How does Atlas help me explore OCaml module dependencies?

Atlas uses the `lsp` tool's `goToDefinition` operation to follow OCaml imports and module boundaries. This allows you to trace dependencies and understand the flow of logic across your `.ml` and `.mli` files efficiently.

What safety measures does Atlas have for modifying OCaml code?

Atlas employs several safety measures: every tool call is permission-gated, plans are drafted in a read-only agent, unified diffs are computed for every file edit for approval, and file changes are snapshotted as git patches for rollback.

Can Atlas help me understand `opam` package configurations?

Yes, Atlas reads the packages pinned in your `opam` switch. This allows it to understand your project's dependencies and environment, providing context when analyzing or modifying your OCaml codebase.

Onboard to an Unfamiliar OCaml Codebase with Atlas in 2026

In 2026, Atlas helps OCaml developers build a working mental model of unfamiliar repositories without reading every file, by leveraging its semantic index, `dune` build rules, `opam` switches, and `.mli` interface files to provide concrete insights into the codebase's structure and behavior.

How Atlas builds a mental model of OCaml codebases

Atlas begins building a mental model of an OCaml codebase by indexing its Abstract Syntax Tree (AST) declarations, a method superior to blind line windows. This approach, available in 2026, allows Atlas to understand the semantic relationships within your OCaml project, including `dune` stanzas and `.mli` signatures.

Atlas's core capability for onboarding to an unfamiliar OCaml codebase lies in its ability to index code by AST declarations using tree-sitter. This means Atlas understands the structure and meaning of your OCaml code, rather than just treating it as plain text. When you run Atlas in a workspace with a `dune-project` at the root, it reads each `dune` stanza, your `.mli` signatures, and the packages pinned in your `opam` switch. This deep understanding allows Atlas's `codebase_search` tool to query the semantic index for concepts like 'how requests are authenticated' and return ranked snippets with file paths, providing a meaningful starting point without requiring you to manually sift through every `.ml` file.

Exploring OCaml project structure with Atlas

In 2026, Atlas provides specific tools to explore the layout of an OCaml project, moving beyond generic file browsing. The `glob` tool quickly maps top-level directories, revealing `dune` build rules and package naming conventions before you open any `.ml` or `.mli` files.

Once Atlas has indexed your OCaml codebase, you can use its specialized tools to navigate and understand the project structure. The `glob` tool allows you to quickly see the package layout and naming conventions by mapping top-level directories, giving you an immediate overview of the `dune` build rules and module organization. After identifying key areas with `codebase_search`, you can use the `read` tool to pull the two or three highest-ranked `.ml` or `.mli` files. For deeper exploration, the `lsp` tool's `goToDefinition` operation lets you follow OCaml imports and module boundaries, tracing the flow of logic across your codebase. For wide sweeps or investigations that might involve many files, you can delegate tasks to the `explore` subagent through the `task` tool. This subagent is permissioned read-only, allowing it to safely use `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch` without making any changes to your OCaml project.

Safe OCaml code exploration and modification with Atlas

Atlas prioritizes safety when exploring and modifying OCaml code, ensuring every action is permission-gated. In 2026, Atlas drafts a plan in a read-only agent and computes a unified diff for every file edit, providing explicit approval steps before any changes are written to your OCaml project.

Atlas is designed with multiple layers of safety for OCaml developers. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, giving you granular control over its actions. When Atlas needs to make changes, it first drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent. This ensures you understand the proposed steps before execution. For any file edits, Atlas computes a unified diff and surfaces it for your approval before writing, allowing you to review the exact changes to your `.ml` or `.mli` files. For example, if Atlas is asked to add an `Alcotest` case to a `test/dune` stanza, it will present the diff for your review. Furthermore, Atlas snapshots file changes as git patches, so edits can be diffed and rolled back, providing a robust safety net for your OCaml development workflow. You can also record what you learned as a `todowrite` list, ensuring open questions survive into the next turn without modifying the codebase.

Integrating Atlas with the OCaml toolchain

Atlas integrates directly with the OCaml toolchain, recognizing `dune` build rules, `opam` switches, and `ocamlformat` in 2026. This allows Atlas to not only understand your OCaml project but also to interact with it using the actual commands OCaml developers use daily.

Atlas is built to be a native extension of the OCaml development environment. It understands and interacts with the core OCaml toolchain by name. For instance, Atlas can be asked to make a variant exhaustive or add an `Alcotest` case to a `test/dune` stanza. for testing, Atlas can run `dune runtest` behind a permission prompt, reading the compiler errors back into its plan for iterative refinement. This means you can trust Atlas to execute your OCaml tests and help debug issues. After making any modifications, Atlas can finish with `ocamlformat` so the diff is style-clean before you approve it, ensuring your OCaml code adheres to established formatting standards. Atlas also reads the packages pinned in your `opam` switch, providing a complete picture of your project's dependencies and environment, making it a powerful assistant for any OCaml developer.

Step by step

01Run Atlas in your OCaml workspace, ensuring a `dune-project` is at the root for Atlas to index `dune` stanzas and `opam` switches.
02Ask `codebase_search` a plain-language question about your OCaml project, such as 'how requests are authenticated', to get ranked `.ml` and `.mli` snippets.
03Run `glob` on the top-level directories to visualize the OCaml package layout and `dune` naming conventions before opening any files.
04Use `read` to examine the two or three OCaml files `codebase_search` ranked highest, then follow OCaml imports with the `lsp` tool's `goToDefinition` operation.
05Delegate wide sweeps of the OCaml codebase to the `explore` subagent through the `task` tool, which is permissioned read-only to prevent accidental changes.
06Record what you learned about the OCaml codebase as a `todowrite` list, ensuring open questions persist into your next Atlas session.
07Ask Atlas to make a variant exhaustive or add an `Alcotest` case to a `test/dune` stanza, then review the proposed OCaml code changes.
08Approve Atlas to run `dune runtest` to verify OCaml changes, and let Atlas read compiler errors back into its plan.
09Have Atlas finish with `ocamlformat` to ensure the OCaml code diff is style-clean before you approve the final write operation.

Frequently asked questions

How does Atlas understand my OCaml project's structure?: Atlas understands your OCaml project by reading the `dune-project` at the root, parsing each `dune` stanza, and analyzing `.mli` interface files and `opam` switches to build a semantic index based on AST declarations.
Can Atlas run OCaml tests like `dune runtest`?: Yes, Atlas can run `dune runtest` behind a permission prompt. It then reads the compiler errors and test results back into its plan, allowing for iterative debugging and refinement of your OCaml code.
How does Atlas ensure OCaml code style and formatting?: Atlas integrates with `ocamlformat`. After making any code changes, Atlas can run `ocamlformat` to ensure the diff is style-clean and adheres to your project's OCaml formatting standards before you approve the write operation.
Is my OCaml code sent to third-party servers when using Atlas?: No, Atlas can build its code index with local Ollama embeddings, keeping your OCaml code entirely off third-party servers. This ensures your proprietary OCaml codebase remains secure and private.
How does Atlas help me explore OCaml module dependencies?: Atlas uses the `lsp` tool's `goToDefinition` operation to follow OCaml imports and module boundaries. This allows you to trace dependencies and understand the flow of logic across your `.ml` and `.mli` files efficiently.
What safety measures does Atlas have for modifying OCaml code?: Atlas employs several safety measures: every tool call is permission-gated, plans are drafted in a read-only agent, unified diffs are computed for every file edit for approval, and file changes are snapshotted as git patches for rollback.
Can Atlas help me understand `opam` package configurations?: Yes, Atlas reads the packages pinned in your `opam` switch. This allows it to understand your project's dependencies and environment, providing context when analyzing or modifying your OCaml codebase.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related 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 OCaml: A Terminal-Native AI Coding Agent for dune and opam Projects in 2026

Atlas is a terminal-native AI coding agent for OCaml in 2026. It reads dune stanzas and .mli signatures, runs dune runtest behind a prompt, and finishes with ocamlformat.

Diagnose a hanging or long-running command in OCaml with Atlas in 2026

Diagnose hanging OCaml `dune` builds or `opam` scripts with Atlas in 2026. Atlas identifies blocked input, suggests non-interactive flags, or recommends timeout adjustments.

Rename a symbol across the repo in OCaml with Atlas in 2026

Learn how Atlas renames OCaml functions, classes, and constants across your repository in 2026. Leverage lsp, grep, edit, and dune for precise, verified refactoring.

Review a pull request in OCaml with Atlas in 2026

In 2026, Atlas helps OCaml developers review pull requests by fetching diffs, reading full files, checking .mli signatures, running dune runtest, and applying ocamlformat.

Document an OCaml Module with a README using Atlas in 2026

Generate accurate, up-to-date README documentation for your OCaml modules in 2026 using Atlas. Leverage dune, opam, and ocamlformat for precise, traceable docs.

Refactor a legacy module in OCaml with Atlas in 2026

Restructure an old OCaml module without breaking callers using Atlas. Map public surfaces, pin behavior with dune runtest, apply changes with apply_patch, and ensure style with ocamlformat.

Write Unit Tests for Untested Code in OCaml with Atlas in 2026

Learn how Atlas helps OCaml developers in 2026 write unit tests for untested modules. Atlas uses dune runtest, opam, and ocamlformat to integrate with your existing OCaml workflow.

Browse this resource hub