How do I use an AI agent to understand a Django codebase I just inherited?

Run atlas in the directory with manage.py, ask codebase_search a plain-language question such as how requests are authenticated, and read the two or three files it ranks highest. Then run glob to see the app layout and follow imports with the lsp tool's goToDefinition operation.

Can Atlas read my Django project without changing any files?

Yes. Delegate the sweep to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it holds no edit tools at all.

Does Atlas work with uv and pyproject.toml in a Django project?

Yes. Atlas drives uv through its bash tool, so it can sync the environment from pyproject.toml and then run pytest-django against it. Every bash call is permission-gated against allow, ask, and deny rules before it runs.

How does Atlas find where authentication happens in a Django app?

Atlas asks codebase_search, which queries the semantic index rather than matching literal strings. That surfaces AUTHENTICATION_BACKENDS in settings.py, permission classes, and middleware even when none of them contain the word you typed.

Will Atlas run pytest-django for me?

Atlas runs pytest-django through the bash tool once you allow it in your permission rules. Running the suite is the fastest way to learn a Django project's fixtures and conftest.py conventions while onboarding.

Is it safe to index a private Django repo with Atlas?

Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers. Every Atlas tool call is also permission-gated against allow, ask, and deny rules before it runs, so reading settings.py or executing manage.py is a choice you make.

How do I keep track of what I learned during Django onboarding?

Record it as a todowrite list. Atlas's documented onboarding workflow ends with a todowrite list so the open questions about a Django repo survive into the next turn rather than dying with the session.

Does Atlas understand Django class-based views when it reads a file?

Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a class-based view in views.py is retrieved as a whole declaration rather than an arbitrary line slice that cuts a method in half.

Onboard to an Unfamiliar Codebase in Django with Atlas (2026)

To onboard to an unfamiliar Django codebase with Atlas, start from meaning rather than filenames. Ask codebase_search a plain-language question such as how requests are authenticated, and Atlas queries its semantic index and returns ranked snippets with file paths. Then run glob over the top-level directories to see the app layout around manage.py, read the two or three files that ranked highest, and follow imports with the lsp tool's goToDefinition operation. Dependencies come from uv, the suite runs under pytest-django, and style is checked with ruff format, so every guess you make about the project can be confirmed with a real command.

How do you onboard to an unfamiliar Django codebase with Atlas?

Atlas onboards you to an unfamiliar Django codebase by starting from meaning, not filenames. In 2026 the first move is codebase_search, a plain-language question like how requests are authenticated, which queries the semantic index and returns ranked snippets with file paths across your apps, models, and settings.

Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, which matters in Django because the concept you are hunting rarely uses the words you would grep for. A question about authentication surfaces a custom AUTHENTICATION_BACKENDS entry in settings.py, a permission class under api/permissions.py, and a middleware in core/middleware.py, none of which necessarily contain the word you typed. Run atlas in a project with a manage.py, let Atlas read your apps, models, and settings, and the ranked snippet list becomes the reading order for your first hour. The workflow Atlas documents for onboarding is a short one: ask codebase_search a plain-language question, run glob on the top-level directories, read the two or three highest ranked files, delegate wide sweeps to the explore subagent through the task tool, and record what you learned as a todowrite list so the open questions survive into the next turn.

Which Atlas tools map a Django project layout?

Atlas maps a Django project layout with glob, which lists the top-level directories before a single file is opened. A typical Django repo shows manage.py at the root, a settings package, and one directory per installed app, each holding the 4 familiar members: models.py, views.py, urls.py, and a migrations folder.

The glob tool is the cheapest way to learn a Django project's naming conventions, and Atlas runs it before read for exactly that reason. Once glob shows you that the project keeps apps under a src/ or apps/ prefix, that settings are split into base.py, dev.py, and prod.py, and that migrations live in per-app migrations/ directories, the shape of the repository is settled and reading becomes targeted. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so when the read tool pulls apps/billing/models.py you get whole model classes and whole methods rather than an arbitrary 200 line slice that cuts a Meta class in half. Combine glob with the pyproject.toml that uv manages and you also learn which third-party Django packages are in play before you have opened a view.

