Spaces:
Sleeping
Sleeping
| # 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. | |
| - Message-loop completion flows through a response tool with `break_loop`; plain or malformed Chat Completions text enters repair, and native Responses output text is normalized through the same response-tool path. | |
| - Reuse the startup-preloaded local embedding model for matching runtime configurations; wrappers retain their own rate-limit configuration while sharing the underlying inference model. | |
| - Prompt Markdown may retain fenced JSON examples for readability; final system-prompt rendering removes only their JSON fence markers before model calls and preserves non-JSON fences. | |
| - 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 | |
| | Child | Scope | | |
| | --- | --- | | |
| | [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. | | |
| | [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and tools. | | |
| | [api/AGENTS.md](api/AGENTS.md) | HTTP API and WebSocket handler entry points. | | |
| | [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. | | |
| | [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, images, compose files, and runtime layout. | | |
| | [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation and screenshots. | | |
| | [extensions/AGENTS.md](extensions/AGENTS.md) | Backend and WebUI lifecycle extensions. | | |
| | [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend utilities and runtime services. | | |
| | [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge. | | |
| | [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helpers outside the WebUI bundle. | | |
| | [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins and custom-plugin architecture. | | |
| | [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates. | | |
| | [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts and automation inputs. | | |
| | [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills. | | |
| | [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. | | |
| | [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. | | |
| | [webui/AGENTS.md](webui/AGENTS.md) | Alpine.js WebUI shell, components, JavaScript, CSS, and assets. | | |
| Intentionally unindexed local or generated roots: | |
| | Path | Reason | | |
| | --- | --- | | |
| | `.conda/`, `.venv/` | Local Python environments. | | |
| | `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. | | |
| | `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. | | |
| | `tmp/` | Ignored runtime caches, uploads, and generated work. | | |
| | `usr/` | Ignored local user data, settings, plugins, chats, and workdirs. | | |
| | `python/` | Generated or legacy runtime mirror; current source is in root modules and tracked source directories. | | |