How does Atlas ensure I don't break existing OCaml callers during a refactor?

Atlas uses the `lsp` tool to perform `findReferences` on every exported symbol in your OCaml module's `.mli` file, enumerating all existing callsites before any changes. This comprehensive mapping ensures no caller is overlooked, and Atlas can track their migration.

Can Atlas work with my existing OCaml `dune` project setup?

Yes, Atlas is designed to work direct within your OCaml workspace. It reads your `dune-project` file, `dune` stanzas, `.mli` signatures, and packages pinned in your `opam` switch, integrating directly with your established OCaml development environment.

How does Atlas verify that my OCaml module's behavior hasn't changed?

Atlas pins the module's behavior by running your existing tests with the `bash` tool and the `dune runtest` command to establish a green baseline. After each structural change, it re-runs `dune runtest` to immediately detect any behavioral regressions in your OCaml code.

What if my OCaml file changes while Atlas is working on it?

Atlas's `apply_patch` tool is robust. It anchors on context lines and `old_lines` for each hunk. If the OCaml file has drifted or been modified externally, `apply_patch` will fail with `Failed to find context`, preventing unintended or incorrect modifications to your code.

Does Atlas handle OCaml code formatting?

Yes, Atlas integrates with `ocamlformat`, the standard OCaml code formatter. After applying structural changes, Atlas will run `ocamlformat` to ensure the refactored OCaml code adheres to your project's style guidelines, making the final diff clean and focused on logic.

How do I review and approve changes made by Atlas to my OCaml code?

Atlas provides a unified diff for every file edit it proposes. You review these diffs line by line within the terminal-native TUI and explicitly approve them before Atlas writes any changes to your OCaml files. All tool calls are also permission-gated.

Can Atlas help me track remaining work for a large OCaml refactor?

Absolutely. Atlas includes a `todowrite` tool specifically for this purpose. It allows you to track remaining callsites or tasks, ensuring that a partially migrated OCaml module is never mistaken for a finished one, providing clear visibility into ongoing work.

Refactor a legacy module in OCaml with Atlas in 2026

To restructure an old OCaml module without changing its behavior or breaking its callers, Atlas in 2026 leverages the `lsp` tool to map public surfaces, pins behavior with `dune runtest`, applies structural changes using `apply_patch`, and ensures code style with `ocamlformat` before committing. This workflow ensures a safe and verifiable refactoring process for OCaml developers.

How Atlas Maps OCaml Module Public Surfaces and Callers

In 2026, Atlas maps an OCaml module's public surface and enumerates all its callers by first using the `lsp` tool's `documentSymbol` operation on `.mli` interface files. This initial step identifies every exported symbol, providing a clear understanding of the module's external API.

Refactoring an OCaml module carries the inherent risk of silently breaking external callers. Atlas mitigates this by performing a comprehensive analysis of the module's public interface before any changes are made. It begins by invoking the `lsp` tool's `documentSymbol` operation on the module's `.mli` signature file, which precisely outlines all publicly exposed functions, types, and values. Once these symbols are identified, Atlas then uses `lsp`'s `findReferences` operation on each individual exported symbol. This process systematically enumerates every single callsite across the entire OCaml codebase, providing a complete inventory of dependencies. This detailed mapping ensures that no callsite is overlooked during the refactoring, allowing Atlas to track and migrate them effectively, preventing unexpected breakage.

Pinning OCaml Module Behavior with `dune runtest`

Before any structural changes are applied to an OCaml module, Atlas establishes a green baseline by running the existing tests with the `bash` tool and the `dune runtest` command. This critical step, performed in 2026, ensures that the module's current behavior is fully understood and captured, providing a reliable benchmark for subsequent modifications.

