Django Orbit

AI agent-native runtime evidence and debugging for Django.

Django Orbit records what your application is doing and gives that evidence to you and your coding agent. Requests, SQL, logs, exceptions, jobs, cache operations and other runtime events are linked into bounded, safe context for investigation.

Orbit has its own dashboard at /orbit/ and a read-only MCP server. It does not inject HTML into your application or require you to leave your coding-agent workflow to start debugging.

Install | Try the demo | Connect an agent | Documentation

Why Orbit

When a Django issue reaches a coding agent, the hard part is usually not writing a patch. It is reconstructing what happened:

• Which request or job failed?
• Which SQL queries, logs and exceptions belong to it?
• Is the signal a real regression, a slow query or only duplicate evidence?
• What should be reproduced with a test before changing code?

Orbit captures that runtime evidence locally and keeps it connected by request family. Humans can inspect it in the dashboard. Agents can query a bounded, masked and read-only context through MCP.

The intended workflow is:

runtime event -> Orbit evidence -> agent investigation -> test plan -> fix -> verification

Orbit is inspired by Django Debug Toolbar, Laravel Telescope and Spatie Ray, but lives outside the host application's UI and is designed for APIs, SPAs, background work and AI-assisted debugging.

Install

pip install django-orbit

For MCP access from Claude, Codex, Cursor or another compatible client:

pip install django-orbit[mcp]

Quick Start

Add Orbit to your Django project:

# settings.py
INSTALLED_APPS = [
    # ...
    "orbit",
]

MIDDLEWARE = [
    "orbit.middleware.OrbitMiddleware",
    # ...
]

Mount the dashboard URLs:

# urls.py
from django.urls import include, path

urlpatterns = [
    path("orbit/", include("orbit.urls")),
    # ...
]

Run migrations and start Django:

python manage.py migrate
python manage.py runserver

Open http://localhost:8000/orbit/ and exercise an endpoint in your app. Orbit will show the captured request and its related runtime evidence.

For the full setup, configuration reference and production guidance, see the Quick Start documentation.

Connect a Coding Agent

Orbit's MCP server runs locally over stdio. It reads Orbit evidence and does not modify your application.

Add a server entry to an MCP-compatible client:

{
  "mcpServers": {
    "django-orbit": {
      "command": "python",
      "args": ["manage.py", "orbit_mcp"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

The exact location of this entry depends on the client. See the MCP setup guide for Claude Desktop, Claude Code, Codex, Cursor and other clients.

Ticket to Fix

Once MCP is connected, a practical investigation looks like this:

1. Describe the ticket or failing behavior.
2. Match it to recent Orbit evidence.
3. Inspect the request family, exception group or endpoint window.
4. Generate a masked incident bundle.
5. Ask the agent for ranked hypotheses and a regression-test plan.
6. Inspect the code, write the test and apply the smallest justified fix.
7. Re-run the test and verify the runtime signal again.

Useful tools for this flow include:

Tool	Use
build_debug_brief	Match a ticket description to recent evidence
summarize_request_family	Start with compact metadata and capture-quality warnings
investigate_request	Inspect one request family and related signals
investigate_exception_group	Group an exception fingerprint and affected paths
create_incident_bundle	Create JSON, Markdown or prompt handoff context
propose_fix_hypotheses	Rank possible fix directions from evidence
propose_test_plan	Suggest focused regression or performance tests
generate_pr_context	Prepare evidence and release-risk context for a PR

The agent is not expected to edit code automatically. Orbit supplies context so the agent can investigate, propose and verify with the developer in control.

Agent Safety

MCP output is designed to be safe to inspect before sharing with an agent:

• common sensitive keys are masked;
• result sizes and payloads are bounded;
• MCP_INCLUDE_PAYLOADS: False enables metadata-only output;
• prompts, completions and tool-call arguments are not captured by default;
• audit_mcp_exposure, preview_masked_entry and list_agent_safe_fields expose the effective safety boundary;
• MCP is read-only and can be disabled with MCP_ENABLED: False.

Recommended local or shared-environment settings:

ORBIT_CONFIG = {
    "AUTH_CHECK": lambda request: request.user.is_staff,
    "MCP_ENABLED": True,
    "MCP_INCLUDE_PAYLOADS": False,
    "MCP_MAX_LIMIT": 100,
    "LLM_CAPTURE_CONTENT": False,
    "LLM_CAPTURE_TOOL_CALL_ARGUMENTS": False,
    "WATCHER_FAIL_SILENTLY": True,
}

Orbit records operational context, so /orbit/ and the local MCP process must still be treated as developer or operator access. Read the security guide before enabling it in staging or production.

What Orbit Captures

Orbit supports watchers for the parts of a Django application that usually matter during debugging:

• HTTP requests and responses;
• SQL, slow queries, duplicate evidence and classified N+1 candidates;
• Python logs and exceptions with request context;
• cache, model, transaction and permission activity;
• management commands and background jobs;
• outgoing HTTP, mail, Redis and storage operations;
• AI/LLM metadata such as provider, model, tokens, latency, errors and tool names.

Related events are connected by a family_hash. The full watcher matrix, configuration keys and extension points are documented in the API and configuration reference.

Try the Demo

The repository includes a small Django project with curated scenarios:

git clone https://github.com/astro-stack/django-orbit.git
cd django-orbit
pip install -e .
python demo.py setup
python manage.py runserver

Then open:

URL	Purpose
http://localhost:8000/	Generate demo runtime events
http://localhost:8000/orbit/	Inspect captured evidence
http://localhost:8000/orbit/stats/	Review runtime metrics
http://localhost:8000/orbit/health/	Check watcher health

Run python demo.py reset to restore the curated demo corpus.

See Running the Demo for the complete walkthrough and the Codex/Claude debugging demo.

Current Release: v0.14.0

The 0.14 release improves everyday agent debugging:

• compact metadata-only request summaries through summarize_request_family;
• reliable handoff copying from dynamically loaded event details, with a preview and clipboard fallback;
• less default feed noise: signal capture is now opt-in.

The Evidence API, async-safe correlation, investigation tools and local dashboard remain available. See the MCP reference for tool limits and evidence-quality warnings.

Read the full changelog for the release history.

Documentation Map

• Installation
• Quick Start
• Configuration
• Dashboard guide
• Stats dashboard
• MCP reference
• Evidence API
• Security
• Storage backends
• Roadmap
• Contributing

Orbit Pro

Django Orbit remains MIT-licensed and useful on its own. The open source package includes the local dashboard, watchers, local MCP tools, masking, incident bundles and safety controls.

Orbit Pro is a separate planned self-hosted verification layer for teams using coding agents. It will build on the open core with release comparison, saved investigations and verification of agent-assisted changes. Planned capabilities are not required to use Orbit today.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and read the relevant documentation before changing capture, MCP or safety behavior.

License

MIT. See LICENSE.