How does the Atlas explore subagent read a Django repo safely?

The Atlas explore subagent reads a Django repo under a deny-by-default permission set that allows only 6 tools: grep, glob, read, bash, webfetch, and websearch. Zero edit tools, so a wide sweep across every installed app cannot modify models.py or write a migration while the agent is looking around.

Onboarding usually needs breadth, and breadth is where an agent does the most accidental damage. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, and the explore subagent is the one you want here because it is defined read-only. Delegate through the task tool with a question like enumerate every Django app that defines a custom manage.py command, and the subagent can grep, glob, read, and run bash without ever holding an edit tool. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so even the bash it does get is checked against your rules. The result comes back as a summary rather than 30,000 tokens of raw file content, which keeps the main session's context free for the files that actually matter.

How do you follow Django imports with the Atlas lsp tool?

Atlas follows Django imports with the lsp tool's goToDefinition operation, jumping from a view's import of a serializer or a model straight to the declaration. In a 2026 Django project that means moving from apps/orders/views.py to apps/orders/serializers.py to apps/orders/models.py in three hops, without guessing at paths.

Django's indirection is what makes onboarding slow. A URL in urls.py points at a view, the view leans on a serializer or a form, the form leans on a model, and the model's behavior is half in models.py and half in a signal handler registered in apps.py. The lsp tool's goToDefinition operation walks that chain against the language server rather than against a regex, so an import of a model aliased at the top of a views.py file still resolves. Read the two or three files codebase_search ranked highest first, then let goToDefinition carry you into the next layer. When the trail runs cold, drop back to grep for the string, since Django wires plenty of behavior through settings strings and dotted paths that no import statement ever mentions.

How do you confirm what you learned about a Django codebase?

Confirming what you learned about a Django codebase means running its real commands. Atlas resolves dependencies with uv, runs the suite with pytest-django, and checks formatting with ruff format, all through the bash tool, so a mental model built in 2026 is verified against the project rather than assumed.

The fastest way to prove you understand a Django app is to make it do something. Ask Atlas to add a model field with a migration or write a test, review the diff, and see whether the suite still passes. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so nothing lands in apps/billing/models.py without you seeing the exact lines. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which means a throwaway experiment during onboarding stays throwaway. Run pytest-django on the app you just read, watch which fixtures load, and you learn more about the project's conftest.py conventions in one command than in an hour of reading. Record the open questions in a todowrite list so the next session starts where this one stopped.

Is it safe to point Atlas at a private Django codebase?

Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, which is the answer most teams need before pointing an agent at a private Django monolith. Every Atlas tool call is also gated against 3 rule types, allow, ask, and deny, before it runs.

A Django repo carries settings modules, secret key handling, and database configuration, so the permission story has to come first. Atlas gates every tool call, including read, bash, and webfetch, against allow, ask, and deny rules, so you decide up front whether Atlas may execute manage.py at all. For the index itself, Atlas can build its code index with local Ollama embeddings, which means the AST declarations that tree-sitter extracts from your views.py and models.py never leave the machine. Atlas is a terminal-native TUI rendered with SolidJS through the OpenTUI renderer, so the whole onboarding session happens inside the same terminal where you already run uv, pytest-django, and ruff format. Nothing about the workflow requires uploading the repo anywhere.

Step by step

