How does Atlas handle Perl's dynamic nature or `AUTOLOAD` for code location?

Atlas indexes Perl code using AST declarations via `tree-sitter`, providing a robust understanding of symbols and their relationships, even in complex `.pm` modules. Its semantic search complements this by understanding behavior descriptions, helping to navigate dynamic aspects.

Can Atlas find code in older Perl 5 projects without a modern `cpanfile`?

Yes, Atlas can operate in any Perl distribution containing a `Makefile.PL` or even just `.pm` files, reading packages and `@EXPORT` lists to build its code index, making it suitable for diverse Perl 5 projects.

What if my Perl project uses a custom test runner instead of `prove (Test2::V0)`?

While Atlas explicitly supports `prove (Test2::V0)` for test execution and output, its core search and `lsp` capabilities are fundamentally language-agnostic, allowing you to locate code regardless of your specific Perl test runner.

Does Atlas send my Perl source code to external servers for indexing?

No, Atlas can build its code index using local Ollama embeddings, ensuring your Perl source code remains entirely on your machine, off third-party servers, maintaining your project's privacy.

How does Atlas help me understand a Perl module's dependencies when locating behavior?

Atlas reads your `cpanfile` or `Makefile.PL` and the modules pulled in by `cpanm`, providing crucial context for your Perl project's dependency graph during code exploration and behavior location.

Can Atlas help me refactor a Perl subroutine once I find its implementation?

While this page focuses on *locating* behavior, Atlas's capabilities, including `lsp` for references, its read-only plan agent, and its ability to apply unified diffs, lay the groundwork for future refactoring tasks within your Perl codebase.

How does Atlas ensure I don't accidentally change production Perl code during exploration?

Atlas employs a read-only plan agent, permission-gated tool calls, and unified diffs for every proposed edit, requiring your explicit approval before any changes are written to your Perl files, ensuring safety.

Locate Perl Behavior Implementations with Atlas in 2026

Atlas empowers Perl developers in 2026 to precisely locate where a behavior is implemented by combining semantic codebase search, exact text matching with `grep`, and symbol graph navigation via the `lsp` tool. This integrated approach works direct across your CPAN distributions, `.pm` modules, and TAP-based test suites, understanding your `cpanfile` or `Makefile.PL` and interacting with tools like `prove (Test2::V0)` and `perltidy`.

How does Atlas find Perl code implementations when I only know the behavior?

In 2026, Atlas employs a powerful three-pronged strategy to pinpoint Perl code implementations, even when you only know what the software does. It combines semantic search, exact text matching, and symbol graph analysis, ensuring comprehensive retrieval across your CPAN distributions and `.pm` modules. This hybrid approach leverages Atlas's AST indexing for precise results.

Atlas addresses the challenge of locating behavior in Perl code by attacking it from three complementary angles. First, the `codebase_search` tool uses hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, to understand your description of a behavior. This means it can return candidate declarations from your Perl codebase even if your exact words do not appear in the source. Atlas builds its code index by AST declarations using `tree-sitter`, providing a deeper understanding of Perl's structure than blind line windows. You can even build this index with local Ollama embeddings, keeping your Perl code off third-party servers. Second, `grep` confirms these semantic findings by running `ripgrep` with real regex, plus include and path filters, allowing you to narrow down searches to specific Perl files like `lib/MyProject/*.pm`. Finally, the `lsp` tool provides symbol graph capabilities, letting you use `findReferences` to see every callsite of a Perl subroutine or `workspaceSymbol` to jump directly to a declaration by name, offering a complete picture of the behavior's implementation.

What Perl commands and files does Atlas use to locate behavior?

Atlas integrates directly with the familiar Perl toolchain, allowing it to understand and interact with your project's structure in 2026. When locating behavior, Atlas recognizes `cpanfile` or `Makefile.PL` for dependency management and understands `@EXPORT` lists within `.pm` modules. It also works direct with `prove (Test2::V0)` for test execution.

Atlas is designed to be a native companion for Perl developers. When you run Atlas in a distribution with a `cpanfile` or `Makefile.PL`, it automatically reads your packages, `@EXPORT` lists, and the modules pulled in by `cpanm`, building a comprehensive understanding of your Perl project's context. This deep integration means that when you're searching for a behavior, Atlas understands the significance of a `.pm` file in `lib/` or a test case in `t/`. While primarily focused on locating, Atlas's setup also includes capabilities like asking it to add `use strict` and `use warnings` to a legacy script or writing `Test2::V0` cases. It can even run `prove -lr t/` behind a permission prompt, showing you the TAP output, which can be invaluable for confirming observed behaviors. Furthermore, if any edits are made during the process of understanding or confirming behavior, Atlas can run `perltidy` on the changed files, ensuring the diff matches your `.perltidyrc` and maintaining code style consistency.

How does Atlas ensure safe code changes and review in Perl projects?

Atlas prioritizes safety and transparency in 2026, implementing several robust mechanisms to ensure every change in your Perl codebase is reviewed and approved. Every Atlas tool call, including those for `grep` or `lsp`, is permission-gated, requiring explicit allow, ask, or deny rules. This prevents unintended modifications and provides developers with full control.

