claude-on-django 0.3.1

Autonomous development framework for the Django-Bolt ecosystem — Rust-powered Django APIs

Claude-on-Django

Autonomous development framework for the Django-Bolt ecosystem. Describe what you want to build, and a coordinated team of AI agents handles implementation across all Django layers — models, APIs, services, tests, and deployment.

Built on Django-Bolt for Rust-powered API performance (60k+ RPS via Actix Web + PyO3).

Table of Contents

• Quick Start
• Project Generator
• Integrating with Existing Projects
• Agent Team
• Architecture
• Configuration
• Development
• License

Quick Start

Requirements

• Python 3.12+
• An Anthropic API key with credits

Install

pip install claude-on-django

Generate a Project

After installation, the django-generate CLI command is available globally:

# Interactive mode — prompts for project name, app name, item name, output path
django-generate

# Fully specified — no prompts
django-generate --project-name MyApp --app-name myapp --item-name ticket

# Quick defaults (project=Django-bolt, app=app, item=task)
django-generate --no-input

This generates a complete, runnable Django-Bolt project with:

• User registration and profiles
• JWT authentication (django-bolt built-in)
• OAuth login (Google, Apple)
• Project CRUD with owner isolation
• Item CRUD with filtering (status, priority, assignee)
• Item assignment and completion endpoints
• Full unit tests (models, services, auth)
• Full integration tests (schemas, service flows)
• Pagination support
• 60k+ RPS via Rust-powered endpoints

Run the Generated Project

cd myapp/
pip install -r requirements.txt
python manage.py makemigrations myapp
python manage.py migrate
python manage.py test myapp -v 2    # Run tests
python manage.py runbolt --dev      # Start Rust-powered dev server

Project Generator

The django-generate command creates a fully functional Django-Bolt project using AI agents to generate each file. It produces 10 AI-generated files plus 3 static templates.

CLI Options

Option	Description	Default
--project-name	Display name for the project	Django-bolt
--app-name	Python module name for the Django app	app
--item-name	Main CRUD entity name (e.g. task, ticket, order)	task
--path	Output directory	./{project-slug}
--no-input	Skip interactive prompts, use defaults	false
--no-migrate	Skip auto-running makemigrations and migrate	false

As a Django Management Command

If you already have a Django project with claude_on_django in INSTALLED_APPS:

python manage.py claude_generate --project-name MyApp --app-name myapp --item-name ticket

Generated File Structure

myapp/
├── manage.py                    # Django entry point
├── requirements.txt             # Dependencies
├── README.md                    # API documentation
├── Makefile                     # Common tasks
└── myapp/
    ├── __init__.py
    ├── settings.py              # Django settings (SQLite, django-bolt)
    ├── urls.py                  # ROOT_URLCONF (empty — bolt handles routing)
    ├── models.py                # User profiles, projects, items with signals
    ├── schemas.py               # msgspec.Struct schemas with from_model() helpers
    ├── api.py                   # BoltAPI endpoints, ModelViewSets, auth routes
    ├── services/
    │   ├── __init__.py
    │   └── auth_service.py      # JWT tokens, registration, OAuth, refresh
    ├── migrations/
    │   └── __init__.py
    └── tests/
        ├── __init__.py
        ├── test_models.py       # Unit tests (models, auth service)
        └── test_api.py          # Integration tests (schemas, service flows)

Generated API Endpoints

Method	Endpoint	Description
POST	/api/auth/register	User registration
POST	/api/auth/login	JWT login
POST	/api/auth/oauth	OAuth login (Google/Apple)
POST	/api/auth/refresh	Refresh JWT token
GET/PATCH	/api/auth/profile	User profile
GET/POST	/api/projects	List/Create projects
GET/PUT/PATCH/DELETE	/api/projects/{id}	Project detail
GET/POST	/api/{items}	List/Create items
GET/PUT/PATCH/DELETE	/api/{items}/{id}	Item detail
PATCH	/api/{items}/{id}/assign	Assign item
PATCH	/api/{items}/{id}/complete	Complete item

Technology Stack

Layer	Technology
API Framework	Django-Bolt (BoltAPI, ModelViewSet)
Serialization	msgspec.Struct (5-10x faster than DRF)
Authentication	JWT via create_jwt_for_user / Token from django-bolt
Permissions	JWTAuthentication, IsAuthenticated, AllowAny guards
Pagination	PageNumberPagination from django-bolt
Database	Async Django ORM (aget, afilter, asave, acreate)
Runtime	Actix Web + PyO3 (Rust) — 60k+ RPS

Integrating with Existing Projects

Claude-on-Django can analyze and augment any existing Django project with AI agent support.

1. Install

pip install claude-on-django

2. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    'claude_on_django',
]

3. Initialize

python manage.py claude_swarm_init

This analyzes your project and generates:

your-project/
├── CLAUDE.md                              # Project context for Claude
└── .claude-on-django/
    ├── context.md                         # Detected project features
    ├── sessions/                          # Agent session logs
    └── prompts/                           # Agent system prompts
        ├── architect.md
        ├── modeler.md
        ├── api_specialist.md
        ├── views.md
        ├── services.md
        ├── qa_engineer.md
        ├── devops.md
        └── tasks.md

What Gets Detected

