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/site/docs/index.html ADDED
@@ -0,0 +1,433 @@
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>Getting Started — Zubo Docs</title>
7
+ <meta name="description" content="Get started with Zubo, a self-hosted AI agent with persistent semantic memory, multi-channel presence, 35+ tools, sub-agent delegation, and workflow automation.">
8
+ <meta name="theme-color" content="#060608">
9
+ <link rel="canonical" href="https://zubo.bot/docs/">
10
+ <meta property="og:title" content="Getting Started — Zubo Docs">
11
+ <meta property="og:description" content="Get started with Zubo, a self-hosted AI agent with persistent semantic memory, multi-channel presence, 35+ tools, sub-agent delegation, and workflow automation.">
12
+ <meta property="og:type" content="article">
13
+ <meta property="og:url" content="https://zubo.bot/docs/">
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="Getting Started — Zubo Docs">
18
+ <meta name="twitter:description" content="Get started with Zubo, a self-hosted AI agent with persistent semantic memory, 35+ tools, and workflow automation.">
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
+ <header class="nav scrolled" id="nav">
30
+ <div class="nav-inner">
31
+ <a href="../index.html" class="nav-logo"><span class="logo-wordmark">zubo</span></a>
32
+ <nav class="nav-links" id="nav-links">
33
+ <a href="../index.html#features">Features</a>
34
+ <a href="index.html" style="color:#fff;">Docs</a>
35
+ <a href="../skills.html">Skills</a>
36
+ <a href="../index.html#get-started">Get Started</a>
37
+ </nav>
38
+ <div class="nav-right">
39
+ <a href="https://github.com/apwn/zubo" class="nav-github" aria-label="GitHub">
40
+ <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>
41
+ </a>
42
+ <a href="../index.html#get-started" class="btn btn-primary btn-nav">Get Started</a>
43
+ <button class="nav-toggle" id="nav-toggle" aria-label="Toggle menu"><span></span><span></span><span></span></button>
44
+ </div>
45
+ </div>
46
+ </header>
47
+
48
+ <div class="docs-layout">
49
+ <aside class="docs-sidebar" id="docs-sidebar">
50
+ <div class="docs-sidebar-section">
51
+ <div class="docs-sidebar-heading">Getting Started</div>
52
+ <div class="docs-sidebar-links">
53
+ <a href="index.html" class="active">Overview</a>
54
+ <a href="config.html">Configuration</a>
55
+ </div>
56
+ </div>
57
+ <div class="docs-sidebar-section">
58
+ <div class="docs-sidebar-heading">Core Concepts</div>
59
+ <div class="docs-sidebar-links">
60
+ <a href="agents.html">Agents &amp; Workflows</a>
61
+ <a href="memory.html">Memory System</a>
62
+ <a href="skills.html">Skills</a>
63
+ </div>
64
+ </div>
65
+ <div class="docs-sidebar-section">
66
+ <div class="docs-sidebar-heading">Guides</div>
67
+ <div class="docs-sidebar-links">
68
+ <a href="channels.html">Channel Setup</a>
69
+ <a href="integrations.html">Integrations</a>
70
+ <a href="security.html">Security &amp; Auth</a>
71
+ </div>
72
+ </div>
73
+ <div class="docs-sidebar-section">
74
+ <div class="docs-sidebar-heading">Reference</div>
75
+ <div class="docs-sidebar-links">
76
+ <a href="api.html">API Reference</a>
77
+ <a href="cli.html">CLI Commands</a>
78
+ </div>
79
+ </div>
80
+ </aside>
81
+ <main class="docs-content">
82
+
83
+ <div class="docs-breadcrumb">
84
+ <a href="../index.html">Home</a> <span>/</span> <span>Docs</span>
85
+ </div>
86
+
87
+ <h1>Getting Started with Zubo</h1>
88
+
89
+ <p>
90
+ Zubo is a self-hosted AI agent with persistent semantic memory, multi-channel presence across Telegram, Discord, Slack, WhatsApp, Signal, and Web Chat, over 35 smart built-in tools, sub-agent delegation, and workflow automation. It runs entirely on your machine &mdash; your data never leaves your infrastructure. Whether you need a personal assistant that remembers everything, an automation hub that connects your services, or an AI copilot embedded in every chat platform you use, Zubo handles it from a single process with a single configuration file.
91
+ </p>
92
+
93
+ <!-- ================================================================ -->
94
+ <h2 id="features">Features</h2>
95
+
96
+ <h3>AI Engine</h3>
97
+ <ul>
98
+ <li><strong>Multi-provider LLM support</strong> &mdash; Claude (Anthropic), OpenAI (GPT-4o, GPT-4-turbo), Google Gemini, Ollama (local models), Groq (fast inference), Together (open models), OpenRouter (multi-model gateway), DeepSeek, xAI (Grok), Fireworks, LM Studio (local GUI), and any OpenAI-compatible endpoint. Switch providers with a single config change.</li>
99
+ <li><strong>Smart routing</strong> &mdash; automatically routes simple queries to fast, cheap models and complex queries to more capable ones. Saves cost without sacrificing quality, with full manual override when you need it.</li>
100
+ <li><strong>Automatic failover</strong> &mdash; define an ordered list of backup providers. If the primary is down or rate-limited, Zubo seamlessly falls through to the next provider in the chain with no user-facing interruption.</li>
101
+ <li><strong>Streaming responses</strong> &mdash; token-by-token streaming for all providers that support it. Messages appear in real time across every channel.</li>
102
+ <li><strong>Context compaction</strong> &mdash; when the conversation approaches the context window limit, Zubo automatically summarizes older turns to free space while preserving critical details.</li>
103
+ <li><strong>200k token context</strong> &mdash; supports the full 200,000 token context window on Claude models, with configurable context windows per provider.</li>
104
+ </ul>
105
+
106
+ <h3>Channels</h3>
107
+ <ul>
108
+ <li><strong>Telegram</strong> &mdash; full bot API integration with user allow-listing by numeric Telegram ID.</li>
109
+ <li><strong>Discord</strong> &mdash; bot presence in servers and DMs, with user allow-listing by Discord user ID.</li>
110
+ <li><strong>Slack</strong> &mdash; app-level integration using Bot Token and App Token, with user allow-listing by Slack member ID.</li>
111
+ <li><strong>WhatsApp</strong> &mdash; via the WhatsApp Web multi-device API, with phone number allow-listing.</li>
112
+ <li><strong>Signal</strong> &mdash; via signal-cli, with phone number allow-listing.</li>
113
+ <li><strong>Web Chat</strong> &mdash; built-in web dashboard with real-time chat, served on a configurable port.</li>
114
+ <li>All channels share the same memory, personality, tools, and conversation history. A fact learned in Telegram is immediately available in Discord.</li>
115
+ </ul>
116
+
117
+ <h3>Memory</h3>
118
+ <ul>
119
+ <li><strong>Persistent semantic memory</strong> with vector embeddings powered by all-MiniLM-L6-v2 (384 dimensions), running locally via ONNX Runtime with zero external API calls.</li>
120
+ <li><strong>Full-text search</strong> using SQLite FTS5 with BM25 ranking for keyword-based retrieval.</li>
121
+ <li><strong>Hybrid search</strong> that combines 60% vector similarity (cosine) with 40% FTS5 BM25 scoring for best-of-both-worlds recall.</li>
122
+ <li><strong>Automatic chunking with overlap</strong> for long documents, ensuring context is preserved across chunk boundaries.</li>
123
+ <li><strong>Document ingestion</strong> supporting PDF, DOCX, TXT, CSV, JSON, YAML, and common code file formats. Upload a document and Zubo indexes it into searchable memory automatically.</li>
124
+ </ul>
125
+
126
+ <h3>Tools</h3>
127
+ <ul>
128
+ <li><strong>35+ built-in tools</strong> including shell command execution, file I/O (read, write, list, search), web search (DuckDuckGo, Brave, Google), HTTP requests, memory read/write/search, secrets management, and cron job scheduling.</li>
129
+ <li>Tools are permission-gated with three levels: <code>safe</code>, <code>sensitive</code>, and <code>dangerous</code>. Dangerous operations require explicit confirmation tokens.</li>
130
+ </ul>
131
+
132
+ <h3>Skills</h3>
133
+ <ul>
134
+ <li><strong>Extensible single-file TypeScript skills</strong> that you can write, install, or share. Each skill is a self-contained <code>.ts</code> file with a manifest header.</li>
135
+ <li><strong>Hot-reload without restart</strong> &mdash; drop a skill file into <code>~/.zubo/workspace/skills/</code> and it becomes available immediately.</li>
136
+ <li><strong>Community skill registry</strong> for discovering and installing skills built by others.</li>
137
+ <li><strong>Skill sandboxing</strong> &mdash; user-installed skills run in isolated subprocesses with configurable timeouts, preventing runaway code from affecting the main process.</li>
138
+ </ul>
139
+
140
+ <h3>Agents</h3>
141
+ <ul>
142
+ <li><strong>Custom sub-agents</strong> with focused system prompts, restricted tool access, and specialized behavior. Define a &ldquo;code-reviewer&rdquo; agent that only has access to file and git tools, or a &ldquo;researcher&rdquo; agent that only has web search.</li>
143
+ <li><strong>2-level delegation</strong> &mdash; the main agent can delegate tasks to sub-agents, which can in turn delegate to their own sub-agents, up to two levels deep.</li>
144
+ </ul>
145
+
146
+ <h3>Workflows</h3>
147
+ <ul>
148
+ <li><strong>Multi-agent pipelines</strong> with dependency resolution, parallel execution of independent steps, and variable passing between stages.</li>
149
+ <li>Define workflows as JSON or YAML in <code>~/.zubo/workspace/workflows/</code> and trigger them by name or on a schedule.</li>
150
+ </ul>
151
+
152
+ <h3>Integrations</h3>
153
+ <ul>
154
+ <li><strong>GitHub</strong> &mdash; repositories, issues, pull requests, code search, commit history.</li>
155
+ <li><strong>Google</strong> &mdash; Calendar (read/write events), Gmail (read/send), Sheets (read/write), Docs (read), Drive (list/search/download).</li>
156
+ <li><strong>Notion</strong> &mdash; pages, databases, blocks.</li>
157
+ <li><strong>Linear</strong> &mdash; issues, projects, teams.</li>
158
+ <li><strong>Jira</strong> &mdash; issues, projects, sprints.</li>
159
+ <li><strong>Slack</strong> &mdash; channels, messages, users (beyond the chat channel).</li>
160
+ <li><strong>Twitter</strong> &mdash; post tweets, read timelines.</li>
161
+ </ul>
162
+
163
+ <h3>Scheduling</h3>
164
+ <ul>
165
+ <li><strong>Natural language scheduling</strong> &mdash; describe schedules in plain English like &ldquo;every weekday at 9am&rdquo; or &ldquo;twice a day&rdquo;. Zubo parses natural language into cron expressions automatically.</li>
166
+ <li><strong>Cron jobs</strong> supporting any standard cron expression (e.g., <code>0 9 * * 1-5</code> for weekday mornings).</li>
167
+ <li><strong>Configurable heartbeat</strong> from 1 to 1440 minutes (default 30), where Zubo wakes up, checks for pending tasks, processes scheduled jobs, and optionally sends proactive messages.</li>
168
+ <li><strong>Proactive memory-based triggers</strong> &mdash; Zubo can surface reminders and follow-ups based on things it has remembered.</li>
169
+ <li><strong>Morning briefing</strong> &mdash; a built-in scheduled task that summarizes your calendar, pending tasks, and unread messages each morning.</li>
170
+ </ul>
171
+
172
+ <h3>Voice</h3>
173
+ <ul>
174
+ <li><strong>Speech-to-text</strong> via OpenAI Whisper for transcribing voice messages received on any channel.</li>
175
+ <li><strong>Text-to-speech</strong> via OpenAI (voices: alloy, echo, fable, onyx, nova, shimmer) or ElevenLabs for generating spoken responses.</li>
176
+ </ul>
177
+
178
+ <h3>Dashboard</h3>
179
+ <ul>
180
+ <li><strong>Built-in web UI</strong> served as zero-dependency inline HTML on the configured port. No build step, no npm dependencies, no CDN calls.</li>
181
+ <li>Includes real-time chat, analytics (token usage, tool calls, response times), memory browser with search, skill manager (install, enable, disable, delete), settings editor, and full data export/import.</li>
182
+ </ul>
183
+
184
+ <h3>Budget &amp; Cost Controls</h3>
185
+ <ul>
186
+ <li><strong>Spending limits</strong> &mdash; set daily or monthly budgets per provider or globally. Zubo pauses requests when limits are reached, preventing surprise bills.</li>
187
+ <li><strong>Per-model cost tracking</strong> &mdash; view token usage and costs broken down by model in the dashboard. Full transparency into where your money goes.</li>
188
+ </ul>
189
+
190
+ <h3>Security</h3>
191
+ <ul>
192
+ <li><strong>API key authentication</strong> with Bearer tokens for all HTTP endpoints.</li>
193
+ <li><strong>Tool permission levels</strong> (safe, sensitive, dangerous) with confirmation tokens for destructive operations.</li>
194
+ <li><strong>Rate limiting</strong> per IP with configurable thresholds for chat and upload endpoints.</li>
195
+ <li><strong>File access restrictions</strong> preventing traversal outside the workspace directory.</li>
196
+ <li><strong>Shell command filtering</strong> blocking known-dangerous commands and patterns.</li>
197
+ <li><strong>Private IP blocking</strong> preventing SSRF attacks by blocking requests to internal network addresses.</li>
198
+ </ul>
199
+
200
+ <!-- ================================================================ -->
201
+ <h2 id="installation">Installation</h2>
202
+
203
+ <p>Zubo requires <strong>Bun v1.0+</strong> as its runtime. If you do not have Bun installed, visit <a href="https://bun.sh" target="_blank" rel="noopener">bun.sh</a> and run the one-line installer.</p>
204
+
205
+ <h3>Step 1: Install Zubo</h3>
206
+
207
+ <p>Install Zubo globally using Bun (recommended) or npm:</p>
208
+
209
+ <pre><code># Using Bun (recommended)
210
+ bun add -g zubo
211
+
212
+ # Or using npm
213
+ npm i -g zubo</code></pre>
214
+
215
+ <p>This places the <code>zubo</code> binary on your PATH, making it available from any terminal session.</p>
216
+
217
+ <h3>Step 2: Run the Setup Wizard</h3>
218
+
219
+ <pre><code>zubo setup</code></pre>
220
+
221
+ <p>The interactive setup wizard walks you through initial configuration. It will:</p>
222
+ <ul>
223
+ <li>Create the <code>~/.zubo</code> directory and all required subdirectories.</li>
224
+ <li>Prompt you to select a primary LLM provider and enter your API key.</li>
225
+ <li>Optionally configure one or more chat channels (Telegram, Discord, etc.).</li>
226
+ <li>Generate the <code>~/.zubo/config.json</code> file with your choices.</li>
227
+ <li>Download the all-MiniLM-L6-v2 embedding model (~80 MB) for local semantic memory.</li>
228
+ <li>Create a default <code>SYSTEM.md</code> system prompt that you can customize later.</li>
229
+ </ul>
230
+
231
+ <h3>Step 3: Start Zubo</h3>
232
+
233
+ <pre><code># Start in foreground (logs to stdout)
234
+ zubo start
235
+
236
+ # Start as a background daemon
237
+ zubo start --daemon</code></pre>
238
+
239
+ <p>When started, Zubo initializes the SQLite database, loads the embedding model, connects to all enabled channels, and starts the heartbeat scheduler. The web dashboard opens automatically in your default browser at <code>http://localhost:3000</code> (or your configured port). When running with <code>--daemon</code>, Zubo writes its PID to <code>~/.zubo/zubo.pid</code> and logs to <code>~/.zubo/logs/zubo.log</code>.</p>
240
+
241
+ <!-- ================================================================ -->
242
+ <h2 id="architecture">Architecture</h2>
243
+
244
+ <p>Zubo is a single-process application built around an event-driven agent loop. Here is a simplified view of how a message flows through the system:</p>
245
+
246
+ <pre><code> +---------------------+
247
+ | User Message |
248
+ +----------+----------+
249
+ |
250
+ +----------v----------+
251
+ | Channel Adapter |
252
+ | (Telegram, Discord, |
253
+ | Slack, WhatsApp, |
254
+ | Signal, Web Chat) |
255
+ +----------+----------+
256
+ |
257
+ +----------v----------+
258
+ | Router |
259
+ | (auth, rate limit, |
260
+ | session lookup) |
261
+ +----------+----------+
262
+ |
263
+ +----------v----------+
264
+ | Agent Loop |
265
+ | |
266
+ | +------+ +-------+ |
267
+ | |Tools | |Memory | |
268
+ | +------+ +-------+ |
269
+ | +------+ +-------+ |
270
+ | |Skills| |Agents | |
271
+ | +------+ +-------+ |
272
+ | +-----------+ |
273
+ | |Scheduler | |
274
+ | +-----------+ |
275
+ +----------+----------+
276
+ |
277
+ +----------v----------+
278
+ | LLM Provider |
279
+ | (Claude / OpenAI / |
280
+ | Ollama / Groq ...) |
281
+ +----------+----------+
282
+ |
283
+ +----------v----------+
284
+ | Response |
285
+ +----------+----------+
286
+ |
287
+ +----------v----------+
288
+ | Channel Adapter |
289
+ +----------+----------+
290
+ |
291
+ +----------v----------+
292
+ | User |
293
+ +---------------------+</code></pre>
294
+
295
+ <p>The <strong>Channel Adapter</strong> normalizes incoming messages from any platform into a unified internal format. The <strong>Router</strong> handles authentication, rate limiting, and session management. The <strong>Agent Loop</strong> is the core: it sends the conversation to the LLM, processes any tool calls the LLM requests, stores results in memory, and iterates until the LLM produces a final text response or the maximum turn count is reached. The response is then sent back through the Channel Adapter to the originating platform.</p>
296
+
297
+ <!-- ================================================================ -->
298
+ <h2 id="directory-structure">Directory Structure</h2>
299
+
300
+ <p>All Zubo data lives under a single home directory, defaulting to <code>~/.zubo</code>. You can override this with the <code>ZUBO_HOME</code> environment variable.</p>
301
+
302
+ <pre><code>~/.zubo/
303
+ ├── config.json # Main configuration file
304
+ ├── zubo.db # SQLite database (WAL mode)
305
+ ├── zubo.pid # Daemon PID file (created on --daemon)
306
+ ├── logs/
307
+ │ └── zubo.log # Application logs (rotated daily)
308
+ ├── sessions/
309
+ │ └── owner.jsonl # Conversation history (JSON Lines)
310
+ ├── models/
311
+ │ └── all-MiniLM-L6-v2/ # Embedding model (auto-downloaded on setup)
312
+ │ ├── model.onnx
313
+ │ ├── tokenizer.json
314
+ │ └── config.json
315
+ └── workspace/
316
+ ├── SYSTEM.md # Custom system prompt (editable)
317
+ ├── MEMORY.md # Persistent memory file
318
+ ├── memory/ # Dated memory files (YYYY-MM-DD.md)
319
+ ├── skills/ # User-installed skill files (.ts)
320
+ ├── agents/ # Custom agent definitions (.json)
321
+ ├── workflows/ # Workflow definitions (.json / .yaml)
322
+ ├── teams/ # Team definitions (.json)
323
+ ├── uploads/ # Uploaded and ingested documents
324
+ └── backups/ # Daily SQLite backups (zubo-YYYY-MM-DD.db)</code></pre>
325
+
326
+ <p>The <code>config.json</code> file is the single source of truth for all runtime configuration. The <code>zubo.db</code> SQLite database stores memory entries, embeddings, scheduled jobs, API keys, and analytics. Conversation history is stored as JSON Lines in the <code>sessions/</code> directory for easy inspection and export.</p>
327
+
328
+ <!-- ================================================================ -->
329
+ <h2 id="tech-stack">Tech Stack</h2>
330
+
331
+ <table>
332
+ <thead>
333
+ <tr>
334
+ <th>Component</th>
335
+ <th>Technology</th>
336
+ </tr>
337
+ </thead>
338
+ <tbody>
339
+ <tr>
340
+ <td>Runtime</td>
341
+ <td>Bun</td>
342
+ </tr>
343
+ <tr>
344
+ <td>Language</td>
345
+ <td>TypeScript</td>
346
+ </tr>
347
+ <tr>
348
+ <td>Database</td>
349
+ <td>SQLite via <code>bun:sqlite</code> (WAL mode for concurrent reads)</td>
350
+ </tr>
351
+ <tr>
352
+ <td>Embeddings</td>
353
+ <td>ONNX Runtime with all-MiniLM-L6-v2 (384 dimensions, ~80 MB)</td>
354
+ </tr>
355
+ <tr>
356
+ <td>Search</td>
357
+ <td>Hybrid: FTS5 BM25 (40%) + cosine vector similarity (60%)</td>
358
+ </tr>
359
+ <tr>
360
+ <td>Dashboard</td>
361
+ <td>Zero-dependency inline HTML (no build step, no CDN)</td>
362
+ </tr>
363
+ <tr>
364
+ <td>LLM SDK</td>
365
+ <td><code>@anthropic-ai/sdk</code> for Claude + OpenAI-compatible REST for all others</td>
366
+ </tr>
367
+ <tr>
368
+ <td>Channels</td>
369
+ <td>Native API clients per platform (grammy, discord.js, @slack/bolt, whatsapp-web.js, signal-cli)</td>
370
+ </tr>
371
+ <tr>
372
+ <td>Voice</td>
373
+ <td>OpenAI Whisper (STT), OpenAI TTS / ElevenLabs (TTS)</td>
374
+ </tr>
375
+ </tbody>
376
+ </table>
377
+
378
+ <!-- ================================================================ -->
379
+ <h2 id="best-practices">Best Practices</h2>
380
+
381
+ <ul>
382
+ <li><strong>Start with <code>zubo setup</code></strong> &mdash; let the interactive wizard configure everything. It handles directory creation, model downloading, and initial config generation so you do not have to do it manually.</li>
383
+ <li><strong>Write a custom system prompt</strong> in <code>~/.zubo/workspace/SYSTEM.md</code> to give your agent a distinct personality and context about you, your work, your preferences, and your tools. The more specific you are, the better Zubo serves you.</li>
384
+ <li><strong>Use the dashboard for day-to-day management</strong> (chatting, browsing memory, managing skills) and <strong>the CLI for automation</strong> (scripting, cron, CI/CD pipelines).</li>
385
+ <li><strong>Enable API authentication</strong> if you are exposing the web port beyond localhost: <code>zubo config set auth.enabled true</code>, then create an API key via the dashboard or <code>zubo auth create</code>.</li>
386
+ <li><strong>Set rate limits for production</strong> to prevent abuse: <code>zubo config set rateLimit.chatPerMinute 30</code>.</li>
387
+ <li><strong>Use <code>zubo start --daemon</code></strong> for always-on operation. Zubo writes a PID file and rotates logs automatically.</li>
388
+ <li><strong>Check <code>zubo status</code> and <code>zubo logs</code></strong> for troubleshooting. The status command shows uptime, memory usage, connected channels, and pending scheduled jobs.</li>
389
+ <li><strong>Back up your data</strong> with <code>zubo export</code> for a full JSON export, or rely on the automatic daily SQLite backups in <code>~/.zubo/workspace/backups/</code>.</li>
390
+ <li><strong>Enable smart routing</strong> to automatically send simple queries to fast, cheap models. Set <code>smartRouting.enabled</code> to <code>true</code> and configure a <code>fastProvider</code> (e.g., Groq) alongside your primary. This can cut costs significantly.</li>
391
+ <li><strong>Set a budget</strong> to avoid surprise bills: <code>zubo config set budget.dailyLimit 5</code>. Cost tracking is always active in the dashboard under Analytics &rarr; Costs.</li>
392
+ <li><strong>Configure failover providers</strong> so your agent stays available even if your primary LLM provider has an outage. For example, set Anthropic as primary and Ollama as failover for fully offline operation when the cloud is down.</li>
393
+ <li><strong>Keep skills small and focused</strong> &mdash; one skill per task. This makes them easier to test, share, and debug.</li>
394
+ </ul>
395
+
396
+ <!-- ================================================================ -->
397
+ <h2 id="next-steps">Next Steps</h2>
398
+
399
+ <p>Now that you have Zubo installed and running, explore the rest of the documentation to unlock its full potential:</p>
400
+
401
+ <ul>
402
+ <li><a href="config.html"><strong>Configuration</strong></a> &mdash; deep dive into every configuration option: LLM providers, channels, voice, rate limiting, authentication, sandbox settings, and a complete annotated example.</li>
403
+ <li><a href="agents.html"><strong>Agents &amp; Workflows</strong></a> &mdash; learn how to create custom sub-agents with focused system prompts and restricted tools, and build multi-agent pipelines with dependency resolution and parallel execution.</li>
404
+ <li><a href="memory.html"><strong>Memory System</strong></a> &mdash; understand how semantic memory works, how to ingest documents, search your knowledge base, and tune the hybrid search weights.</li>
405
+ <li><a href="skills.html"><strong>Skills</strong></a> &mdash; write, install, and share single-file TypeScript skills. Learn the skill manifest format, the sandbox environment, and the community registry.</li>
406
+ <li><a href="channels.html"><strong>Channel Setup</strong></a> &mdash; step-by-step guides for configuring each channel: creating bots, obtaining tokens, setting up webhooks, and configuring allow-lists.</li>
407
+ <li><a href="integrations.html"><strong>Integrations</strong></a> &mdash; connect Zubo to GitHub, Google Workspace, Notion, Linear, Jira, and more. OAuth flows, API key setup, and usage examples.</li>
408
+ <li><a href="security.html"><strong>Security &amp; Auth</strong></a> &mdash; harden your Zubo instance: API key management, tool permission levels, confirmation tokens, rate limiting, file access restrictions, and network security.</li>
409
+ <li><a href="api.html"><strong>API Reference</strong></a> &mdash; complete HTTP API documentation for programmatic access: endpoints, request/response formats, authentication, and WebSocket streaming.</li>
410
+ <li><a href="cli.html"><strong>CLI Commands</strong></a> &mdash; full reference for every <code>zubo</code> CLI command: start, stop, status, config, auth, export, import, logs, and more.</li>
411
+ </ul>
412
+
413
+ <div class="docs-page-nav">
414
+ <div></div>
415
+ <a href="config.html"><span class="nav-dir">Next</span><span class="nav-label">Configuration &rarr;</span></a>
416
+ </div>
417
+
418
+ </main>
419
+ </div>
420
+ <button class="docs-sidebar-toggle" id="docs-sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
421
+ <script src="../script.js"></script>
422
+ <script type="application/ld+json">
423
+ {
424
+ "@context": "https://schema.org",
425
+ "@type": "BreadcrumbList",
426
+ "itemListElement": [
427
+ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zubo.bot/" },
428
+ { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://zubo.bot/docs/" }
429
+ ]
430
+ }
431
+ </script>
432
+ </body>
433
+ </html>