When you're exploring a Perl codebase to locate a behavior, Atlas provides multiple layers of safety and review. Before any tool call, such as `grep` or `lsp`, is executed, it is permission-gated against allow, ask, and deny rules, giving you granular control over Atlas's actions. Atlas drafts its plan in a read-only plan agent, allowing you to review the proposed steps before it switches to a build agent that could potentially make changes. For every file edit Atlas proposes, it computes a unified diff and surfaces it for your approval before writing, ensuring you see exactly what changes will be applied to your `.pm` modules or other Perl files. Atlas also connects to Model Context Protocol servers and exposes their tools to the agent, further enhancing its capabilities while maintaining oversight. It reads `git` branches, status, and diffs, and can stage and create commits on your behalf, integrating direct into your existing Perl development workflow. Crucially, Atlas snapshots file changes as `git` patches, so any edits can be easily diffed and rolled back if needed, providing a robust safety net for your Perl projects.

Step by step

01Run Atlas in your Perl distribution, ensuring it can read your `cpanfile` or `Makefile.PL` and index your `.pm` modules and `@EXPORT` lists.
02Describe the observed behavior to Atlas using `codebase_search`, for example: "Find where the `Customer` object's `calculate_discount` method is implemented in Perl."
03Review the candidate declarations returned by `codebase_search`, which leverage Atlas's AST indexing of your Perl code via `tree-sitter`.
04Confirm the semantic results by using Atlas's `grep` tool with a specific Perl regex, such as `grep -e 'sub calculate_discount'` within your project's `lib/` directory.
05Open the most promising Perl module, for instance `lib/MyProject/Customer.pm`, using Atlas's `read` tool to inspect the code directly.
06Utilize Atlas's `lsp` tool to `findReferences` for the `calculate_discount` symbol or `workspaceSymbol` to jump directly to its declaration within your Perl codebase.
07Summarize the exact file and line references for the behavior's implementation, providing a clear call path back to the user with concrete Perl file and line details.

Frequently asked questions

How does Atlas handle Perl's dynamic nature or `AUTOLOAD` for code location?: Atlas indexes Perl code using AST declarations via `tree-sitter`, providing a robust understanding of symbols and their relationships, even in complex `.pm` modules. Its semantic search complements this by understanding behavior descriptions, helping to navigate dynamic aspects.
Can Atlas find code in older Perl 5 projects without a modern `cpanfile`?: Yes, Atlas can operate in any Perl distribution containing a `Makefile.PL` or even just `.pm` files, reading packages and `@EXPORT` lists to build its code index, making it suitable for diverse Perl 5 projects.
What if my Perl project uses a custom test runner instead of `prove (Test2::V0)`?: While Atlas explicitly supports `prove (Test2::V0)` for test execution and output, its core search and `lsp` capabilities are fundamentally language-agnostic, allowing you to locate code regardless of your specific Perl test runner.
Does Atlas send my Perl source code to external servers for indexing?: No, Atlas can build its code index using local Ollama embeddings, ensuring your Perl source code remains entirely on your machine, off third-party servers, maintaining your project's privacy.
How does Atlas help me understand a Perl module's dependencies when locating behavior?: Atlas reads your `cpanfile` or `Makefile.PL` and the modules pulled in by `cpanm`, providing crucial context for your Perl project's dependency graph during code exploration and behavior location.
Can Atlas help me refactor a Perl subroutine once I find its implementation?: While this page focuses on *locating* behavior, Atlas's capabilities, including `lsp` for references, its read-only plan agent, and its ability to apply unified diffs, lay the groundwork for future refactoring tasks within your Perl codebase.
How does Atlas ensure I don't accidentally change production Perl code during exploration?: Atlas employs a read-only plan agent, permission-gated tool calls, and unified diffs for every proposed edit, requiring your explicit approval before any changes are written to your Perl files, ensuring safety.

Try Atlas in your terminal

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

Install Atlas

Related guides

Locate Where a Behavior Is Implemented with Atlas in 2026

How to locate where a behavior is implemented with Atlas in 2026: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph.

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.

Refactor a Legacy Perl Module with Atlas in 2026

Refactor old Perl modules without breaking callers using Atlas. Map public APIs, pin behavior with prove (Test2::V0), and apply changes safely with Atlas's patch system.

Onboard to an unfamiliar codebase in Perl with Atlas in 2026

Quickly build a working mental model of any Perl codebase in 2026 using Atlas. Leverage semantic search, AST indexing, and read-only exploration of `cpanm` distributions and `Test2::V0` test suites, without reading

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`.

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.

Automate GitHub Issue and Pull Request Triage in Perl with Atlas in 2026

Streamline GitHub issue and pull request triage for your Perl projects in 2026 using Atlas. Automate responses safely with `cpanm`, `prove (Test2::V0)`, and `perltidy` integration, ensuring trusted user control.

Run the test suite and triage the failures in Perl with Atlas in 2026

Efficiently triage Perl test failures in 2026 with Atlas. Turn a wall of red `prove (Test2::V0)` output into a prioritized list of distinct root causes, using `grep` and `todowrite`.

Browse this resource hub