Agent Atlas

Agent Atlas generates a deterministic, static repository map for coding agents. It uses Griffe to extract Python packages, public symbols, signatures, annotations, docstrings, source locations, and local type references without importing the project being mapped.

No LLM calls. No target-code execution. No invented explanations.

Start with MAP.md, follow the package and module pages to the exact symbol, then open the source. Use deeper graph tools only when relationships or impact analysis actually matter.

Install

pip install agent-atlas-map

Python 3.11 or later is required. The agent-atlas and repo-map commands are equivalent; repo-map is retained as a compatibility alias.

Configure and run

Add a minimal configuration to the target repository's pyproject.toml:

[tool.repo-map]
source_roots = ["src"]
root_packages = ["my_package"]

source_roots defaults to ["src"]. When root_packages is omitted, Agent Atlas discovers importable packages and modules directly below each source root. Output defaults to .repo-map and MAP.md; the paths and additional filtering, policy, summary, and watch settings can be configured in the same table.

# Generate or update the map in the current repository.
agent-atlas build

# Fail when generated files are missing or differ from a fresh render.
agent-atlas check

# Generate once, then rebuild after debounced .py or .pyi source changes.
agent-atlas watch

# Run against another repository.
agent-atlas build --project-root /path/to/project

Output and exit codes

build writes a generated MAP.md at the project root and a .repo-map/ directory containing index.json, package maps, and module maps. check does not write files.

Limits and safety

Agent Atlas is static analysis, not runtime introspection. Dynamically created symbols, imports resolved only at runtime, generated source, and information available only through execution may be absent or unresolved in the map.

Builds stage and validate output before publishing. Agent Atlas refuses to replace output it cannot identify as its own and attempts rollback when a publication step fails. Each target replacement is atomic on the local filesystem, but .repo-map/ and MAP.md are separate targets: a process or filesystem failure between replacements cannot be made globally atomic. Keep the generated files under version control or regenerate after an interrupted build. Publication assumes a locally controlled checkout; it does not defend against another process maliciously replacing target directories during the publication window.

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy
uv build

License

MIT. See LICENSE.