How does Atlas ensure it finds all Perl callers, even dynamic ones?

Atlas combines `lsp`'s `findReferences` for static calls in `.pm` modules with `grep` for dynamic or string-based usages, ensuring a complete enumeration of all Perl callsites, including those in legacy scripts or `eval` blocks.

Can Atlas handle Perl modules managed by `cpanm` or `Makefile.PL`?

Yes, Atlas is designed to work within Perl distributions that use `cpanfile` or `Makefile.PL`. It reads your packages, `@EXPORT` lists, and modules pulled in by `cpanm` to build its code index and understand your project structure.

What happens if a Perl file changes while Atlas is working on it?

Atlas's `apply_patch` tool is context-anchored. If a Perl file, such as `lib/My/Service.pm`, drifts and the expected `old_lines` or surrounding context are not found, `apply_patch` will throw a `Failed to find expected lines` error, preventing misapplication and data corruption.

How does Atlas integrate with Perl's testing framework?

Atlas integrates directly with `prove (Test2::V0)`. After each file modification, it runs `bash -c 'prove -lr t/'` to execute affected tests. A `todowrite` entry is marked complete only if these `Test2::V0` tests pass, ensuring no regressions are introduced.

Does Atlas enforce Perl coding standards like `perltidy`?

Yes, Atlas runs `perltidy` on all changed Perl files. This ensures that the modifications adhere to your project's `.perltidyrc` configuration, maintaining consistent code style and providing clean, functional-only diffs for review.

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

Atlas computes a unified diff for every file edit and surfaces it for your approval before writing. You can review these changes, such as those to `lib/My/App.pm`, and approve or reject them. Atlas also integrates with `git` to stage and commit changes on your behalf.

Can Atlas help with adding `use strict` and `use warnings` to old Perl scripts?

Yes, Atlas can be asked to add `use strict` and `use warnings` to legacy Perl scripts, or to write new `Test2::V0` cases under `t/`, demonstrating its ability to assist with various Perl code improvements.

Migrate a Deprecated API Across Every Callsite in Perl with Atlas in 2026

Atlas empowers Perl developers in 2026 to systematically migrate deprecated APIs across an entire codebase, ensuring no callsite is missed. It integrates directly with your Perl toolchain, leveraging `lsp` for comprehensive callsite enumeration, `todowrite` for tracking, and `apply_patch` for safe, context-aware modifications, all validated by `prove (Test2::V0)` and formatted by `perltidy`.

How Atlas Finds All Perl Callsites for a Deprecated API

Atlas ensures a complete enumeration of deprecated Perl API calls by combining `lsp` and `grep`, preventing any callsite from being overlooked in 2026. This hybrid approach guarantees that both statically linked module calls and dynamic, string-based usages are identified, providing a 100% accurate starting point for your migration.

To begin a migration in Perl, Atlas first uses its `lsp` tool to perform a `findReferences` operation on the deprecated symbol. This leverages the language server's understanding of your Perl modules, `cpanfile`, and `Makefile.PL` to identify all direct, statically linked calls. For instance, if you're deprecating a function in `My::OldModule`, Atlas will find all `use My::OldModule;` and subsequent calls to its `@EXPORT`ed functions. However, Perl's dynamic nature means some usages might be string-based or constructed at runtime. To catch these, Atlas cross-checks the `lsp` results with a `grep` search for the deprecated symbol's name, ensuring that even `eval` statements or dynamically loaded module names are identified. This two-pronged strategy ensures a comprehensive list of every callsite, whether it's in a `.pm` file or a legacy script.

Tracking Migration Progress Across Perl Files with Atlas

Tracking progress during a large Perl API migration is crucial, and Atlas addresses this by creating one `todowrite` entry per callsite. This ensures that partial progress is always visible, and no single call to a deprecated function or module is silently skipped, providing a clear roadmap for 100s of changes.

Once Atlas has enumerated all callsites for the deprecated Perl API, it converts each identified usage into a distinct `todowrite` entry. This granular tracking mechanism is vital for large-scale refactoring efforts across numerous `.pm` files or scripts. Each `todowrite` entry represents a specific piece of work: migrating a single callsite. As Atlas processes each entry, it marks it as complete only after the migration is successfully applied and the relevant tests pass. This allows you to see exactly which files, like `lib/My/App/Legacy.pm` or `scripts/old_report.pl`, still contain deprecated calls, providing transparent visibility into the migration's status and preventing any callsite from being overlooked.

