How does Atlas understand my Perl modules and packages?

Atlas uses tree-sitter to index your Perl code by AST declarations, recognizing `package` statements, `use` directives, and `@EXPORT` lists. This allows it to understand the semantic structure of your `.pm` files, not just keywords, providing more accurate search results and context.

Can Atlas help me find where a specific Perl subroutine is called?

Yes, after an initial `codebase_search` to locate relevant files, you can use the `lsp` tool's `goToDefinition` operation on a subroutine call within a Perl module. This will navigate you directly to its definition, helping you trace execution flow.

Is it safe to let Atlas explore my Perl codebase?

Absolutely. The `explore` subagent, designed for wide sweeps, operates with a deny-by-default permission set. It is restricted to read-only tools like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`, ensuring it cannot modify any of your Perl files or configuration like `cpanfile` or `Makefile.PL`.

How does Atlas handle Perl testing with `Test2::V0`?

Atlas understands `Test2::V0` test suites. When tasked with running tests, it will execute the `prove -lr t/` command behind a permission prompt. You will see the raw TAP output directly in your terminal, allowing you to verify test results before any changes are committed.

Will Atlas mess up my Perl code formatting?

No, Atlas respects your Perl coding style. If it makes any changes, it will run `perltidy` on the modified files, ensuring the resulting diff adheres to your project's `.perltidyrc` configuration. All proposed changes are presented as a unified diff for your approval.

Can Atlas help me add `use strict` and `use warnings` to old Perl scripts?

Yes, Atlas can draft a plan to add `use strict` and `use warnings` to legacy Perl scripts. It will present a unified diff for your review and approval before applying these best practices to your `.pl` or `.pm` files.

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

No, Atlas can build its code index using local Ollama embeddings. This means your Perl codebase, including sensitive `.pm` modules or `cpanfile` details, remains entirely on your local machine, never leaving your third-party servers.

How do I know what changes Atlas is making to my Perl project?

Atlas provides full transparency. It drafts a plan in a read-only agent and asks for your approval before switching to a build agent. For every file edit, it computes a unified diff and surfaces it for your explicit approval before writing any changes to your Perl files.

Onboard to an unfamiliar codebase in Perl with Atlas in 2026

In 2026, Perl developers can rapidly build a working mental model of an unfamiliar codebase using Atlas, a terminal-native AI coding agent. Atlas integrates directly with the Perl toolchain, understanding `cpanm` distributions and `Test2::V0` test suites, allowing you to grasp repository structure and key functionalities without manually sifting through every `.pm` file.

How Atlas Indexes Perl Codebases for Rapid Onboarding

Atlas, in 2026, indexes Perl codebases by understanding their Abstract Syntax Tree (AST) declarations, not just blind line windows. This allows it to grasp the structure of `.pm` modules and `@EXPORT` lists, providing a deeper, more accurate semantic understanding than keyword-only searches.

When you run Atlas in a Perl distribution containing a `cpanfile` or `Makefile.PL`, it automatically begins to build its code index. This process involves parsing Perl modules and scripts using tree-sitter, which recognizes AST declarations. This means Atlas understands the relationships between `use` statements, package declarations, and exported symbols, rather than simply matching text. For instance, if you ask Atlas about 'how requests are authenticated', it queries this semantic index, returning ranked snippets and file paths that are contextually relevant to Perl's module system, such as `My::Auth::Module.pm` or a specific subroutine within a package.

Exploring Perl Code Structure with Atlas's Read-Only Subagents

To build a mental model of a Perl codebase in 2026, Atlas employs an `explore` subagent, which operates with a deny-by-default permission set. This ensures that while you're investigating the repository's layout and naming conventions, no unintended modifications occur to your `lib/` or `t/` directories.

After an initial semantic search with `codebase_search`, you can use the `glob` tool to quickly map the top-level directories and understand the package layout, such as `lib/My/App.pm` or `script/my_daemon.pl`. For deeper, read-only investigations, you delegate tasks to the `explore` subagent via the `task` tool. This subagent is strictly permissioned to only allow safe operations like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This allows you to perform wide sweeps, for example, finding all modules that `use My::Database` or examining the contents of `t/` for `Test2::V0` test patterns, without any risk of altering the codebase.

Following Perl Module Dependencies and Recording Insights

Atlas helps Perl developers in 2026 trace module dependencies and record their learning efficiently. After reviewing initial files, the `lsp` tool's `goToDefinition` operation allows you to navigate `use` statements, while `todowrite` captures your insights and remaining questions.

Once `codebase_search` has identified two or three highly relevant Perl files, you can `read` them directly within Atlas. If a file `use`s another module, like `use My::Utility;`, you can immediately follow that dependency using the `lsp` tool's `goToDefinition` operation. This quickly builds a dependency graph in your mind. As you uncover information or identify areas needing further investigation, you can use the `todowrite` tool to record your findings as a list. This ensures that your mental model evolves systematically and that open questions, such as 'How does `My::Service` handle errors?', are preserved for subsequent turns, preventing loss of context.

Ensuring Code Quality and Safety in Perl with Atlas

Atlas prioritizes code quality and safety for Perl development in 2026, integrating directly with `prove (Test2::V0)` and `perltidy`. Every proposed change, from adding `use strict` to formatting with `.perltidyrc`, is presented as a unified diff for explicit approval.

When Atlas suggests modifications, such as adding `use strict` and `use warnings` to a legacy Perl script or writing new `Test2::V0` test cases under `t/`, it operates with a strong emphasis on safety. Before any changes are committed, Atlas computes a unified diff and surfaces it for your approval. If Atlas is tasked with running tests, it will execute `prove -lr t/` behind a permission prompt, showing you the raw TAP output. Similarly, if code formatting is involved, Atlas will run `perltidy` on the changed files, ensuring the diff aligns with your project's `.perltidyrc` configuration. This granular control and transparency mean you always understand and approve the exact changes Atlas proposes.

Step by step

01Run `atlas` in your Perl distribution, ensuring it can read your `cpanfile` or `Makefile.PL` to index packages and modules.
02Ask `codebase_search` a plain-language question about the Perl codebase, for example, "how are requests authenticated in this Perl application?" to get ranked `.pm` file snippets.
03Run `glob */` on the top-level directories to quickly understand the Perl package layout and naming conventions, looking for `lib/`, `script/`, `t/`.
04Use `read path/to/highest_ranked.pm` to examine the top two or three Perl module files identified by `codebase_search`.
05Follow Perl module `use` statements with `lsp goToDefinition` to navigate dependencies and build a mental map of the call stack.
06Delegate wide sweeps to the `explore` subagent using `task "grep -r 'DBI->connect' lib/"` to find database connections in Perl modules, ensuring read-only operations.
07Record your findings and any remaining questions as a `todowrite` list, such as "Investigate `My::Auth::Module`'s `_check_password` subroutine."
08If Atlas suggests code changes, review the unified diff carefully before approving, especially for Perl idioms like `use strict` or `Test2::V0` test cases.
09When prompted, allow Atlas to run `prove -lr t/` to see the TAP output for your Perl test suite.
10Approve Atlas running `perltidy` on changed Perl files to ensure formatting adheres to your `.perltidyrc`.

Frequently asked questions

How does Atlas understand my Perl modules and packages?: Atlas uses tree-sitter to index your Perl code by AST declarations, recognizing `package` statements, `use` directives, and `@EXPORT` lists. This allows it to understand the semantic structure of your `.pm` files, not just keywords, providing more accurate search results and context.
Can Atlas help me find where a specific Perl subroutine is called?: Yes, after an initial `codebase_search` to locate relevant files, you can use the `lsp` tool's `goToDefinition` operation on a subroutine call within a Perl module. This will navigate you directly to its definition, helping you trace execution flow.
Is it safe to let Atlas explore my Perl codebase?: Absolutely. The `explore` subagent, designed for wide sweeps, operates with a deny-by-default permission set. It is restricted to read-only tools like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`, ensuring it cannot modify any of your Perl files or configuration like `cpanfile` or `Makefile.PL`.
How does Atlas handle Perl testing with `Test2::V0`?: Atlas understands `Test2::V0` test suites. When tasked with running tests, it will execute the `prove -lr t/` command behind a permission prompt. You will see the raw TAP output directly in your terminal, allowing you to verify test results before any changes are committed.
Will Atlas mess up my Perl code formatting?: No, Atlas respects your Perl coding style. If it makes any changes, it will run `perltidy` on the modified files, ensuring the resulting diff adheres to your project's `.perltidyrc` configuration. All proposed changes are presented as a unified diff for your approval.
Can Atlas help me add `use strict` and `use warnings` to old Perl scripts?: Yes, Atlas can draft a plan to add `use strict` and `use warnings` to legacy Perl scripts. It will present a unified diff for your review and approval before applying these best practices to your `.pl` or `.pm` files.
Does Atlas send my Perl code to external servers for indexing?: No, Atlas can build its code index using local Ollama embeddings. This means your Perl codebase, including sensitive `.pm` modules or `cpanfile` details, remains entirely on your local machine, never leaving your third-party servers.
How do I know what changes Atlas is making to my Perl project?: Atlas provides full transparency. It drafts a plan in a read-only agent and asks for your approval before switching to a build agent. For every file edit, it computes a unified diff and surfaces it for your explicit approval before writing any changes to your Perl files.

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

Review a Pull Request in Perl with Atlas in 2026

Review Perl pull requests efficiently in 2026 with Atlas. Catch subtle bugs by examining full file context, running prove (Test2::V0) tests, and ensuring 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.

Write unit tests for untested code in Perl with Atlas in 2026

In 2026, use Atlas to write unit tests for untested Perl modules. Atlas understands your cpanm dependencies and Test2::V0 conventions, ensuring new tests fit your existing codebase.

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.

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

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.

Browse this resource hub