Atlas onboards you to an unfamiliar Python codebase by starting from meaning, not filenames. You ask codebase_search a plain-language question, glob maps the package layout around pyproject.toml or requirements.txt, and read opens only the two or three modules that actually matter. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a query returns a real Python function or class. You then confirm behavior with pytest, resolve the virtualenv with uv, and learn the formatting baseline with ruff format.
How do you understand a Python codebase you have never seen before?
Atlas builds a mental model of an unfamiliar Python codebase in 2026 by asking codebase_search a plain-language question, for example how requests are authenticated. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so the answer is ranked snippets with real file paths.
The job to be done is building a working mental model of a repository you have never seen before, without reading every file. In a Python project that starts at the package root beside pyproject.toml or requirements.txt, and then lets Atlas rank the modules that implement the behavior you asked about. Because Atlas indexes code by AST declarations using tree-sitter, a question about session handling surfaces the whole authenticate function in a FastAPI dependency or the Django middleware class that wraps it, rather than an arbitrary slice of lines. Atlas reads your package layout, virtualenv, and installed dependencies first, so the ranked results reflect the code that is actually importable in the environment you run pytest against.
Which Atlas tools map a Python repository fastest?
Atlas maps a Python repository with 6 tools: codebase_search, glob, read, lsp, task, and todowrite. Run glob on the top-level directories first to see the package layout and naming conventions, whether the project uses a src layout, a flat package, or one Django app per directory.
codebase_search answers the meaning question, and glob answers the shape question. Running glob over the top-level directories tells you within seconds whether you are looking at src/yourpkg/__init__.py, a flat package next to requirements.txt, or a uv-managed workspace declared in pyproject.toml. Once glob has shown you the shape, read opens the two or three .py modules that codebase_search ranked highest, and the lsp tool's goToDefinition operation follows an import such as from app.services import billing straight to the module that defines it. todowrite captures what you learned so the open questions survive into the next turn instead of evaporating when the session context rolls over.
What does Atlas read first in a Python project with pyproject.toml?
Atlas starts a Python onboarding session in the directory that holds pyproject.toml or requirements.txt. Atlas reads your package layout, virtualenv, and installed dependencies before it opens any source, so the first 2 or 3 files it reads are the modules codebase_search ranked highest, not a random __init__.py.
Reading order matters in Python because the interesting code is rarely in the file with the obvious name. A repository can hide its request authentication in app/dependencies.py, in a Django middleware module, or in a decorator defined three packages away. Atlas ranks candidates from the semantic index, opens the top hits with read, and then walks imports with the lsp tool's goToDefinition operation until the call path is concrete. Dependency questions get answered from the environment: uv resolves what is installed, so when the ranked snippet imports a third-party client you can tell immediately whether the pin lives in pyproject.toml or in requirements.txt.
How does the Atlas explore subagent keep Python onboarding read-only?
Atlas delegates wide sweeps across a Python monorepo to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that allows only grep, glob, read, bash, webfetch, and websearch, so a sweep across your .py files in 2026 cannot modify one of them.
Onboarding means reading a lot, and reading a lot is exactly where an agent can quietly go wrong. Atlas fans out that work to subagents that can run in the foreground or in parallel background sessions, and the explore subagent it uses for onboarding carries a read-only permission set. Even a bash invocation inside the sweep, such as a pytest run, is checked against the same permission rules before it executes. If you later ask for an edit, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and it snapshots file changes as git patches so an unwanted change to a .py module can be rolled back.
How do you confirm what you learned with pytest, uv, and ruff format?
Atlas closes a Python onboarding pass with 3 real commands. Run uv to sync the virtualenv, pytest to see which suites pass on a clean checkout, and ruff format to learn the formatting baseline. Atlas records the remaining open questions as a todowrite list before the session ends.
A mental model is only real once the code runs. pytest tells you which behavior is covered and which is folklore, and the failures you see on a fresh clone are themselves onboarding documentation. uv gives you a reproducible virtualenv from pyproject.toml or requirements.txt, so the pytest run reflects the pinned dependency tree rather than whatever is on your machine. ruff format shows the project's formatting conventions without you having to reverse-engineer them from a style guide. conftest.py and the pytest suite tell you which behavior is actually covered, and uv tells you the dependency versions that coverage was measured against.
Which Python files does Atlas open during onboarding?
Atlas opens 5 kinds of Python file during onboarding: pyproject.toml or requirements.txt for dependencies, __init__.py for the package tree, conftest.py for pytest fixtures, the modules codebase_search ranked highest, and any Django settings module or FastAPI app module the project defines.
pyproject.toml tells Atlas which dependencies uv will install, and requirements.txt does the same job in older Python repositories. conftest.py is where pytest fixtures live, so reading conftest.py tells you how the pytest suite builds its objects, which is often the fastest description of the domain model a Python project has. __init__.py files reveal the package tree and any re-exports that make an import path misleading. ruff format settles the formatting conventions. Between pyproject.toml, conftest.py, and the pytest suite, most Python repositories explain themselves faster than their README does.
Step by step
- 01Run atlas in the repository root that contains pyproject.toml or requirements.txt, and let Atlas read your package layout, virtualenv, and installed dependencies.
- 02Ask codebase_search a plain-language question, for example how requests are authenticated, and review the ranked .py snippets it returns with file paths.
- 03Run glob on the top-level directories to see the package layout and naming conventions, such as src/yourpkg/__init__.py, before opening anything.
- 04Read the two or three Python modules codebase_search ranked highest, then follow each import with the lsp tool's goToDefinition operation.
- 05Delegate a wide sweep to the explore subagent through the task tool; its deny-by-default permission set allows only grep, glob, read, bash, webfetch, and websearch.
- 06Sync the virtualenv with uv, then run pytest to see which suites pass on a clean checkout of the Python project.
- 07Run ruff format to learn the formatting baseline before you propose your first edit.
- 08Record what you learned, and every open question, as a todowrite list so it survives into the next turn.
Frequently asked questions
- how do I quickly understand a large Python codebase
- Ask Atlas a plain-language question through codebase_search, run glob on the top-level directories to see the package layout, then read only the two or three modules that ranked highest. Follow imports with the lsp tool's goToDefinition operation instead of opening every .py file.
- can an AI agent explore a Python repo without changing any files
- Yes. Atlas delegates wide sweeps to the explore subagent through the task tool, and the explore subagent has a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it cannot edit a .py file.
- does Atlas work with pyproject.toml and uv
- Yes. Run atlas in a repo with a pyproject.toml or requirements.txt and it reads your package layout, virtualenv, and installed dependencies. uv is the package manager Atlas expects for resolving that environment before you run pytest.
- how does Atlas find Python code when I do not know the function name
- Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and it indexes code by AST declarations using tree-sitter. codebase_search therefore returns the matching Python declaration even when your wording never appears in the source.
- can Atlas run pytest and ruff format while I onboard
- Yes. Atlas runs pytest to show which suites pass on a clean checkout and ruff format to reveal the project's formatting baseline. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs.
- does Atlas send my Python source code to a third-party server
- Not necessarily. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, which matters when the pyproject.toml project you are onboarding to is private or regulated.
- how do I keep notes while onboarding to a Python project with Atlas
- Record what you learned as a todowrite list. Atlas keeps the open questions in that list so they survive into the next turn, which is useful when a Django or FastAPI service takes several sessions to understand.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated 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 Python in 2026
Atlas is a terminal-native AI coding agent for Python in 2026. Run it in a repo with a pyproject.toml or requirements.txt and review every diff before it lands.
Extract a Shared Helper From Duplicated Code in Python with Atlas (2026)
Duplication in Python is semantic, not textual. Atlas finds near-duplicate logic with codebase_search in 2026, collapses it with apply_patch, and proves it with pytest.
Self-Review Your Working Diff Before Committing in Python With Atlas (2026)
How to self-review a Python working diff before committing with Atlas in 2026: read the whole diff, grep for leftover breakpoints, then run pytest and ruff format.
Run Atlas Headless in CI in a Python Repo: The 2026 Guide to atlas run
Run Atlas headless in CI on a Python repo in 2026. Use atlas run with --format json, pre-approve tools, and gate the pipeline on pytest, uv, and ruff format.
Review a pull request in Python with Atlas (2026)
Review a Python pull request in 2026 with Atlas: read the changed .py files in full, check callers with findReferences, and run pytest before you approve the diff.
Upgrade Python Dependencies and Fix Breakage with Atlas in 2026
In 2026, Python developers use Atlas to upgrade dependencies like Django or FastAPI, automatically fixing compile and test failures with `uv`, `pytest`, and `ruff format`.
Audit a Python Repo with Parallel Subagents in Atlas (2026)
Audit a Python repo with parallel Atlas subagents in 2026. Slice by package, launch read-only explore tasks, and merge findings without flooding your context.