Applying Patches Safely to Perl Code with Atlas

Atlas applies migration changes to Perl code with high safety and precision using its `apply_patch` tool, which seeks specific hunk context and old lines. This method prevents misapplication to drifted files, ensuring that changes to your `.pm` modules or scripts are only committed when the exact expected code is found, minimizing risks in 2026.

Migrating each Perl callsite is handled by Atlas's `apply_patch` tool. This tool is designed for robust, context-aware modifications. Instead of blindly applying changes by line number, `apply_patch` seeks the specific hunk's context and `old_lines` within the target file. For example, if you're replacing `OldModule::old_function()` with `NewModule::new_function()`, Atlas will generate a patch that includes the surrounding lines of code. If the file, such as `lib/My/Service.pm`, has drifted since the patch was generated - perhaps another developer modified the same lines - `apply_patch` will throw a `Failed to find expected lines` error rather than guessing or corrupting the file. This ensures that every change is applied precisely where intended, maintaining code integrity across your Perl codebase.

Automated Testing and Formatting for Perl Migrations

After each file modification, Atlas automatically runs affected Perl tests using `prove -lr t/` and applies `perltidy` to maintain code style. This immediate feedback loop ensures that every change to a `.pm` module or script passes its `Test2::V0` suite and adheres to your `.perltidyrc` standards, preventing regressions and style drift in 2026.

A critical safety measure in Atlas's Perl migration workflow is the integration of automated testing and formatting. After `apply_patch` modifies a file, Atlas immediately executes the affected tests using the `bash` tool to run `prove -lr t/`. This command targets the relevant `Test2::V0` test files under the `t/` directory, providing instant feedback on whether the migration introduced any regressions. Only if these tests pass is the `todowrite` entry marked as complete. Furthermore, to ensure code consistency and clean diffs, Atlas runs `perltidy` on the changed files. This adheres to your project's `.perltidyrc` configuration, ensuring that the diff presented for approval reflects only the functional change, not formatting adjustments, making review processes smoother and more efficient.

Reviewing and Committing Perl Changes with Atlas

Atlas provides a comprehensive review process for Perl code changes, presenting a unified diff for every file edit before writing. This allows developers to approve or reject changes to `.pm` modules or scripts, ensuring full control over the migration process and preventing unintended modifications in 2026.

Before any changes are written to your Perl codebase, Atlas computes a unified diff for every file edit and surfaces it for your approval. This allows you to meticulously review the proposed changes, such as the replacement of `Old::API` with `New::API` in `lib/My/Module.pm`. Atlas's read-only plan agent drafts the entire migration plan, and only after your explicit approval does it switch to a build agent to execute the changes. Each tool call is permission-gated, giving you fine-grained control. Atlas also reads `git` branches, status, and diffs, and can stage and create commits on your behalf, or even snapshot file changes as `git` patches for easy rollback. This robust review and commit system ensures that every migration step is transparent and fully controlled by the Perl developer.

Step by step

01Run Atlas in your Perl distribution, ensuring it can read your `cpanfile` or `Makefile.PL` to index packages and `@EXPORT` lists.
02Use `atlas lsp findReferences <DeprecatedSymbol>` to enumerate all static callsites of the deprecated Perl API, then cross-check with `atlas grep <DeprecatedSymbol>` for dynamic usages.
03Instruct Atlas to create `todowrite` entries for each identified callsite, ensuring visible and trackable progress for every migration task.
04For each `todowrite` entry, have Atlas use `apply_patch` to migrate the callsite, ensuring the patch's context and `old_lines` are found before modification.
05After each file modification, Atlas will run `bash -c 'prove -lr t/'` to execute affected `Test2::V0` tests, marking the `todowrite` entry complete only upon success.
06Atlas will then run `perltidy` on the changed Perl files to ensure formatting adheres to your `.perltidyrc`, presenting a clean diff for review.
07Review the unified diffs presented by Atlas for each file, approving the changes to `lib/My/Module.pm` or `scripts/legacy.pl` before they are written.
08Finally, confirm zero remaining hits for the deprecated symbol with `atlas grep <DeprecatedSymbol>` and then delete the old Perl implementation.

