Agent-zero a0-debug-plugin

Diagnose and fix Agent Zero plugin problems. Covers plugin not appearing, won't enable, API endpoints not responding, frontend store errors, extension point injection, settings resolution, hooks.py issues, and log inspection. Use when a plugin is not working, not loading, crashing, missing from the list, or behaving unexpectedly.

install

source · Clone the upstream repo

git clone https://github.com/agent0ai/agent-zero

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/agent0ai/agent-zero "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/a0-debug-plugin" ~/.claude/skills/agent0ai-agent-zero-a0-debug-plugin && rm -rf "$T"

manifest: skills/a0-debug-plugin/SKILL.md

Agent Zero Plugin Debugger

Work through these checks in order. Stop at the first failure and fix it before continuing.

1. Plugin not appearing in the Plugins list

# Check plugin.yaml exists
ls /a0/usr/plugins/<name>/plugin.yaml

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('/a0/usr/plugins/<name>/plugin.yaml'))"

# Check directory name doesn't start with '.'
ls /a0/usr/plugins/

Common causes:

Missing
```
plugin.yaml
```
- plugin not discovered
Invalid YAML syntax - plugin skipped silently
Directory name starts with
```
.
```
- skipped by discovery

2. Plugin appears but won't enable

# Check toggle state
ls -la /a0/usr/plugins/<name>/.toggle-*

# Check for conflicting scoped toggles
ls -la project/.a0proj/plugins/<name>/.toggle-* 2>/dev/null
ls -la /a0/usr/agents/default/plugins/<name>/.toggle-* 2>/dev/null

3. API endpoint not responding

Verify the handler file is in
```
api/
```
and subclasses
```
ApiHandler
```

Route format:

POST /api/plugins/<plugin_name>/<handler_filename_without_.py>

Check for Python import errors on startup (check Agent Zero logs)

Verify correct import paths:

from agent import AgentContext

not

from helpers.context import AgentContext

# Check for syntax errors in handler
python3 -m py_compile /a0/usr/plugins/<name>/api/my_handler.py

4. Frontend component not rendering / store errors

Check browser console for Alpine.js errors
Verify the store file is imported in HTML
```
<head>
```
via
```
<script type="module">
```
Confirm Store Gate pattern is used (missing gate = undefined error if store not yet loaded)
Verify store name in
```
createStore(...)
```
matches
```
$store.<name>
```
in templates

5. Extension point not injecting

Check the HTML file is in

extensions/webui/<correct_breakpoint_name>/

Verify the breakpoint name exists in core UI (check
```
webui/index.html
```
or component files for
```
<x-extension id="...">
```
)

Common breakpoints:

sidebar-quick-actions-main-start

plugins-list-header-buttons

chat-input-bottom-actions-end

Confirm the HTML file has a root element with
```
x-data
```
and an
```
x-move-*
```
directive

For backend extension hooks:

Named lifecycle hooks must live under
```
extensions/python/<point>/
```

Implicit

@extensible

hooks must live under

extensions/python/_functions/<module>/<qualname>/<start|end>/

The retired flattened form

extensions/python/<module>_<qualname>_<start|end>/

no longer loads

6. Settings not saving / loading wrong values

Config resolution order (highest priority first):

project/.a0proj/agents/<profile>/plugins/<name>/config.json

project/.a0proj/plugins/<name>/config.json

usr/agents/<profile>/plugins/<name>/config.json

```
usr/plugins/<name>/config.json
```
```
plugins/<name>/default_config.yaml
```

# Find which config file is actually being loaded
find /a0 -path "*/plugins/<name>/config.json" 2>/dev/null

7. hooks.py install hook not running

The

install()

hook is called automatically by the plugin installer after placement. If it didn't run:

Check the function is named exactly
```
install
```
(not
```
on_install
```
or similar)
Check for exceptions in the function (add try/except with print for debugging)
Manually trigger in the framework runtime (not via
```
code_execution_tool
```
python - that uses
```
/opt/venv
```
, not
```
/opt/venv-a0
```
):

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'install'))
print('Done')
"

If the

pre_update()

hook is not running before plugin updates:

Check the function is named exactly
```
pre_update
```
Check for exceptions in the function
Manually trigger it in the framework runtime the same way:

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'pre_update'))
print('Done')
"

If the

uninstall()

hook is not running when the plugin is removed:

Check the function is named exactly
```
uninstall
```
(not
```
on_uninstall
```
or similar)
Check for exceptions in the function
The
```
uninstall()
```
hook is called by
```
uninstall_plugin()
```
in
```
helpers/plugins.py
```
before the plugin directory is deleted. If the user removed the plugin manually (
```
rm -rf
```
), the hook was bypassed — always use the API or UI to uninstall.
Manually trigger it in the framework runtime the same way:

cd /a0 && /opt/venv-a0/bin/python -c "
import asyncio
from helpers.plugins import call_plugin_hook
asyncio.run(call_plugin_hook('<plugin_name>', 'uninstall'))
print('Done')
"

8. Check Agent Zero logs

# Find recent log files
ls -lt /a0/logs/*.html | head -5

Plugin-related errors appear as Python tracebacks mentioning the plugin path.

How Plugin Discovery Works

Agent Zero walks
```
usr/plugins/
```
then
```
plugins/
```
at startup
Any directory containing
```
plugin.yaml
```
is treated as a plugin
```
usr/plugins/<name>
```
takes priority over
```
plugins/<name>
```
when both exist (user overrides core)
Toggle state is evaluated:
```
.toggle-0
```
disables,
```
.toggle-1
```
enables, no file = enabled by default
Enabled plugins have their
```
extensions/
```
,
```
api/
```
,
```
tools/
```
, etc. registered into the runtime, including both named extension points and implicit
```
_functions/...
```
extensible hooks

Plugins are re-scanned when:

Agent Zero restarts
A plugin is installed/removed via the installer
The "Refresh" action is triggered in the Plugins UI

References

Plugin architecture:
```
/a0/docs/agents/AGENTS.plugins.md
```
Manage (install/update/uninstall): read
```
/a0/skills/a0-manage-plugin/SKILL.md
```