zubo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/.github/workflows/ci.yml +35 -0
  2. package/README.md +149 -0
  3. package/bun.lock +216 -0
  4. package/desktop/README.md +57 -0
  5. package/desktop/package.json +12 -0
  6. package/desktop/src-tauri/Cargo.toml +25 -0
  7. package/desktop/src-tauri/build.rs +3 -0
  8. package/desktop/src-tauri/icons/README.md +17 -0
  9. package/desktop/src-tauri/icons/icon.png +0 -0
  10. package/desktop/src-tauri/src/main.rs +189 -0
  11. package/desktop/src-tauri/tauri.conf.json +68 -0
  12. package/docs/ROADMAP.md +490 -0
  13. package/migrations/001_init.sql +9 -0
  14. package/migrations/002_memory.sql +33 -0
  15. package/migrations/003_cron.sql +24 -0
  16. package/migrations/004_usage.sql +12 -0
  17. package/migrations/005_secrets.sql +8 -0
  18. package/migrations/006_agents.sql +1 -0
  19. package/migrations/007_workflows.sql +22 -0
  20. package/migrations/008_proactive.sql +24 -0
  21. package/migrations/009_uploads.sql +9 -0
  22. package/migrations/010_observability.sql +22 -0
  23. package/migrations/011_api_keys.sql +7 -0
  24. package/migrations/012_indexes.sql +5 -0
  25. package/migrations/013_budget.sql +11 -0
  26. package/migrations/014_usage_session_idx.sql +2 -0
  27. package/package.json +39 -0
  28. package/site/404.html +156 -0
  29. package/site/CNAME +1 -0
  30. package/site/docs/agents.html +294 -0
  31. package/site/docs/api.html +446 -0
  32. package/site/docs/channels.html +345 -0
  33. package/site/docs/cli.html +238 -0
  34. package/site/docs/config.html +1034 -0
  35. package/site/docs/index.html +433 -0
  36. package/site/docs/integrations.html +381 -0
  37. package/site/docs/memory.html +254 -0
  38. package/site/docs/security.html +375 -0
  39. package/site/docs/skills.html +322 -0
  40. package/site/docs.css +412 -0
  41. package/site/index.html +638 -0
  42. package/site/install.sh +98 -0
  43. package/site/logo.svg +1 -0
  44. package/site/og-image.png +0 -0
  45. package/site/robots.txt +4 -0
  46. package/site/script.js +361 -0
  47. package/site/sitemap.xml +63 -0
  48. package/site/skills.html +532 -0
  49. package/site/style.css +1686 -0
  50. package/src/agent/agents.ts +159 -0
  51. package/src/agent/compaction.ts +53 -0
  52. package/src/agent/context.ts +18 -0
  53. package/src/agent/delegate.ts +118 -0
  54. package/src/agent/loop.ts +318 -0
  55. package/src/agent/prompts.ts +111 -0
  56. package/src/agent/session.ts +87 -0
  57. package/src/agent/teams.ts +116 -0
  58. package/src/agent/workflow-executor.ts +192 -0
  59. package/src/agent/workflow.ts +175 -0
  60. package/src/channels/adapter.ts +21 -0
  61. package/src/channels/dashboard.html.ts +2969 -0
  62. package/src/channels/discord.ts +137 -0
  63. package/src/channels/optional-deps.d.ts +17 -0
  64. package/src/channels/router.ts +199 -0
  65. package/src/channels/signal.ts +133 -0
  66. package/src/channels/slack.ts +101 -0
  67. package/src/channels/telegram.ts +102 -0
  68. package/src/channels/utils.ts +18 -0
  69. package/src/channels/webchat.ts +1797 -0
  70. package/src/channels/whatsapp.ts +119 -0
  71. package/src/config/loader.ts +22 -0
  72. package/src/config/paths.ts +43 -0
  73. package/src/config/schema.ts +121 -0
  74. package/src/db/connection.ts +20 -0
  75. package/src/db/export.ts +148 -0
  76. package/src/db/migrations.ts +42 -0
  77. package/src/index.ts +261 -0
  78. package/src/llm/claude.ts +193 -0
  79. package/src/llm/factory.ts +115 -0
  80. package/src/llm/failover.ts +101 -0
  81. package/src/llm/openai-compat.ts +409 -0
  82. package/src/llm/provider.ts +83 -0
  83. package/src/llm/smart-router.ts +241 -0
  84. package/src/logs.ts +53 -0
  85. package/src/memory/chunker.ts +58 -0
  86. package/src/memory/document-parser.ts +115 -0
  87. package/src/memory/embedder.ts +235 -0
  88. package/src/memory/engine.ts +170 -0
  89. package/src/memory/fts-index.ts +55 -0
  90. package/src/memory/hybrid-search.ts +72 -0
  91. package/src/memory/store.ts +56 -0
  92. package/src/memory/vector-index.ts +72 -0
  93. package/src/model.ts +118 -0
  94. package/src/registry/cli.ts +43 -0
  95. package/src/registry/client.ts +54 -0
  96. package/src/registry/installer.ts +67 -0
  97. package/src/scheduler/briefing.ts +71 -0
  98. package/src/scheduler/cron.ts +258 -0
  99. package/src/scheduler/heartbeat.ts +58 -0
  100. package/src/scheduler/memory-triggers.ts +100 -0
  101. package/src/scheduler/natural-cron.ts +163 -0
  102. package/src/scheduler/proactive.ts +25 -0
  103. package/src/scheduler/recipes.ts +110 -0
  104. package/src/secrets/store.ts +64 -0
  105. package/src/setup.ts +413 -0
  106. package/src/skills.ts +293 -0
  107. package/src/start.ts +373 -0
  108. package/src/status.ts +165 -0
  109. package/src/tools/builtin/connect-service.ts +205 -0
  110. package/src/tools/builtin/cron.ts +126 -0
  111. package/src/tools/builtin/datetime.ts +36 -0
  112. package/src/tools/builtin/delegate-task.ts +81 -0
  113. package/src/tools/builtin/delegate.ts +42 -0
  114. package/src/tools/builtin/diagnose.ts +41 -0
  115. package/src/tools/builtin/google-oauth.ts +379 -0
  116. package/src/tools/builtin/manage-agents.ts +149 -0
  117. package/src/tools/builtin/manage-skills.ts +294 -0
  118. package/src/tools/builtin/manage-teams.ts +89 -0
  119. package/src/tools/builtin/manage-triggers.ts +94 -0
  120. package/src/tools/builtin/manage-workflows.ts +119 -0
  121. package/src/tools/builtin/memory-search.ts +38 -0
  122. package/src/tools/builtin/memory-write.ts +30 -0
  123. package/src/tools/builtin/run-workflow.ts +36 -0
  124. package/src/tools/builtin/secrets.ts +122 -0
  125. package/src/tools/builtin/skill-registry.ts +75 -0
  126. package/src/tools/builtin-integrations/api-helpers.ts +26 -0
  127. package/src/tools/builtin-integrations/github/github_issues/SKILL.md +56 -0
  128. package/src/tools/builtin-integrations/github/github_issues/handler.ts +108 -0
  129. package/src/tools/builtin-integrations/github/github_prs/SKILL.md +57 -0
  130. package/src/tools/builtin-integrations/github/github_prs/handler.ts +113 -0
  131. package/src/tools/builtin-integrations/github/github_repos/SKILL.md +37 -0
  132. package/src/tools/builtin-integrations/github/github_repos/handler.ts +88 -0
  133. package/src/tools/builtin-integrations/google/gmail/SKILL.md +51 -0
  134. package/src/tools/builtin-integrations/google/gmail/handler.ts +125 -0
  135. package/src/tools/builtin-integrations/google/google_calendar/SKILL.md +35 -0
  136. package/src/tools/builtin-integrations/google/google_calendar/handler.ts +105 -0
  137. package/src/tools/builtin-integrations/google/google_docs/SKILL.md +35 -0
  138. package/src/tools/builtin-integrations/google/google_docs/handler.ts +108 -0
  139. package/src/tools/builtin-integrations/google/google_drive/SKILL.md +39 -0
  140. package/src/tools/builtin-integrations/google/google_drive/handler.ts +106 -0
  141. package/src/tools/builtin-integrations/google/google_sheets/SKILL.md +36 -0
  142. package/src/tools/builtin-integrations/google/google_sheets/handler.ts +116 -0
  143. package/src/tools/builtin-integrations/jira/jira_boards/SKILL.md +21 -0
  144. package/src/tools/builtin-integrations/jira/jira_boards/handler.ts +74 -0
  145. package/src/tools/builtin-integrations/jira/jira_issues/SKILL.md +28 -0
  146. package/src/tools/builtin-integrations/jira/jira_issues/handler.ts +140 -0
  147. package/src/tools/builtin-integrations/linear/linear_issues/SKILL.md +30 -0
  148. package/src/tools/builtin-integrations/linear/linear_issues/handler.ts +75 -0
  149. package/src/tools/builtin-integrations/linear/linear_projects/SKILL.md +21 -0
  150. package/src/tools/builtin-integrations/linear/linear_projects/handler.ts +43 -0
  151. package/src/tools/builtin-integrations/notion/notion_databases/SKILL.md +39 -0
  152. package/src/tools/builtin-integrations/notion/notion_databases/handler.ts +83 -0
  153. package/src/tools/builtin-integrations/notion/notion_pages/SKILL.md +43 -0
  154. package/src/tools/builtin-integrations/notion/notion_pages/handler.ts +130 -0
  155. package/src/tools/builtin-integrations/notion/notion_search/SKILL.md +27 -0
  156. package/src/tools/builtin-integrations/notion/notion_search/handler.ts +69 -0
  157. package/src/tools/builtin-integrations/slack/slack_messages/SKILL.md +42 -0
  158. package/src/tools/builtin-integrations/slack/slack_messages/handler.ts +72 -0
  159. package/src/tools/builtin-integrations/twitter/twitter_posts/SKILL.md +24 -0
  160. package/src/tools/builtin-integrations/twitter/twitter_posts/handler.ts +133 -0
  161. package/src/tools/builtin-skills/file-read/SKILL.md +26 -0
  162. package/src/tools/builtin-skills/file-read/handler.ts +66 -0
  163. package/src/tools/builtin-skills/file-write/SKILL.md +30 -0
  164. package/src/tools/builtin-skills/file-write/handler.ts +64 -0
  165. package/src/tools/builtin-skills/http-request/SKILL.md +34 -0
  166. package/src/tools/builtin-skills/http-request/handler.ts +87 -0
  167. package/src/tools/builtin-skills/shell/SKILL.md +26 -0
  168. package/src/tools/builtin-skills/shell/handler.ts +96 -0
  169. package/src/tools/builtin-skills/url-fetch/SKILL.md +26 -0
  170. package/src/tools/builtin-skills/url-fetch/handler.ts +37 -0
  171. package/src/tools/builtin-skills/web-search/SKILL.md +26 -0
  172. package/src/tools/builtin-skills/web-search/handler.ts +50 -0
  173. package/src/tools/executor.ts +205 -0
  174. package/src/tools/integration-installer.ts +106 -0
  175. package/src/tools/permissions.ts +45 -0
  176. package/src/tools/registry.ts +39 -0
  177. package/src/tools/sandbox-runner.ts +56 -0
  178. package/src/tools/sandbox.ts +82 -0
  179. package/src/tools/skill-installer.ts +52 -0
  180. package/src/tools/skill-loader.ts +259 -0
  181. package/src/types/optional-deps.d.ts +23 -0
  182. package/src/util/auth.ts +121 -0
  183. package/src/util/costs.ts +59 -0
  184. package/src/util/error-buffer.ts +32 -0
  185. package/src/util/google-tokens.ts +180 -0
  186. package/src/util/logger.ts +73 -0
  187. package/src/util/perf-collector.ts +35 -0
  188. package/src/util/rate-limiter.ts +70 -0
  189. package/src/util/tokens.ts +17 -0
  190. package/src/voice/stt.ts +57 -0
  191. package/src/voice/tts.ts +103 -0
  192. package/tests/agent/session.test.ts +109 -0
  193. package/tests/agent-loop.test.ts +54 -0
  194. package/tests/auth.test.ts +89 -0
  195. package/tests/channels.test.ts +67 -0
  196. package/tests/compaction.test.ts +44 -0
  197. package/tests/config.test.ts +51 -0
  198. package/tests/costs.test.ts +19 -0
  199. package/tests/cron.test.ts +55 -0
  200. package/tests/db/export.test.ts +219 -0
  201. package/tests/executor.test.ts +144 -0
  202. package/tests/export.test.ts +137 -0
  203. package/tests/helpers/mock-llm.ts +34 -0
  204. package/tests/helpers/test-db.ts +74 -0
  205. package/tests/integration/chat-flow.test.ts +48 -0
  206. package/tests/integrations.test.ts +97 -0
  207. package/tests/memory/engine.test.ts +114 -0
  208. package/tests/memory-engine.test.ts +57 -0
  209. package/tests/permissions.test.ts +21 -0
  210. package/tests/rate-limiter.test.ts +70 -0
  211. package/tests/registry.test.ts +67 -0
  212. package/tests/router.test.ts +36 -0
  213. package/tests/session.test.ts +58 -0
  214. package/tests/skill-loader.test.ts +44 -0
  215. package/tests/tokens.test.ts +30 -0
  216. package/tests/tools/executor.test.ts +130 -0
  217. package/tests/util/auth.test.ts +75 -0
  218. package/tests/util/rate-limiter.test.ts +73 -0
  219. package/tests/voice.test.ts +60 -0
  220. package/tests/webchat.test.ts +88 -0
  221. package/tests/workflow.test.ts +38 -0
  222. package/tsconfig.json +16 -0
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "zubo",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "bin": {
6
+ "zubo": "src/index.ts"
7
+ },
8
+ "scripts": {
9
+ "setup": "bun run src/index.ts setup",
10
+ "start": "bun run src/index.ts start",
11
+ "start:daemon": "bun run src/index.ts start --daemon",
12
+ "stop": "bun run src/index.ts stop",
13
+ "status": "bun run src/index.ts status",
14
+ "logs": "bun run src/index.ts logs",
15
+ "logs:follow": "bun run src/index.ts logs --follow",
16
+ "model": "bun run src/index.ts model",
17
+ "skills": "bun run src/index.ts skills",
18
+ "dev": "bun run --watch src/index.ts start",
19
+ "desktop:dev": "cd desktop && npm run dev",
20
+ "desktop:build": "cd desktop && npm run build",
21
+ "test": "bun test"
22
+ },
23
+ "dependencies": {
24
+ "@anthropic-ai/sdk": "^0.39.0",
25
+ "croner": "^9.0.0",
26
+ "discord.js": "^14.25.1",
27
+ "grammy": "^1.35.0",
28
+ "onnxruntime-node": "^1.24.1",
29
+ "sqlite-vec": "^0.1.7-alpha.2",
30
+ "zod": "^3.24.0"
31
+ },
32
+ "devDependencies": {
33
+ "@types/bun": "^1.2.0",
34
+ "typescript": "^5.9.3"
35
+ },
36
+ "trustedDependencies": [
37
+ "onnxruntime-node"
38
+ ]
39
+ }
package/site/404.html ADDED
@@ -0,0 +1,156 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>404 — Page Not Found | Zubo</title>
7
+ <meta name="description" content="The page you're looking for doesn't exist. Head back to Zubo's home page.">
8
+ <meta name="theme-color" content="#060608">
9
+ <link rel="canonical" href="https://zubo.bot/404.html">
10
+ <meta property="og:title" content="404 — Page Not Found | Zubo">
11
+ <meta property="og:description" content="The page you're looking for doesn't exist. Head back to Zubo's home page.">
12
+ <meta property="og:type" content="website">
13
+ <meta property="og:url" content="https://zubo.bot/404.html">
14
+ <meta property="og:image" content="https://zubo.bot/og-image.png">
15
+ <meta property="og:site_name" content="Zubo">
16
+ <meta name="twitter:card" content="summary_large_image">
17
+ <meta name="twitter:title" content="404 — Page Not Found | Zubo">
18
+ <meta name="twitter:description" content="The page you're looking for doesn't exist. Head back to Zubo's home page.">
19
+ <meta name="twitter:image" content="https://zubo.bot/og-image.png">
20
+ <meta name="twitter:creator" content="@thomaskanze">
21
+ <meta name="robots" content="noindex, follow">
22
+ <link rel="preconnect" href="https://fonts.googleapis.com">
23
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
24
+ <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,700;12..96,800&family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
25
+ <link rel="stylesheet" href="style.css">
26
+ <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%237c3aed'/><path d='M50 15C52 37 63 48 85 50C63 52 52 63 50 85C48 63 37 52 15 50C37 48 48 37 50 15Z' fill='white'/></svg>">
27
+ <style>
28
+ .error-page {
29
+ min-height: 100vh;
30
+ display: flex;
31
+ flex-direction: column;
32
+ }
33
+ .error-content {
34
+ flex: 1;
35
+ display: flex;
36
+ align-items: center;
37
+ justify-content: center;
38
+ text-align: center;
39
+ padding: 6rem 1.5rem 4rem;
40
+ }
41
+ .error-inner {
42
+ max-width: 480px;
43
+ }
44
+ .error-code {
45
+ font-family: 'Bricolage Grotesque', sans-serif;
46
+ font-size: clamp(6rem, 15vw, 10rem);
47
+ font-weight: 800;
48
+ line-height: 1;
49
+ background: linear-gradient(135deg, #7c3aed 0%, #a78bfa 50%, #7c3aed 100%);
50
+ -webkit-background-clip: text;
51
+ -webkit-text-fill-color: transparent;
52
+ background-clip: text;
53
+ margin-bottom: 0.5rem;
54
+ }
55
+ .error-subtitle {
56
+ font-family: 'DM Sans', sans-serif;
57
+ font-size: 1.25rem;
58
+ color: rgba(255, 255, 255, 0.6);
59
+ margin-bottom: 2rem;
60
+ font-weight: 400;
61
+ }
62
+ .error-description {
63
+ font-family: 'DM Sans', sans-serif;
64
+ font-size: 0.95rem;
65
+ color: rgba(255, 255, 255, 0.4);
66
+ line-height: 1.6;
67
+ margin-bottom: 2.5rem;
68
+ }
69
+ </style>
70
+ </head>
71
+ <body>
72
+ <div class="error-page">
73
+
74
+ <!-- Subtle noise overlay -->
75
+ <div class="noise" aria-hidden="true"></div>
76
+
77
+ <!-- ========== NAVIGATION ========== -->
78
+ <header class="nav" id="nav">
79
+ <div class="nav-inner">
80
+ <a href="index.html" class="nav-logo">
81
+ <span class="logo-wordmark">zubo</span>
82
+ </a>
83
+ <nav class="nav-links" id="nav-links">
84
+ <a href="index.html#features">Features</a>
85
+ <a href="docs/index.html">Docs</a>
86
+ <a href="skills.html">Skills</a>
87
+ <a href="index.html#get-started">Get Started</a>
88
+ </nav>
89
+ <div class="nav-right">
90
+ <a href="https://github.com/apwn/zubo" class="nav-github" aria-label="GitHub">
91
+ <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
92
+ </a>
93
+ <a href="index.html#get-started" class="btn btn-primary btn-nav">Get Started</a>
94
+ <button class="nav-toggle" id="nav-toggle" aria-label="Toggle menu">
95
+ <span></span><span></span><span></span>
96
+ </button>
97
+ </div>
98
+ </div>
99
+ </header>
100
+
101
+ <!-- ========== 404 CONTENT ========== -->
102
+ <main class="error-content">
103
+ <div class="error-inner">
104
+ <div class="error-code">404</div>
105
+ <h1 class="error-subtitle">Page not found</h1>
106
+ <p class="error-description">The page you're looking for doesn't exist or has been moved. Let's get you back on track.</p>
107
+ <a href="index.html" class="btn btn-primary btn-lg">
108
+ <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M19 12H5"/><polyline points="12 19 5 12 12 5"/></svg>
109
+ Back to Home
110
+ </a>
111
+ </div>
112
+ </main>
113
+
114
+ <!-- ========== FOOTER ========== -->
115
+ <footer class="footer">
116
+ <div class="container">
117
+ <div class="footer-inner">
118
+ <div class="footer-brand">
119
+ <a href="index.html" class="nav-logo">
120
+ <span class="logo-wordmark">zubo</span>
121
+ </a>
122
+ <p>Your AI agent that never forgets.</p>
123
+ </div>
124
+ <div class="footer-links">
125
+ <div class="footer-col">
126
+ <h5>Product</h5>
127
+ <a href="index.html#features">Features</a>
128
+ <a href="index.html#integrations">Integrations</a>
129
+ <a href="index.html#channels">Channels</a>
130
+ <a href="index.html#get-started">Get Started</a>
131
+ </div>
132
+ <div class="footer-col">
133
+ <h5>Resources</h5>
134
+ <a href="docs/index.html">Documentation</a>
135
+ <a href="skills.html">Community Skills</a>
136
+ <a href="https://github.com/apwn/zubo">GitHub</a>
137
+ <a href="https://github.com/apwn/zubo/issues">Issues</a>
138
+ </div>
139
+ <div class="footer-col">
140
+ <h5>Community</h5>
141
+ <a href="https://github.com/apwn/zubo/discussions">Discussions</a>
142
+ <a href="https://github.com/apwn/zubo/blob/main/CONTRIBUTING.md">Contributing</a>
143
+ </div>
144
+ </div>
145
+ </div>
146
+ <div class="footer-bottom">
147
+ <p>&copy; 2026 Zubo. MIT License. Created in the jungle by <a href="https://x.com/thomaskanze" target="_blank" rel="noopener">@thomaskanze</a>.</p>
148
+ </div>
149
+ </div>
150
+ </footer>
151
+
152
+ </div>
153
+
154
+ <script src="script.js"></script>
155
+ </body>
156
+ </html>
package/site/CNAME ADDED
@@ -0,0 +1 @@
1
+ zubo.bot
package/site/docs/agents.html ADDED
@@ -0,0 +1,294 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Agents &amp; Workflows — Zubo Docs</title>
7
+ <meta name="description" content="Learn how to create custom agents, delegate tasks to sub-agents, build multi-step workflows, and organize agent teams in Zubo.">
8
+ <meta name="theme-color" content="#060608">
9
+ <link rel="canonical" href="https://zubo.bot/docs/agents.html">
10
+ <meta property="og:title" content="Agents &amp; Workflows — Zubo Docs">
11
+ <meta property="og:description" content="Create custom agents, delegate tasks to sub-agents, build multi-step workflows, and organize agent teams in Zubo.">
12
+ <meta property="og:type" content="article">
13
+ <meta property="og:url" content="https://zubo.bot/docs/agents.html">
14
+ <meta property="og:image" content="https://zubo.bot/og-image.png">
15
+ <meta property="og:site_name" content="Zubo">
16
+ <meta name="twitter:card" content="summary_large_image">
17
+ <meta name="twitter:title" content="Agents &amp; Workflows — Zubo Docs">
18
+ <meta name="twitter:description" content="Create custom agents, delegate tasks to sub-agents, and build multi-step workflows in Zubo.">
19
+ <meta name="twitter:image" content="https://zubo.bot/og-image.png">
20
+ <meta name="twitter:creator" content="@thomaskanze">
21
+ <link rel="preconnect" href="https://fonts.googleapis.com">
22
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
23
+ <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,700;12..96,800&family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
24
+ <link rel="stylesheet" href="../style.css">
25
+ <link rel="stylesheet" href="../docs.css">
26
+ <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%237c3aed'/><path d='M50 15C52 37 63 48 85 50C63 52 52 63 50 85C48 63 37 52 15 50C37 48 48 37 50 15Z' fill='white'/></svg>">
27
+ </head>
28
+ <body>
29
+
30
+ <header class="nav scrolled" id="nav">
31
+ <div class="nav-inner">
32
+ <a href="../index.html" class="nav-logo"><span class="logo-wordmark">zubo</span></a>
33
+ <nav class="nav-links" id="nav-links">
34
+ <a href="../index.html#features">Features</a>
35
+ <a href="index.html" style="color:#fff;">Docs</a>
36
+ <a href="../skills.html">Skills</a>
37
+ <a href="../index.html#get-started">Get Started</a>
38
+ </nav>
39
+ <div class="nav-right">
40
+ <a href="https://github.com/apwn/zubo" class="nav-github" aria-label="GitHub"><svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg></a>
41
+ <a href="../index.html#get-started" class="btn btn-primary btn-nav">Get Started</a>
42
+ <button class="nav-toggle" id="nav-toggle" aria-label="Toggle menu"><span></span><span></span><span></span></button>
43
+ </div>
44
+ </div>
45
+ </header>
46
+
47
+ <div class="docs-layout">
48
+ <aside class="docs-sidebar" id="docs-sidebar">
49
+ <div class="docs-sidebar-section">
50
+ <div class="docs-sidebar-heading">Getting Started</div>
51
+ <div class="docs-sidebar-links">
52
+ <a href="index.html">Overview</a>
53
+ <a href="config.html">Configuration</a>
54
+ </div>
55
+ </div>
56
+ <div class="docs-sidebar-section">
57
+ <div class="docs-sidebar-heading">Core Concepts</div>
58
+ <div class="docs-sidebar-links">
59
+ <a href="agents.html" class="active">Agents &amp; Workflows</a>
60
+ <a href="memory.html">Memory System</a>
61
+ <a href="skills.html">Skills</a>
62
+ </div>
63
+ </div>
64
+ <div class="docs-sidebar-section">
65
+ <div class="docs-sidebar-heading">Guides</div>
66
+ <div class="docs-sidebar-links">
67
+ <a href="channels.html">Channel Setup</a>
68
+ <a href="integrations.html">Integrations</a>
69
+ <a href="security.html">Security &amp; Auth</a>
70
+ </div>
71
+ </div>
72
+ <div class="docs-sidebar-section">
73
+ <div class="docs-sidebar-heading">Reference</div>
74
+ <div class="docs-sidebar-links">
75
+ <a href="api.html">API Reference</a>
76
+ <a href="cli.html">CLI Commands</a>
77
+ </div>
78
+ </div>
79
+ </aside>
80
+
81
+ <main class="docs-content">
82
+ <div class="docs-breadcrumb"><a href="../index.html">Home</a><span>/</span><a href="index.html">Docs</a><span>/</span>Agents &amp; Workflows</div>
83
+
84
+ <h1>Agents &amp; Workflows</h1>
85
+ <p>Zubo supports custom sub-agents, multi-agent delegation, structured workflows, and agent teams. This allows you to create specialized agents for specific tasks and orchestrate them together into powerful, composable pipelines that go far beyond what a single agent can accomplish on its own.</p>
86
+
87
+ <h2>The Default Agent</h2>
88
+ <p>By default, Zubo operates as a single agent that handles all messages across every connected channel using a unified session identified as "owner." This default agent has access to all registered tools &mdash; both built-in tools and any user-installed skills &mdash; and its personality and behavior are defined by the system prompt stored at <code>~/.zubo/workspace/SYSTEM.md</code>.</p>
89
+ <p>For many use cases, the default agent is all you need. It can search the web, manage your calendar, write code, read and write memory, and use any skill you install. Custom agents become valuable when you want to restrict tool access, provide specialized instructions, or build multi-step workflows.</p>
90
+
91
+ <h2>Custom System Prompt</h2>
92
+ <p>The system prompt defines your agent's personality, rules, and background knowledge. There are two ways to customize it:</p>
93
+ <ul>
94
+ <li><strong>Edit the file directly</strong> &mdash; Open <code>~/.zubo/workspace/SYSTEM.md</code> in any text editor and modify it.</li>
95
+ <li><strong>Use the dashboard</strong> &mdash; Navigate to the System Prompt panel in the web dashboard and edit it there. Changes are saved to <code>SYSTEM.md</code> automatically.</li>
96
+ </ul>
97
+ <p>Here is an example <code>SYSTEM.md</code> that defines a personalized assistant:</p>
98
+ <pre><code># System Prompt
99
+
100
+ You are Zubo, a personal AI assistant for Thomas.
101
+
102
+ ## Personality
103
+ - Friendly but concise. Avoid unnecessary filler.
104
+ - Use a professional tone for work topics, casual for personal.
105
+ - When unsure, ask clarifying questions rather than guessing.
106
+
107
+ ## Rules
108
+ - Always check memory before answering personal questions.
109
+ - Never share API keys, passwords, or sensitive data in chat.
110
+ - Prefer short answers unless the user asks for detail.
111
+
112
+ ## Context
113
+ - Thomas is a software engineer working on a Rust project called "relay."
114
+ - His timezone is America/New_York.
115
+ - He prefers metric units and Markdown formatting.</code></pre>
116
+ <p>The system prompt is loaded fresh on every message, so changes take effect immediately without restarting Zubo.</p>
117
+
118
+ <h2>Creating Custom Agents</h2>
119
+ <p>Custom agents are defined as directories inside <code>~/.zubo/workspace/agents/</code>. Each directory contains a single <code>AGENT.md</code> file that specifies the agent's name, description, system prompt, and allowed tools.</p>
120
+ <p>Here is an example <code>AGENT.md</code> for a research specialist:</p>
121
+ <pre><code># research_agent
122
+ A specialized agent for web research and summarization.
123
+
124
+ ## System Prompt
125
+ You are a research specialist. Focus on finding accurate, up-to-date
126
+ information from reliable sources. Always cite your sources and provide
127
+ concise summaries. When researching a topic, search from multiple angles
128
+ to ensure comprehensive coverage.
129
+
130
+ ## Tools
131
+ - web_search
132
+ - url_fetch
133
+ - memory_write</code></pre>
134
+ <p>There are three ways to create a custom agent:</p>
135
+ <ul>
136
+ <li><strong>Manually</strong> &mdash; Create the directory and <code>AGENT.md</code> file yourself at <code>~/.zubo/workspace/agents/research_agent/AGENT.md</code>.</li>
137
+ <li><strong>Conversationally</strong> &mdash; Tell Zubo: "Create an agent called research_agent that specializes in web research and has access to web_search, url_fetch, and memory_write." Zubo will generate the <code>AGENT.md</code> for you.</li>
138
+ <li><strong>Programmatically</strong> &mdash; Use the <code>manage_agents</code> tool to create, update, list, or delete agents.</li>
139
+ </ul>
140
+ <p>Agents have restricted tool access &mdash; they can only use the tools explicitly listed in their <code>## Tools</code> section. This is a key security and reliability feature: a research agent does not need access to your calendar, and a writing agent does not need access to the shell.</p>
141
+
142
+ <h3>Agent Fields</h3>
143
+ <table>
144
+ <thead><tr><th>Field</th><th>Required</th><th>Description</th></tr></thead>
145
+ <tbody>
146
+ <tr><td><code>Name (H1)</code></td><td>Yes</td><td>Lowercase with underscores, e.g. <code>research_agent</code>. Used as the agent identifier.</td></tr>
147
+ <tr><td><code>Description</code></td><td>Yes</td><td>Free-text between the H1 heading and the first H2. Describes what the agent does.</td></tr>
148
+ <tr><td><code>System Prompt</code></td><td>Yes</td><td>Content under the <code>## System Prompt</code> heading. Defines the agent's behavior and personality.</td></tr>
149
+ <tr><td><code>Tools</code></td><td>Yes</td><td>Bullet list under the <code>## Tools</code> heading. Each item is the name of a registered tool or skill.</td></tr>
150
+ </tbody>
151
+ </table>
152
+
153
+ <h2>Sub-Agent Delegation</h2>
154
+ <p>The main agent can delegate tasks to sub-agents using the built-in <code>delegate</code> tool. When a task is delegated, the sub-agent runs with its own system prompt and restricted tool set, processes the task, and returns a result to the main agent.</p>
155
+ <p>Key rules for delegation:</p>
156
+ <ul>
157
+ <li><strong>Maximum delegation depth: 2</strong> &mdash; This prevents infinite recursion. The main agent (depth 0) can delegate to a sub-agent (depth 1), which can delegate once more (depth 2), but no further.</li>
158
+ <li><strong>Sub-agents cannot delegate further or access the <code>manage_agents</code> or <code>delegate</code> tools</strong> &mdash; These tools are automatically stripped from sub-agent tool lists to prevent abuse.</li>
159
+ <li><strong>Each delegation creates a separate session</strong> &mdash; This provides context isolation. The sub-agent's conversation history does not bleed into the main agent's context.</li>
160
+ <li><strong>Memory is shared</strong> &mdash; Sub-agents can search and write to the same memory store as the main agent, so research findings and facts persist across delegations.</li>
161
+ </ul>
162
+ <p>Here is an example of how delegation works in practice:</p>
163
+ <pre><code>User: "Research the latest AI news and summarize it"
164
+
165
+ Zubo (main agent):
166
+ [Decides this is a research task, delegates to research_agent]
167
+
168
+ research_agent:
169
+ [Uses web_search to find recent AI articles]
170
+ [Uses url_fetch to read the top 3 articles]
171
+ [Uses memory_write to save key findings]
172
+ Returns: "Here's a summary of today's AI news:
173
+ 1. OpenAI announced GPT-5 with improved reasoning...
174
+ 2. Google DeepMind published new results on...
175
+ 3. Meta released an open-source model that..."
176
+
177
+ Zubo (main agent):
178
+ "Based on the research, here's what's happening in AI today:
179
+ [Formats and presents the research_agent's findings]"</code></pre>
180
+ <p>The user sees only the final response from the main agent. The delegation is transparent unless you inspect the logs in the dashboard.</p>
181
+
182
+ <h2>Workflows</h2>
183
+ <p>Workflows let you chain multiple agents together in a structured, multi-step pipeline. Each step defines a task, the agent that should handle it, and its dependencies on other steps. Zubo executes steps in dependency order using topological sorting, and independent steps run in parallel.</p>
184
+ <p>Workflows are defined as <code>WORKFLOW.md</code> files inside <code>~/.zubo/workspace/workflows/</code>. Here is an example:</p>
185
+ <pre><code># content_pipeline
186
+ A workflow that researches, writes, and reviews content.
187
+
188
+ ## Agents
189
+ - research_agent
190
+ - writer_agent
191
+ - reviewer_agent
192
+
193
+ ## Steps
194
+ ### research
195
+ - agent: research_agent
196
+ - task: Research the topic: $input
197
+
198
+ ### write
199
+ - agent: writer_agent
200
+ - task: Write an article based on this research: $research
201
+ - dependsOn: research
202
+
203
+ ### review
204
+ - agent: reviewer_agent
205
+ - task: Review and improve this article: $write
206
+ - dependsOn: write</code></pre>
207
+ <p>In this example, the <code>research</code> step runs first. Once it completes, its output is passed to the <code>write</code> step via the <code>$research</code> variable. After writing is complete, the <code>review</code> step receives the article via <code>$write</code> and produces the final output.</p>
208
+
209
+ <h3>Running a Workflow</h3>
210
+ <p>There are two ways to trigger a workflow:</p>
211
+ <ul>
212
+ <li><strong>Conversationally</strong> &mdash; Tell Zubo: "Run the content_pipeline workflow with input: AI trends in 2025"</li>
213
+ <li><strong>Programmatically</strong> &mdash; Use the <code>run_workflow</code> tool with the workflow name and input string.</li>
214
+ </ul>
215
+
216
+ <h3>Variables</h3>
217
+ <p>Workflows use a simple variable system to pass data between steps:</p>
218
+ <ul>
219
+ <li><code>$input</code> &mdash; The original input string provided when the workflow was triggered.</li>
220
+ <li><code>$stepName</code> &mdash; The output of a previously completed step. For example, <code>$research</code> contains the output of the <code>research</code> step.</li>
221
+ </ul>
222
+
223
+ <h3>Execution Details</h3>
224
+ <ul>
225
+ <li>Steps are executed in topological order based on their <code>dependsOn</code> declarations.</li>
226
+ <li>Steps with no dependencies (or whose dependencies are already satisfied) run in parallel.</li>
227
+ <li>Each step has a maximum of <strong>8 agent rounds</strong> to complete its task.</li>
228
+ <li>Execution is logged in the database in the <code>workflow_executions</code> and <code>workflow_step_logs</code> tables for auditing and debugging.</li>
229
+ </ul>
230
+
231
+ <h3>Workflow Step Fields</h3>
232
+ <table>
233
+ <thead><tr><th>Field</th><th>Required</th><th>Description</th></tr></thead>
234
+ <tbody>
235
+ <tr><td><code>Step name (H3)</code></td><td>Yes</td><td>Unique step identifier, used as a variable name for downstream steps.</td></tr>
236
+ <tr><td><code>agent</code></td><td>No</td><td>The agent to delegate this step to. If omitted, the main agent handles the step.</td></tr>
237
+ <tr><td><code>task</code></td><td>Yes</td><td>Natural language description of what this step should accomplish. Supports variable interpolation.</td></tr>
238
+ <tr><td><code>dependsOn</code></td><td>No</td><td>Name of a step (or comma-separated list of steps) that must complete before this step can start.</td></tr>
239
+ <tr><td><code>output</code></td><td>No</td><td>Custom variable name for this step's output. Defaults to the step name.</td></tr>
240
+ </tbody>
241
+ </table>
242
+
243
+ <h2>Agent Teams</h2>
244
+ <p>Teams provide a way to group related agents and associate them with a default workflow. They are defined as <code>TEAM.md</code> files inside <code>~/.zubo/workspace/teams/</code>.</p>
245
+ <pre><code># content_team
246
+ A team for content creation workflows.
247
+
248
+ ## Agents
249
+ - research_agent
250
+ - writer_agent
251
+ - reviewer_agent
252
+
253
+ ## Default Workflow
254
+ content_pipeline</code></pre>
255
+ <p>Teams serve as an organizational layer:</p>
256
+ <ul>
257
+ <li>They group agents that work together on related tasks.</li>
258
+ <li>They associate a default workflow that is triggered when the team is invoked.</li>
259
+ <li>They can be created and managed using the <code>manage_teams</code> tool or by asking Zubo conversationally.</li>
260
+ </ul>
261
+ <p>When you tell Zubo "use the content team to write about AI trends," it automatically activates the team's default workflow with your input.</p>
262
+
263
+ <h2>Best Practices</h2>
264
+ <ul>
265
+ <li><strong>Keep agents focused</strong> &mdash; Each agent should have a clear, narrow purpose. A "research_agent" that also edits code and manages calendars is doing too much.</li>
266
+ <li><strong>Limit tools per agent</strong> &mdash; Only give agents the tools they actually need. Fewer tools means less confusion for the LLM and fewer potential failure modes.</li>
267
+ <li><strong>Use workflows for multi-step processes</strong> &mdash; Rather than asking one agent to research, write, and review in a single turn, break it into a workflow with specialized agents for each step.</li>
268
+ <li><strong>Write clear system prompts</strong> &mdash; The more specific your agent's system prompt, the better it performs. Include examples of desired output format, tone, and behavior.</li>
269
+ <li><strong>Test agents individually</strong> &mdash; Before combining agents in a workflow, test each one in isolation to make sure it handles its task well.</li>
270
+ <li><strong>Don't over-engineer</strong> &mdash; The default agent handles most tasks well on its own. Only create custom agents when you have a genuine need for specialization, restricted tool access, or multi-step orchestration.</li>
271
+ </ul>
272
+
273
+ <div class="docs-page-nav">
274
+ <a href="config.html"><span class="nav-dir">Previous</span><span class="nav-label">&larr; Configuration</span></a>
275
+ <a href="memory.html"><span class="nav-dir">Next</span><span class="nav-label">Memory System &rarr;</span></a>
276
+ </div>
277
+ </main>
278
+ </div>
279
+
280
+ <button class="docs-sidebar-toggle" id="docs-sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
281
+ <script src="../script.js"></script>
282
+ <script type="application/ld+json">
283
+ {
284
+ "@context": "https://schema.org",
285
+ "@type": "BreadcrumbList",
286
+ "itemListElement": [
287
+ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zubo.bot/" },
288
+ { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://zubo.bot/docs/" },
289
+ { "@type": "ListItem", "position": 3, "name": "Agents & Workflows", "item": "https://zubo.bot/docs/agents.html" }
290
+ ]
291
+ }
292
+ </script>
293
+ </body>
294
+ </html>