How does Atlas handle OCaml module boundaries during a rename?

Atlas leverages the lsp tool's findReferences operation, which understands OCaml's module system and .mli interface files, to accurately identify all symbol usages across module boundaries.

Can Atlas rename OCaml symbols in dune files or opam package definitions?

Yes, Atlas uses the grep tool to find and the edit tool to replace occurrences of the old symbol name in non-code contexts, including dune build rules and opam package metadata.

What if Atlas finds multiple matches for an OCaml symbol during a rename?

The edit tool in Atlas enforces uniqueness. If it finds multiple matches for a single replacement, it will throw an error unless you explicitly provide more context or opt into replaceAll for that file.

How does Atlas ensure my OCaml code still compiles after a rename?

After applying renames, Atlas uses the bash tool to run dune runtest, compiling your OCaml project and executing tests. It then reads compiler errors back into its plan for further action.

Does Atlas integrate with ocamlformat for style consistency?

Yes, Atlas can finish its workflow by running ocamlformat on modified OCaml files, ensuring that the resulting diff is style-clean and adheres to your project's formatting standards.

Is it safe to let Atlas modify my OCaml codebase?

Atlas operates with multiple safety layers: a read-only plan agent, permission-gated tool calls, unified diffs for every edit, and the ability to snapshot changes as git patches for easy rollback.

Can Atlas rename OCaml type constructors or record fields?

Atlas's lsp tool integration allows it to understand OCaml's Abstract Syntax Tree (AST) declarations, enabling it to accurately identify and rename various symbol types, including type constructors and record fields, where the language server provides references.

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

In 2026, Atlas empowers OCaml developers to rename functions, classes, or constants across an entire repository with precision, leveraging the lsp tool for authoritative references, grep for non-code occurrences, and edit for mechanical changes, all verified by dune runtest and ocamlformat.

How Atlas Pinpoints OCaml Symbol References

Atlas precisely identifies all OCaml symbol references using the lsp tool's findReferences operation, which queries the language server for an authoritative callsite list. This method, superior to simple text search, ensures that in 2026, every relevant usage of a function or constant is captured, even across .mli interface files.

To rename a symbol in OCaml, Atlas first employs the lsp tool's findReferences operation. This tool connects to the language server to obtain a true reference set, understanding OCaml's type system and module structure. Unlike naive text searches, lsp accurately identifies all declarations and usages of a function, class, or constant, including those defined in .mli interface files and implemented in corresponding .ml files. Atlas builds its code index using AST declarations via tree-sitter, which, combined with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, ensures comprehensive and accurate identification of all relevant OCaml code locations.

Locating Non-Code OCaml Occurrences with Grep

Beyond compiler-visible code, Atlas employs the grep tool to find instances of the old symbol name in comments, documentation, and configuration files. This crucial step ensures a complete rename, preventing orphaned references that the OCaml compiler or lsp alone would miss in 2026.

While the lsp tool handles code references, many symbol names appear in contexts outside the OCaml type system. Atlas uses the grep tool to catch these occurrences. This includes instances within code comments, string literals, documentation blocks, and configuration files such as dune build rules or opam package definitions. This comprehensive search ensures that the rename is truly repository-wide, addressing all mentions of the old symbol name that a compiler or language server might overlook, guaranteeing a thorough refactor.

Applying Mechanical Renames in OCaml Files

The edit tool in Atlas performs the mechanical replacement of the old symbol name with the new one across OCaml files. In 2026, edit uses replaceAll for unambiguous matches, but critically, it refuses single replacements if multiple matches are found, preventing silent corruption and ensuring precision.

Once all occurrences of the old symbol name are identified, Atlas uses the edit tool to apply the mechanical replacements. For cases where the match is unambiguous within a file, edit uses replaceAll to update the symbol. A key safety feature of the edit tool is its strictness: it refuses ambiguous single replacements. If edit finds multiple matches for an old string and is not explicitly instructed to replaceAll, it will throw a 'Found multiple matches for oldString' error, preventing unintended changes. This mechanism ensures that every rename is precise and intentional, avoiding silent corruption of OCaml source files. Atlas also snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if needed.

Verifying OCaml Renames with Dune and OCamlformat

After renaming, Atlas uses the bash tool to execute dune runtest and compile the OCaml project, catching any remaining compiler errors or runtime issues. This verification step, followed by ocamlformat to ensure style consistency, guarantees a clean and functional refactor in 2026.

