Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (73 loc) · 5.02 KB

AGENTS.md

File metadata and controls

92 lines (73 loc) · 5.02 KB
Raw

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.
  • Treat the Docker container exposed at localhost:32080 as the live plugin/backend runtime when that target is named.
  • 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 Actions workflows and release automation scripts.
agents/AGENTS.md Bundled agent profiles, profile-local prompts, and tools.
api/AGENTS.md HTTP API and WebSocket handler entry points.
conf/AGENTS.md Repository-shipped configuration defaults and templates.
docker/AGENTS.md Docker build contexts, images, compose files, and runtime layout.
docs/AGENTS.md Human-facing documentation and screenshots.
extensions/AGENTS.md Backend and WebUI lifecycle extensions.
helpers/AGENTS.md Shared backend utilities and runtime services.
knowledge/AGENTS.md Built-in agent self-knowledge.
lib/AGENTS.md Lightweight browser-side helpers outside the WebUI bundle.
plugins/AGENTS.md Bundled system plugins and custom-plugin architecture.
prompts/AGENTS.md Core prompt templates.
scripts/AGENTS.md Repository maintenance scripts and automation inputs.
skills/AGENTS.md Bundled Agent Zero skills.
tests/AGENTS.md Pytest regression and contract tests.
tools/AGENTS.md Core agent tool implementations.
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.
logs/ Runtime output.
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.