{"owner":"agent0ai","repo":"agent-zero","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# Agent Zero DOX\n\n## Purpose\n\n- Own project-wide engineering rules and the top-level DOX index.\n- Keep detailed contracts in the closest applicable child `AGENTS.md`.\n\n## Project\n\n- Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO.\n- Start the WebUI with `python run_ui.py`; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port.\n- Run the full test suite with `pytest` or a focused file with `pytest tests/test_name.py`.\n- Human-facing documentation lives in `README.md` and `docs/`.\n\n## Root Ownership\n\n- `agent.py` owns `Agent`, `AgentContext`, and loop data.\n- `initialize.py` owns framework initialization.\n- `models.py` owns model-provider configuration and LiteLLM integration.\n- `run_ui.py` is the WebUI entry point.\n- `DockerfileLocal` must remain compatible with the contracts under `docker/`.\n- Runtime or user state under `usr/` and `tmp/` is intentionally outside tracked DOX unless the user explicitly asks otherwise.\n\n## Project-Wide Contracts\n\n- Import `AgentContext` and `AgentContextType` from `agent`, not `helpers.context`.\n- Never commit secrets, `.env` files, API keys, tokens, or private user data.\n- Preserve authentication and CSRF protections.\n- Use Linux paths and commands in examples.\n- When a live Dockerized Agent Zero target is explicitly named, verify that exact runtime instead of assuming a fixed localhost port.\n- 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.\n- 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.\n- Copy live core-plugin changes back into tracked source under `plugins/`.\n- Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`.\n- Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.\n\n## Permissions\n\nAllowed without asking:\n\n- Read repository files.\n- Update files under `usr/`.\n\nAsk before:\n\n- Installing dependencies.\n- Deleting core files outside `usr/` or `tmp/`.\n- Modifying `agent.py` or `initialize.py`.\n- Creating commits or pushing branches.\n\n## DOX Workflow\n\n- `AGENTS.md` files are binding contracts for their subtrees.\n- 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.\n- 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.\n- Create a child `AGENTS.md` only for a durable boundary with distinct ownership or workflow.\n- Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index.\n- After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification.\n- Do not document ignored `usr/` or `tmp/` changes unless explicitly requested.\n- Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance.\n\n## Child DOX Index\n\n| Child | Scope |\n| --- | --- |\n| [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. |\n| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and tools. |\n| [api/AGENTS.md](api/AGENTS.md) | HTTP API and WebSocket handler entry points. |\n| [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. |\n| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, images, compose files, and runtime layout. |\n| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation and screenshots. |\n| [extensions/AGENTS.md](extensions/AGENTS.md) | Backend and WebUI lifecycle extensions. |\n| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend utilities and runtime services. |\n| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge. |\n| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helpers outside the WebUI bundle. |\n| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins and custom-plugin architecture. |\n| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates. |\n| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts and automation inputs. |\n| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills. |\n| [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. |\n| [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. |\n| [webui/AGENTS.md](webui/AGENTS.md) | Alpine.js WebUI shell, components, JavaScript, CSS, and assets. |\n\nIntentionally unindexed local or generated roots:\n\n| Path | Reason |\n| --- | --- |\n| `.conda/`, `.venv/` | Local Python environments. |\n| `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. |\n| `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. |\n| `tmp/` | Ignored runtime caches, uploads, and generated work. |\n| `usr/` | Ignored local user data, settings, plugins, chats, and workdirs. |\n| `python/` | Generated or legacy runtime mirror; current source is in root modules and tracked source directories. |\n"}}