Frequently asked questions

How does Atlas ensure it finds all Perl callers, even dynamic ones?: Atlas combines `lsp`'s `findReferences` for static calls in `.pm` modules with `grep` for dynamic or string-based usages, ensuring a complete enumeration of all Perl callsites, including those in legacy scripts or `eval` blocks.
Can Atlas handle Perl modules managed by `cpanm` or `Makefile.PL`?: Yes, Atlas is designed to work within Perl distributions that use `cpanfile` or `Makefile.PL`. It reads your packages, `@EXPORT` lists, and modules pulled in by `cpanm` to build its code index and understand your project structure.
What happens if a Perl file changes while Atlas is working on it?: Atlas's `apply_patch` tool is context-anchored. If a Perl file, such as `lib/My/Service.pm`, drifts and the expected `old_lines` or surrounding context are not found, `apply_patch` will throw a `Failed to find expected lines` error, preventing misapplication and data corruption.
How does Atlas integrate with Perl's testing framework?: Atlas integrates directly with `prove (Test2::V0)`. After each file modification, it runs `bash -c 'prove -lr t/'` to execute affected tests. A `todowrite` entry is marked complete only if these `Test2::V0` tests pass, ensuring no regressions are introduced.
Does Atlas enforce Perl coding standards like `perltidy`?: Yes, Atlas runs `perltidy` on all changed Perl files. This ensures that the modifications adhere to your project's `.perltidyrc` configuration, maintaining consistent code style and providing clean, functional-only diffs for review.
How do I review and approve changes made by Atlas to my Perl code?: Atlas computes a unified diff for every file edit and surfaces it for your approval before writing. You can review these changes, such as those to `lib/My/App.pm`, and approve or reject them. Atlas also integrates with `git` to stage and commit changes on your behalf.
Can Atlas help with adding `use strict` and `use warnings` to old Perl scripts?: Yes, Atlas can be asked to add `use strict` and `use warnings` to legacy Perl scripts, or to write new `Test2::V0` cases under `t/`, demonstrating its ability to assist with various Perl code improvements.

Try Atlas in your terminal

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

Install Atlas

Related guides

Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)

How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.

Atlas for Perl: A Terminal-Native AI Coding Agent for CPAN Distributions in 2026

Atlas is a terminal-native AI coding agent for Perl in 2026. It reads cpanfile deps and @EXPORT lists, writes Test2::V0 cases, runs prove -lr t/, and runs perltidy on the diff.

Plan a Multi-File Change in Perl with Atlas in 2026

Design and review complex, multi-file Perl changes with Atlas's plan agent before modifying a single line of code. Leverage prove, cpanm, and perltidy for safe development.

Research a third-party API before integrating it in Perl with Atlas in 2026

Perl developers in 2026 can research third-party APIs with Atlas, leveraging websearch and webfetch to get current documentation. Integrate with confidence, verifying code against prove (Test2::V0) and perltidy.

Trace a runtime bug from a stack trace in Perl with Atlas in 2026

Pinpoint Perl runtime bugs from production stack traces using Atlas in 2026. Leverage Atlas's code indexing, grep, and lsp tools to quickly identify the root cause and apply fixes, all without a debugger.

Upgrade a dependency and fix the breakage in Perl with Atlas in 2026

Effortlessly upgrade Perl dependencies and resolve breaking changes with Atlas in 2026. Leverage Atlas to manage `cpanm` upgrades, fix `Test2::V0` failures, and apply `perltidy` formatting.

Self-review your working diff before committing in Perl with Atlas in 2026

Catch your own mistakes in uncommitted Perl diffs before they reach review or CI. Learn how Atlas helps Perl developers in 2026 self-review code, run `prove`, and `perltidy`.

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

Rename Perl functions, classes, or constants across your entire codebase with Atlas in 2026. Leverage lsp, grep, and edit for precise, safe refactoring, ensuring your prove (Test2::V0) tests pass and perltidy formatting

Browse this resource hub