01Run atlas in the project root, the directory that contains manage.py, so Atlas can read your apps, models, and settings.
02Ask codebase_search a plain-language question such as how requests are authenticated; it queries the semantic index and returns ranked snippets with file paths into settings.py, middleware, and your app packages.
03Run glob on the top-level directories to see the package layout, the settings split, and the per-app migrations folders before opening anything.
04Read the two or three files codebase_search ranked highest, for example apps/orders/views.py and apps/orders/models.py, then follow the imports with the lsp tool's goToDefinition operation.
05Delegate wide sweeps to the explore subagent through the task tool; it is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch.
06Install and sync dependencies with uv through the bash tool so the environment matches pyproject.toml before you run anything.
07Run the suite with pytest-django through the bash tool to see which fixtures and conftest.py conventions the project relies on.
08Ask Atlas to add a model field with a migration or write a test, and review the unified diff Atlas surfaces before it writes.
09Run ruff format on the touched files so your first contribution matches the repo's existing style.
10Record every open question as a todowrite list so the unknowns survive into the next Atlas session.

Frequently asked questions

How do I use an AI agent to understand a Django codebase I just inherited?: Run atlas in the directory with manage.py, ask codebase_search a plain-language question such as how requests are authenticated, and read the two or three files it ranks highest. Then run glob to see the app layout and follow imports with the lsp tool's goToDefinition operation.
Can Atlas read my Django project without changing any files?: Yes. Delegate the sweep to the explore subagent through the task tool. The explore subagent is defined with a deny-by-default permission set that only allows grep, glob, read, bash, webfetch, and websearch, so it holds no edit tools at all.
Does Atlas work with uv and pyproject.toml in a Django project?: Yes. Atlas drives uv through its bash tool, so it can sync the environment from pyproject.toml and then run pytest-django against it. Every bash call is permission-gated against allow, ask, and deny rules before it runs.
How does Atlas find where authentication happens in a Django app?: Atlas asks codebase_search, which queries the semantic index rather than matching literal strings. That surfaces AUTHENTICATION_BACKENDS in settings.py, permission classes, and middleware even when none of them contain the word you typed.
Will Atlas run pytest-django for me?: Atlas runs pytest-django through the bash tool once you allow it in your permission rules. Running the suite is the fastest way to learn a Django project's fixtures and conftest.py conventions while onboarding.
Is it safe to index a private Django repo with Atlas?: Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers. Every Atlas tool call is also permission-gated against allow, ask, and deny rules before it runs, so reading settings.py or executing manage.py is a choice you make.
How do I keep track of what I learned during Django onboarding?: Record it as a todowrite list. Atlas's documented onboarding workflow ends with a todowrite list so the open questions about a Django repo survive into the next turn rather than dying with the session.
Does Atlas understand Django class-based views when it reads a file?: Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a class-based view in views.py is retrieved as a whole declaration rather than an arbitrary line slice that cuts a method in half.

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 Django in 2026

Atlas, the terminal-native AI coding agent, empowers Django developers in 2026. Boost productivity across models, views, and migrations with secure, reviewable AI assistance.

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

Streamline Django test triage in 2026 with Atlas. Turn walls of `pytest-django` output into prioritized, distinct root causes, accelerating your debugging workflow.

Add a Regression Test for a Bug Fix in Django with Atlas in 2026

Lock in Django bug fixes with Atlas by writing failing regression tests using pytest-django, applying fixes, and verifying with real commands. Ensure code quality in 2026.

Refactor a legacy module in Django with Atlas in 2026

Streamline legacy Django modules in 2026 with Atlas. Safely restructure code, maintain behavior, and prevent breaking changes using `pytest-django`, `uv`, and `ruff format`.

Extract a Shared Helper from Duplicated Code in Django with Atlas in 2026

In 2026, Django developers use Atlas to find and refactor duplicated logic into shared helpers. Leverage semantic search, automated patching, and `pytest-django` for safe, efficient code consolidation.

Locate Where a Behavior Is Implemented in Django with Atlas (2026)

Find the Django view, model, or signal behind a behavior in 2026: Atlas attacks it with codebase_search, grep, and the lsp tool, then confirms with pytest-django.

Run Atlas Headless in CI for Django Projects in 2026

In 2026, Django developers can run Atlas headless in CI pipelines to automate code changes and get machine-readable output. Integrate Atlas with pytest-django and uv for efficient, automated development workflows.

Browse this resource hub