codex-django

Django runtime integration layer for the Codex ecosystem: reusable modules, cabinet UI building blocks, and shared adapters for Codex-shaped Django projects. Project scaffolding now lives in the companion package codex-django-cli, while this repository focuses on installable runtime code.

Install

# Runtime library only
pip install codex-django

# Runtime + companion CLI package
pip install "codex-django[cli]"

# Optional admin theme and Prometheus integration
pip install "codex-django[admin,observability]"

# Runtime + CLI + day-to-day development toolchain
pip install "codex-django[dev]"

Requires Python 3.12 or newer.

Project Scaffolding

The codex-django runtime package no longer owns the CLI implementation. Use the companion package when you want to scaffold or extend a project:

pip install "codex-django[cli]"
# or: pip install codex-django-cli
codex-django init myproject

Temporary compatibility shims remain under codex_django.cli, but the real CLI code lives in codex-django-cli. Select optional scaffolds with init --with-booking --with-messaging, or use codex-django menu for interactive selection.

Development

uv sync --extra maintainer
uv run pytest
uv run mypy src/
uv run pre-commit run --all-files
uv run python tools/dev/check.py --ci
uv build --no-sources

Quick Start

Runtime Example

from datetime import date

from codex_django.booking import DjangoAvailabilityAdapter
from codex_django.booking.selectors import get_available_slots

adapter = DjangoAvailabilityAdapter(
    resource_model=Master,
    appointment_model=Appointment,
    service_model=Service,
    working_day_model=MasterWorkingDay,
    day_off_model=MasterDayOff,
    booking_settings_model=BookingSettings,
    timezone="UTC",
)

result = get_available_slots(
    adapter=adapter,
    service_ids=[1],
    target_date=date.today(),
)

print(result.get_unique_start_times())

What Each Optional Module Adds

• cabinet: user-facing dashboard pages, profile/settings views, and cabinet adapters.
• booking: booking app scaffolds, booking settings, cabinet booking pages, and booking templates.
• messaging: content models, dispatch hooks, campaign primitives, and queue/direct delivery adapters.
• notifications: deprecated compatibility import path for older notification integrations.

Modules

Agent Skills

codex-django includes an optional, offline agent skill installer. From the consuming project's root, use the Python environment where codex-django is installed:

python -m codex_django.agent_skills install --project .
python -m codex_django.agent_skills status --project .

After upgrading the package, refresh the installed instructions separately:

python -m pip install --upgrade codex-django
python -m codex_django.agent_skills update --project .

The installer manages .agents/skills/codex-django/ and a bounded block in the project's root AGENTS.md. Skill installation is optional for normal Python use and requires neither Django configuration nor the [cli] extra. The Agent Skills Guide covers removal, ownership, and recovery.

Documentation

Full docs with architecture, API reference, and generated project structure:

https://codexdlc.github.io/codex-django/

• Agent Skills Guide (EN) | Руководство по агентским навыкам (RU)

Part of the Codex ecosystem

Each library is fully standalone — install only what your project needs. Together they form the backbone of codex-bot (Telegram AI-agent infrastructure built on aiogram) and codex-django (Django integration layer and scaffolding toolkit).