Metadata-Version: 2.4
Name: claude-on-django
Version: 0.3.1
Summary: Autonomous development framework for the Django-Bolt ecosystem — Rust-powered Django APIs
Project-URL: Homepage, https://github.com/beret/claude_on_django
Project-URL: Issues, https://github.com/beret/claude_on_django/issues
Author-email: Adam Mańczuk <beret@hipisi.org.pl>
License: MIT License
        
        Copyright (c) 2026 Adam Mańczuk
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,autonomous,claude,django,swarm
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: django-bolt>=0.7
Requires-Dist: django>=4.2
Requires-Dist: msgspec
Requires-Dist: pydantic-ai
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/dj-bolt/django-bolt) for Rust-powered API performance (60k+ RPS via Actix Web + PyO3).

## Table of Contents

- [Quick Start](#quick-start)
- [Project Generator](#project-generator)
- [Integrating with Existing Projects](#integrating-with-existing-projects)
- [Agent Team](#agent-team)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Development](#development)
- [License](#license)

## Quick Start

### Requirements

- Python 3.12+
- An [Anthropic API key](https://console.anthropic.com/) with credits

### Install

```bash
pip install claude-on-django
```

### Generate a Project

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

```bash
# 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

```bash
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`:

```bash
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](https://github.com/dj-bolt/django-bolt) (BoltAPI, ModelViewSet) |
| Serialization | [msgspec.Struct](https://jcristharif.com/msgspec/) (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

```bash
pip install claude-on-django
```

### 2. Add to INSTALLED_APPS

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

### 3. Initialize

```bash
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:

```bash
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](https://ai.pydantic.dev/) 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

```bash
# 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

```python
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:

```bash
# 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

```bash
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

```bash
# 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](https://github.com/FarhanAliRaza/claude-context-local) as an MCP server:

```bash
# 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](LICENSE) for details.