A critical phase of any OCaml refactor is verification. Atlas employs the bash tool to run the project's test suite and compile the code. Specifically, it executes dune runtest, which compiles the OCaml project and runs all defined tests. Atlas reads the compiler errors and test failures back into its plan, allowing for immediate correction. After successful compilation and testing, Atlas runs ocamlformat on all modified files. This ensures that the refactored code adheres to the project's formatting standards, resulting in a style-clean diff. Finally, Atlas performs one more grep for the old name to definitively prove zero remaining hits, confirming the completeness of the rename.

Atlas's Safety and Review Process for OCaml Refactors

Atlas prioritizes safety in OCaml refactoring through a multi-stage review process. A read-only plan agent drafts the entire rename strategy, asking for approval before any changes are made. Every file edit generates a unified diff, presented for user approval before writing, ensuring full transparency in 2026.

Atlas is designed with multiple layers of safety for OCaml developers. The process begins with a read-only plan agent that drafts the entire refactoring strategy, detailing the steps Atlas intends to take. Before any modifications are made, Atlas asks for user approval to switch to a build agent. Every tool call, including lsp, grep, edit, and bash, is permission-gated against allow, ask, and deny rules. For every file edit, Atlas computes a unified diff and surfaces it for approval before writing, providing complete transparency. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, ensuring that OCaml refactors are not only accurate but also fully auditable and reversible.

Step by step

01Initialize Atlas in your OCaml workspace, ensuring a dune-project file is at the root and Atlas can read your dune stanzas and opam switch.
02Ask Atlas to rename your OCaml symbol, for example, 'Rename MyOldFunction to MyNewFunction everywhere in the repo'.
03Approve Atlas's plan, which will use the lsp tool's findReferences operation to get the authoritative callsite list from the OCaml language server, including .mli files.
04Confirm Atlas's use of the grep tool to locate instances of the old symbol name in comments, strings, documentation, and dune configuration files.
05Review and approve the edit tool's proposed changes, ensuring replaceAll is used for mechanical replacements in OCaml source files and that no ambiguous single replacements are made.
06Grant permission for Atlas to execute bash commands, specifically dune runtest, to compile your OCaml project and run tests, reading any compiler errors back into the plan.
07Approve Atlas's final bash command to run ocamlformat on all modified OCaml files, ensuring the diff is style-clean before you approve it.
08Verify with Atlas that a final grep for the old symbol name yields zero results, confirming a complete and successful OCaml symbol rename.

Frequently asked questions

How does Atlas handle OCaml module boundaries during a rename?: Atlas leverages the lsp tool's findReferences operation, which understands OCaml's module system and .mli interface files, to accurately identify all symbol usages across module boundaries.
Can Atlas rename OCaml symbols in dune files or opam package definitions?: Yes, Atlas uses the grep tool to find and the edit tool to replace occurrences of the old symbol name in non-code contexts, including dune build rules and opam package metadata.
What if Atlas finds multiple matches for an OCaml symbol during a rename?: The edit tool in Atlas enforces uniqueness. If it finds multiple matches for a single replacement, it will throw an error unless you explicitly provide more context or opt into replaceAll for that file.
How does Atlas ensure my OCaml code still compiles after a rename?: After applying renames, Atlas uses the bash tool to run dune runtest, compiling your OCaml project and executing tests. It then reads compiler errors back into its plan for further action.
Does Atlas integrate with ocamlformat for style consistency?: Yes, Atlas can finish its workflow by running ocamlformat on modified OCaml files, ensuring that the resulting diff is style-clean and adheres to your project's formatting standards.
Is it safe to let Atlas modify my OCaml codebase?: Atlas operates with multiple safety layers: a read-only plan agent, permission-gated tool calls, unified diffs for every edit, and the ability to snapshot changes as git patches for easy rollback.
Can Atlas rename OCaml type constructors or record fields?: Atlas's lsp tool integration allows it to understand OCaml's Abstract Syntax Tree (AST) declarations, enabling it to accurately identify and rename various symbol types, including type constructors and record fields, where the language server provides references.

Try Atlas in your terminal

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

Install Atlas

Related guides

Rename a Symbol Across the Repo with Atlas in 2026

How to rename a symbol across a repo with Atlas in 2026: findReferences gets the true reference set, grep catches strings and docs, and edit refuses ambiguous matches.

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.

Audit an OCaml Repository with Parallel Subagents in Atlas, 2026

Sweep an OCaml repository for specific problems using Atlas's parallel subagents. Leverage `dune`, `opam`, and `ocamlformat` for efficient, context-window-friendly audits.

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.

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.

Debug a single failing test in OCaml with Atlas in 2026

Pinpoint and fix failing OCaml tests with Atlas, the terminal-native AI coding agent. Leverage dune runtest, opam, and ocamlformat for efficient debugging in 2026.

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.

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.

Browse this resource hub