Feature	Detection
Django-Bolt	django-bolt in requirements or django_bolt in INSTALLED_APPS
DRF	rest_framework in INSTALLED_APPS
GraphQL	Graphene or Strawberry in requirements
Celery	celery in requirements or celery.py present
HTMX	django-htmx in requirements
Database	PostgreSQL, MySQL, or SQLite from DATABASES
Deployment	Docker, Kubernetes, Heroku, Fly.io configs
Custom Patterns	Services, serializers, permissions, middleware, signals

4. Use with Claude

Once initialized, use Claude to develop across all Django layers:

claude "Add user authentication with JWT and OAuth"
claude "Create a task management API with filtering and pagination"
claude "Optimize the dashboard queries for performance"

The agent prompts in .claude-on-django/prompts/ are fully customizable — edit them to match your team's conventions.

Init Options

Option	Description
--api-only	Force API-only mode (skip Views agent)
--skip-tests	Skip test framework detection
--skip-mcp	Skip MCP server setup

Agent Team

Claude-on-Django coordinates 8 specialized AI agents, each with focused expertise:

Agent	Role	When Active
Architect	System design, coordination, project structure	Always
Modeler	Django models, migrations, database optimization	Always
API Specialist	Django-Bolt APIs, BoltAPI views, JWT/OAuth, msgspec schemas	Always
Views	Templates, class-based views, BoltAPI views (full-stack + API)	Full-stack projects
Services	Business logic, service layer, design patterns	Always
QA Engineer	Unit + integration tests, TDD, test coverage	Always
DevOps	Docker, CI/CD, deployment, production config	Always
Tasks	Celery, background jobs, async task processing	When Celery detected

Agents are orchestrated by SwarmOrchestrator using PydanticAI and communicate through structured task delegation.

Architecture

claude_on_django/
├── project_analyzer.py          # Detects Django project features
├── swarm_builder.py             # Generates agent topology from analysis
├── configuration.py             # Global settings with env var overrides
├── cli.py                       # Standalone CLI entry point (django-generate)
├── orchestrator/
│   ├── swarm.py                 # SwarmOrchestrator (PydanticAI agents)
│   └── maintainer.py            # CLAUDE.md auto-updater
├── toolsets/
│   └── core.py                  # Filesystem and command toolsets
├── mcp_server/
│   ├── structure.py             # API metadata scanning (BoltAPI + DRF patterns)
│   └── support.py               # MCP availability and installation
├── agents/                      # 8 agent system prompts (.md files)
└── management/commands/
    ├── claude_generate.py       # Project generator (AI-powered)
    ├── claude_swarm_init.py     # Project analysis + agent setup
    └── claude_sandbox_generate.py  # Sandbox test wrapper

Core Components

• ProjectAnalyzer — Detects frameworks, databases, deployment, and custom patterns in any Django project
• SwarmBuilder — Builds a conditional agent topology based on the analysis (e.g. API-only skips Views, Celery adds Tasks)
• SwarmOrchestrator — Manages all agents using PydanticAI, routes tasks to the appropriate specialist
• MCP Server — Provides API endpoint metadata via Model Context Protocol, auto-discovers BoltAPI and DRF patterns

Configuration

Environment Variables

# Required: Anthropic API key (for AI code generation)
export ANTHROPIC_API_KEY=sk-ant-...

# Optional: Override the default model
export CLAUDE_ON_DJANGO_MODEL=anthropic:claude-sonnet-4-6

Python Configuration

from claude_on_django import configure

configure(
    default_model="anthropic:claude-opus-4-6",
    vibe_mode=False,
    max_parallel_agents=3,
)

Sandbox Configuration

Generate custom sandbox projects with different names:

# Default: Django-bolt / app / task
make sandbox-init

# Custom: MyApp / myapp / ticket
make sandbox-init SANDBOX_PROJECT=MyApp SANDBOX_APP=myapp SANDBOX_ITEM=ticket

Development

Setup

git clone https://github.com/beret/claude_on_django.git
cd claude_on_django
python -m venv .venv
source .venv/bin/activate
make dev-install

Commands

Command	Description
make install	Install the package
make dev-install	Install in editable mode with dev dependencies
make test	Run package tests (21 tests)
make lint	Run linting (ruff)
make build	Build wheel and sdist with hatch
make publish	Build and publish to PyPI
make clean	Remove build artifacts and sandbox
make sandbox-init	Generate sandbox project, run swarm init and migrations
make sandbox-test	Run sandbox tests (41 tests)
make sandbox-run	Run swarm verification (6 checks)

Running Tests

# Package tests
make test

# Sandbox generation + tests (requires ANTHROPIC_API_KEY)
make sandbox-init
make sandbox-test

# Full verification pipeline
make sandbox-run

Semantic Code Search (Optional)

For improved code generation, set up claude-context-local as an MCP server:

# Install
git clone https://github.com/FarhanAliRaza/claude-context-local ~/.local/share/claude-context-local
cd ~/.local/share/claude-context-local && uv sync

# Register MCP server
claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

# Index django-bolt source
# (use the index_directory MCP tool after restarting Claude Code)

This enables semantic code search across the django-bolt source, helping AI agents generate more accurate code.

License

MIT License - see LICENSE for details.