A core principle of safe refactoring in OCaml is to 'pin behavior first.' Atlas adheres to this by executing the module's existing test suite using the `bash` tool and the standard OCaml test runner, `dune runtest`. This initial run serves to record a 'green baseline,' confirming that all current tests pass and the module behaves as expected. This baseline is crucial because it provides an immediate, objective measure against which all subsequent changes can be validated. If, after a refactoring step, `dune runtest` reports failures, Atlas can instantly identify that the module's behavior has been altered, allowing for immediate correction. Atlas can read the compiler errors and test failures back into its plan, guiding the developer to resolve issues efficiently within the terminal-native TUI.

Applying Structural Changes to OCaml Code with `apply_patch`

Atlas applies structural changes to OCaml source files using the `apply_patch` tool, which anchors on context lines and refuses to apply against a drifted file. This method ensures that modifications are precise and safe, preventing unintended alterations to the codebase, a key feature for OCaml refactoring in 2026.

The actual restructuring of an OCaml module is performed by Atlas using its `apply_patch` tool. This tool is designed for robust and context-aware code modification. Instead of blindly applying changes, `apply_patch` seeks each hunk's context and `old_lines` within the target OCaml file. If the file has drifted or been modified by another process since Atlas last read it, `apply_patch` will fail with a `Failed to find context` error. This safeguard prevents applying patches to an outdated or incorrect version of the code, ensuring the integrity of the OCaml codebase. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, giving the OCaml developer full control over every change. After each hunk successfully lands, Atlas immediately re-runs the tests with `bash` and `dune runtest`, verifying that the module's behavior remains unchanged after that specific modification, rather than waiting until the very end of the refactor.

Ensuring OCaml Code Style with `ocamlformat`

After applying structural changes to an OCaml module, Atlas ensures the code adheres to established style guidelines by automatically running `ocamlformat`. This step, a standard practice in 2026, guarantees that the resulting diff is style-clean, making code reviews more focused on logic and less on formatting discrepancies.

Maintaining consistent code style is vital in any OCaml project. Atlas integrates direct with `ocamlformat`, the standard OCaml code formatter. Once all structural changes have been applied and verified by `dune runtest`, Atlas will invoke `ocamlformat` on the modified OCaml files. This ensures that the refactored code conforms to the project's predefined formatting rules, which are often configured in a `.ocamlformat` file. By automatically formatting the code, Atlas ensures that the final diff presented for developer approval is purely focused on the logical and structural changes, free from stylistic noise. This significantly streamlines the review process, allowing OCaml developers to concentrate on the correctness and intent of the refactoring rather than minor formatting adjustments.

Safety and Review for OCaml Refactors with Atlas

Atlas provides multiple layers of safety and review for OCaml refactoring tasks in 2026, including permission-gated tool calls, a read-only plan agent, and unified diffs for every file edit. This robust framework ensures that OCaml developers maintain full control and visibility throughout the entire refactoring process.

Atlas is built with developer control and safety at its core, especially crucial for complex OCaml refactors. Every Atlas tool call, whether it's `lsp`, `bash`, or `apply_patch`, is permission-gated against `allow`, `ask`, and `deny` rules configured by the user. Before executing any changes, Atlas drafts a plan in a read-only plan agent and explicitly asks for approval before switching to a build agent that can modify files. For every proposed file edit, Atlas computes a unified diff and surfaces it for approval, allowing OCaml developers to review changes line by line before they are written to disk. Atlas also reads `git` branches, status, and diffs, and can stage and create commits on your behalf, ensuring that the refactoring work is properly version-controlled. Furthermore, Atlas snapshots file changes as `git` patches, providing a robust mechanism for diffing edits and rolling back if necessary, offering unparalleled safety for OCaml code modifications.

Step by step

