Agent Zero DOX

Purpose

• Own project-wide engineering rules and the top-level DOX index.
• Keep detailed contracts in the closest applicable child AGENTS.md.

Project

• Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO.
• Start the WebUI with python run_ui.py; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port.
• Run the full test suite with pytest or a focused file with pytest tests/test_name.py.
• Human-facing documentation lives in README.md and docs/.

Root Ownership

• agent.py owns Agent, AgentContext, and loop data.
• initialize.py owns framework initialization.
• models.py owns model-provider configuration and LiteLLM integration.
• run_ui.py is the WebUI entry point.
• DockerfileLocal must remain compatible with the contracts under docker/.
• Runtime or user state under usr/ and tmp/ is intentionally outside tracked DOX unless the user explicitly asks otherwise.

Project-Wide Contracts

• Import AgentContext and AgentContextType from agent, not helpers.context.
• Never commit secrets, .env files, API keys, tokens, or private user data.
• Preserve authentication and CSRF protections.
• Use Linux paths and commands in examples.
• When a live Dockerized Agent Zero target is explicitly named, verify that exact runtime instead of assuming a fixed localhost port.
• Copy live core-plugin changes back into tracked source under plugins/.
• Develop new custom plugins under ignored usr/plugins/; tracked bundled plugins live under plugins/.
• Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.

Permissions

Allowed without asking:

• Read repository files.
• Update files under usr/.

Ask before:

• Installing dependencies.
• Deleting core files outside usr/ or tmp/.
• Modifying agent.py or initialize.py.
• Creating commits or pushing branches.

DOX Workflow

• AGENTS.md files are binding contracts for their subtrees.
• Before editing, read this file and every AGENTS.md on the path to each target; the closest contract controls local details without weakening parent rules.
• Keep work understandable from the applicable DOX chain. Put project-wide rules here and concrete ownership, workflows, inputs, outputs, side effects, and verification in child docs.
• Create a child AGENTS.md only for a durable boundary with distinct ownership or workflow.
• Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index.
• After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification.
• Do not document ignored usr/ or tmp/ changes unless explicitly requested.
• Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance.

Child DOX Index

Intentionally unindexed local or generated roots:

Source: AGENTS.md