@samitouri / QOSami_Agents_Zero
Code Commits Issues Pulls Sessions CI/CD
main
main
md 158 lines 5.4 KB
Rendered Raw
1 # Create A Small Plugin
2
3 The fastest way to understand Agent Zero plugins is to make one small enough to
4 hold in your head.
5
6 This guide walks through a real example: a local plugin named `unread_dot` that
7 adds a pulsing dot beside a chat when that chat receives new activity while you
8 are looking somewhere else.
9
10 ![Unread dot in the chat list](../res/usage/webui/unread-dot-chat-list.png)
11
12 For architecture and source-linked internals, use
13 [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). This page
14 stays practical: what to ask, where files appear, what to check, and how to know
15 the plugin actually works.
16
17 ## What You Are Making
18
19 `unread_dot` is intentionally tiny:
20
21 - it does not add a server endpoint;
22 - it adds no tool;
23 - it installs no package;
24 - it makes no network calls;
25 - it touches only the Web UI and one browser `localStorage` key.
26
27 That makes it a good first plugin. You can see the whole shape without learning
28 every plugin feature at once.
29
30 ## Ask Agent Zero To Build It
31
32 Open a new chat and give Agent Zero a very specific plugin task:
33
34 ```text
35 Use the a0-create-plugin skill.
36
37 Create a local-only plugin named unread_dot in /a0/usr/plugins/unread_dot.
38 The plugin should show a pulsing dot in the chat list whenever a non-selected
39 chat receives new agent activity.
40
41 Keep it minimal and frontend-only:
42 - no external dependencies;
43 - no backend API;
44 - no tools;
45 - no network calls.
46
47 If the plugin already exists, improve it instead of creating a duplicate.
48 When finished, run the a0-review-plugin skill on unread_dot and summarize
49 PASS/WARN/FAIL. Do not run CodeRabbit.
50 ```
51
52 The important part is not the exact wording. The important part is giving Agent
53 Zero the plugin name, the location, the visible behavior, and the boundaries.
54
55 ## Where The Files Go
56
57 Local plugins live under `/a0/usr/plugins/<plugin_name>/` inside the running
58 Agent Zero instance. For this example, the final plugin shape is:
59
60 ```text
61 /a0/usr/plugins/unread_dot/
62 ├── plugin.yaml
63 ├── README.md
64 ├── extensions/
65 │ └── webui/
66 │ ├── apply_snapshot_before/
67 │ │ └── track-unread.js
68 │ └── initFw_end/
69 │ └── bootstrap-unread-dot.js
70 └── webui/
71 ├── unread-dot.css
72 └── unread-dot-store.js
73 ```
74
75 `plugin.yaml` is the plugin's name tag:
76
77 ```yaml
78 name: unread_dot
79 title: Unread Dot
80 description: Shows a pulsing dot beside chats that received new activity while you were elsewhere.
81 version: 1.0.0
82 settings_sections: []
83 per_project_config: false
84 per_agent_config: false
85 ```
86
87 The two Web UI extension files are the little doorways into the running
88 interface:
89
90 - `initFw_end/bootstrap-unread-dot.js` loads the store and stylesheet after the Web UI starts.
91 - `apply_snapshot_before/track-unread.js` watches state snapshots so the plugin can notice when another chat changes.
92
93 The store keeps the unread state. The CSS draws the dot.
94
95 ## Try It For Real
96
97 After creating or changing a plugin, restart Agent Zero so the Web UI extension
98 list is rebuilt.
99
100 Then test the behavior:
101
102 1. Open a fresh chat.
103 2. Send a short prompt, such as:
104
105 ```text
106 Please reply with one short sentence: unread dot live test complete.
107 ```
108
109 3. Immediately switch to another chat.
110 4. Wait for Agent Zero to keep working in the first chat.
111 5. Look at the chat list.
112
113 If the first chat receives new activity while it is not selected, the dot appears.
114 When you open that chat again, the dot clears.
115
116 This example watches for chat activity. In normal use, that means "the agent did
117 something in a chat you were not watching." It does not read every message in
118 every other chat.
119
120 ## Review It
121
122 Run the plugin review skill before treating the plugin as done:
123
124 ```text
125 Use the a0-review-plugin skill to review /a0/usr/plugins/unread_dot.
126 Report PASS/WARN/FAIL by phase.
127 ```
128
129 For this example, the review result is:
130
131 | Phase | Result | Notes |
132 | --- | --- | --- |
133 | Manifest | PASS | `plugin.yaml` is valid, named correctly, and uses simple local settings. |
134 | Structure | PASS with WARN | The layout is standard. `LICENSE` is absent, which is fine locally but blocks Plugin Index submission. |
135 | Code patterns | PASS with WARN | The store uses Agent Zero's `createStore` pattern. The unread signal is chat activity, not a parsed message-author check. |
136 | Security and index | PASS with WARN | No secrets, subprocesses, dependencies, or outbound calls. The community index already has a related `Chat Status Marklet` plugin, so treat this as a learning example unless you make it clearly different. |
137
138 Status: ready as a local demo plugin. Not ready as a new community submission
139 until it has a license and a reason to exist separately from similar plugins.
140
141 ## Make The Example Yours
142
143 Once the small version works, change only one thing at a time:
144
145 - move the dot to a different place in the row;
146 - use a badge instead of a dot;
147 - add a plugin setting for color or animation;
148 - show a different status for running chats and finished chats;
149 - turn the plugin into a publishable project with a `LICENSE`, screenshots, and a clearer README.
150
151 Small plugins are good teachers. You can see the whole machine turning without
152 standing inside the engine.
153
154 ## Related
155
156 - [Usage Guide](usage.md#plugins-and-plugin-hub): where plugins appear in the Web UI.
157 - [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero): source-linked architecture when you need it.
158 - [Contributing Guide](contribution.md): expectations before sharing changes upstream.