01Run Atlas in your OCaml workspace, ensuring a `dune-project` file is at the root and Atlas can read your `dune` stanzas, `.mli` signatures, and `opam` switch packages.
02Ask Atlas to map the public surface of the OCaml module using the `lsp` tool's `documentSymbol` operation on its `.mli` file, then `findReferences` on each exported symbol to enumerate all callers.
03Instruct Atlas to pin the module's current behavior by running existing tests with the `bash` tool and the `dune runtest` command, recording a green baseline.
04Guide Atlas to restructure the OCaml module using the `apply_patch` tool, which anchors on context lines and will fail if the file has drifted, ensuring precise modifications.
05After each `apply_patch` hunk lands, have Atlas re-run the tests with `bash` and `dune runtest` to immediately verify that the module's behavior remains unchanged.
06Use the `todowrite` tool to track remaining callsites that need migration, ensuring a partially migrated OCaml module is not mistaken for a finished one.
07Once refactoring is complete, ask Atlas to finish by running `ocamlformat` on the modified OCaml files to ensure the diff is style-clean before you approve it.
08Review the unified diffs presented by Atlas for all file edits and approve them, then allow Atlas to stage and create a `git` commit on your behalf.

Frequently asked questions

How does Atlas ensure I don't break existing OCaml callers during a refactor?: Atlas uses the `lsp` tool to perform `findReferences` on every exported symbol in your OCaml module's `.mli` file, enumerating all existing callsites before any changes. This comprehensive mapping ensures no caller is overlooked, and Atlas can track their migration.
Can Atlas work with my existing OCaml `dune` project setup?: Yes, Atlas is designed to work direct within your OCaml workspace. It reads your `dune-project` file, `dune` stanzas, `.mli` signatures, and packages pinned in your `opam` switch, integrating directly with your established OCaml development environment.
How does Atlas verify that my OCaml module's behavior hasn't changed?: Atlas pins the module's behavior by running your existing tests with the `bash` tool and the `dune runtest` command to establish a green baseline. After each structural change, it re-runs `dune runtest` to immediately detect any behavioral regressions in your OCaml code.
What if my OCaml file changes while Atlas is working on it?: Atlas's `apply_patch` tool is robust. It anchors on context lines and `old_lines` for each hunk. If the OCaml file has drifted or been modified externally, `apply_patch` will fail with `Failed to find context`, preventing unintended or incorrect modifications to your code.
Does Atlas handle OCaml code formatting?: Yes, Atlas integrates with `ocamlformat`, the standard OCaml code formatter. After applying structural changes, Atlas will run `ocamlformat` to ensure the refactored OCaml code adheres to your project's style guidelines, making the final diff clean and focused on logic.
How do I review and approve changes made by Atlas to my OCaml code?: Atlas provides a unified diff for every file edit it proposes. You review these diffs line by line within the terminal-native TUI and explicitly approve them before Atlas writes any changes to your OCaml files. All tool calls are also permission-gated.
Can Atlas help me track remaining work for a large OCaml refactor?: Absolutely. Atlas includes a `todowrite` tool specifically for this purpose. It allows you to track remaining callsites or tasks, ensuring that a partially migrated OCaml module is never mistaken for a finished one, providing clear visibility into ongoing work.

Try Atlas in your terminal

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

Install Atlas

Related guides

Refactor a Legacy Module with Atlas in 2026

How to refactor a legacy module with Atlas in 2026: findReferences maps every callsite, apply_patch refuses to apply against a drifted file, and bash proves behavior.

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.

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.

Self-review Your OCaml Working Diff Before Committing with Atlas in 2026

OCaml developers in 2026 can self-review uncommitted diffs with Atlas, catching mistakes before CI. Leverage dune runtest, ocamlformat, and opam for a clean codebase.

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.

Onboard to an Unfamiliar OCaml Codebase with Atlas in 2026

Quickly build a working mental model of any OCaml repository in 2026 using Atlas. Leverage `dune` build rules, `opam` switches, and `.mli` interface files for rapid understanding and safe code exploration.

Upgrade an OCaml Dependency and Fix Breakage with Atlas in 2026

In 2026, OCaml developers use Atlas to upgrade dependencies like opam packages to new major versions. Atlas automates fixing compile and test failures, integrating with dune, ocamlformat, and .mli files for a

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.

Browse this resource hub