django-ai-toolkit

AI-assisted Django development tools. Three standalone, zero-dependency utilities designed for AI agents (Claude Code, Codex, Cursor) navigating Django codebases.

Tools

index — URL Navigation Index

Resolves Django URL patterns to view files, templates, and test files using pure AST analysis. Generates INDEX.md and INDEX.json for agent navigation.

django-ai-toolkit index --root . --entry-module myapp.urls

toc — Table of Contents Generator

Generates sidecar *.TOC.md files for large Python files, listing top-level classes, functions, and section markers with line numbers.

django-ai-toolkit toc --root . --roots src/app src/lib

drift — Documentation Drift Guard

Checks that shared invariants (keywords) are present across documentation files. Supports both CLI args and config files.

# Config file (recommended)
django-ai-toolkit drift --config .ai-drift.toml

# Inline args
django-ai-toolkit drift --files CLAUDE.md AGENTS.md --invariant "tests:manage.py test,pytest"

Installation

# Core tools (zero dependencies)
pip install django-ai-toolkit

# With Django management commands
pip install django-ai-toolkit[django]

Config File: .ai-drift.toml

Define invariant checks in a TOML file instead of repeating CLI args:

[[groups]]
files = ["CLAUDE.md", "AGENTS.md"]
[groups.invariants]
i18n = ["translate", "makemessages"]
tests = ["manage.py test"]

[[groups]]
files = ["api/CLAUDE.md"]
[groups.invariants]
auth = ["authentication_classes", "permission_classes"]

Each [[groups]] defines a set of files that must all contain at least one keyword from each invariant.

Django Integration

Add django_ai_toolkit to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_ai_toolkit",
]

Then use management commands:

python manage.py ai_index --entry-module myapp.urls
python manage.py ai_toc --roots myapp utils
python manage.py ai_drift --config .ai-drift.toml

CLI Reference

django-ai-toolkit index

Argument	Description
--root	Repository root (default: .)
--entry-module	Entry URL module (required, repeatable)
--test-dir	Test directory (repeatable; default: auto-discover)
--scan-dir	Directory for large file scan (repeatable; default: all top-level)
--check	Check mode — exits 1 if files are out of date
--index-md	Output markdown path (default: INDEX.md)
--index-json	Output JSON path (default: INDEX.json)

django-ai-toolkit toc

Argument	Description
--root	Repository root (default: .)
--roots	Directories to scan (required)
--min-lines	Minimum line threshold (default: 500)
--check	Check mode

django-ai-toolkit drift

Argument	Description
--config	Path to .ai-drift.toml config file
--files	Documentation files to check (not needed with --config)
--invariant	name:keyword1,keyword2,... (repeatable, not needed with --config)
--root	Root directory

Python API

from django_ai_toolkit.index import build_index, render_markdown
from django_ai_toolkit.toc import render_toc, run
from django_ai_toolkit.drift import check_group, check_config, load_config

License

MIT