OpenBuddy

The open desktop AI workspace that you can actually read, fork, and own.

English · 简体中文

OpenBuddy is a WorkBuddy-style desktop AI workspace, rebuilt as 100% open source (MIT) on Electron + Pi. It ships the polished UI, plan mode, skills, MCP connectors, and an enterprise-grade Casdoor × NewAPI integration — every byte auditable, every provider BYOK.

Quick Start · Features · Architecture · Documentation · Contributing · Community

---

📑 Table of Contents

• Why OpenBuddy?
• ✨ Features
• 🎬 Demo & Screenshots
• ⚔️ OpenBuddy vs WorkBuddy
• 🚀 Quick Start
• 🏗️ Architecture
• 🧩 Capabilities
• 🛠️ Built With
• 📚 Documentation
• 🗺️ Roadmap
• 🤝 Contributing
• 🛡️ Security
• 🌍 Community
• ⭐ Star History
• 🙏 Acknowledgements
• 📄 License

---

💡 Why OpenBuddy?

Tencent WorkBuddy showed the world what a great desktop AI agent workspace should feel like — polished UI, plan mode, skills, MCP connectors. It's a genuinely capable product.

But it's closed-source, and your data flows through Tencent's backend.

OpenBuddy is the open answer — the same shape of experience, rebuilt from the ground up on Electron + Pi, with a Cordis capability mesh that any contributor can extend:

🔓	100% open source (MIT) No telemetry black box, no vendor lock-in. The whole repo is auditable.
⚡	Electron + Pi runtime One tested desktop host with a versioned preload bridge; the renderer only sees a typed API surface.
🔁	Restart-safe sessions Pi sessions, provider settings, capability state, and audit logs persist across renderer reloads and Electron restarts.
🤖	Pi as the agent runtime The in-process AgentSession owns prompts, tools, permissions, plans, tasks, and streaming events.
🌐	Truly cross-platform One codebase, Windows, macOS, and Linux. electron-builder produces signed installers for each.
🪐	moon DAG monorepo 66 projects (1 root + 1 Electron + 64 workspace packages), type-check/test/build incrementally. CI runs the same moon run commands you run locally.
🧩	Cordis capability mesh 59 workspace packages (5 capability, 8 collaboration, 26 UI, …) (@openbuddy/*) — skills, memory, plan, task, email, calendar, MCP, payment, SCIM, SAML… pick what you need.
🏢	Enterprise-ready Casdoor OIDC, NewAPI gateway, 4 payment channels, SCIM v2, SAML 2.0, transactional outbox webhooks, audit ledger — production-ready building blocks.

"If WorkBuddy is the polished product, OpenBuddy is the one you can actually read, fork, and own."

🌟 If this project matters to you, please give it a ⭐

It helps others discover OpenBuddy and keeps development moving.

---

✨ Features

Surface	Capabilities
🎨 Pixel-close WorkBuddy UI Ported --wb-* design tokens, full 207-icon foundation (all implemented, no stubs), brand atoms. It looks like WorkBuddy because the same atoms make it up. ⚙️ Pi, in-process @earendil-works/pi-coding-agent runs in Electron Main. Renderer code only sees the typed preload API; no Node or provider SDK is required in the UI. 🔌 Pi events as contract Streaming assistant deltas, tool calls, plan updates, permission requests, and completion events flow through cleanup-aware pi://* events.	🔑 BYOK, multi-provider Bring your own keys. Configure Anthropic, OpenAI-compatible, Pi, MiniMax, NewAPI, or custom providers in the local Pi/OpenBuddy data directory. 🧩 Extensible agent surface Skills — Pi skills and local skill catalogs MCP connectors — local connector roots + OAuth/auth status Experts / Assistants — local Pi/OpenBuddy agent files Plugins — loadable via the marketplace 🚀 Advanced workflows Plan mode (toggle & view) · Rewind (rewind & fork) · sub-agent Tasks (observe & cancel) · Slash Commands · local Automations scheduler. 📦 Cross-platform installers Windows (NSIS .exe + MSI), macOS (.dmg), Linux (AppImage + .deb). CI-built releases via GitHub Actions.
🏢 Enterprise integration Casdoor — OIDC SSO + tenant policy + audit log NewAPI — model aggregation gateway (BYOK + Service Token) Stripe / WeChat Pay / Alipay — 4 payment adapters SCIM v2 — RFC 7644 user/group provisioning SAML 2.0 — AuthnRequest/Response/LogoutRequest Transactional outbox — webhook delivery with exponential backoff	🧪 Battle-tested quality 309 test files across the monorepo (Vitest) Live integration tests against public Casdoor + NewAPI endpoints Closed-loop capability evals for end-to-end agent runs Type-safe IPC — every preload channel is allowlisted in electron/preload/index.ts Storage boundaries — automated architecture enforcement 🌍 Internationalization Full UI locale coverage via @openbuddy/ui-locale; ships English + 简体中文 out of the box. 🪟 Native desktop polish System tray, native notifications, deep links (casdoor://), clipboard integration, multi-window, autosave-on-quit.

---

🎬 Demo & Screenshots (all captured against the real MiniMax-M3 model)

Every AI chat screenshot below is from a real Electron build driven by the real MiniMax-M3 model at https://api.minimaxi.com/anthropic — not a mock, not a replay.

Reproduce locally:

pnpm build
OPENBUDDY_E2E_API_KEY="sk-cp-..." \
OPENBUDDY_E2E_BASE_URL="https://api.minimaxi.com/anthropic" \
OPENBUDDY_E2E_MODEL_ID="MiniMax-M3" \
node scripts/electron/_screenshot-real-ui.mjs

Offline fallback (local echo upstream, same Anthropic Messages wire format): node scripts/electron/launch-real-evals-echo.mjs

1. Cold start — no API key configured

2. Composer ready after configuring MiniMax

3. Real MiniMax-M3 streaming answer — mid-turn

4. Turn 1 settled

5. Turn 2 — multi-turn conversation

6. Turn 3 — structured output (Chinese to-do list)

7. Full three-turn transcript

Verification evidence (all passing)

• tests/electron/chat-ui-minimax-real.spec.ts — 6/6 pass (54.7s) against the real upstream
• tests/electron/minimax-real-roundtrip.spec.ts — 4/4 pass (46.1s), real agent:prompt / follow-up / abort / current-model IPC chain
• tests/electron/chat-flow-echo.spec.ts — 5/5 pass against the local echo upstream
• tests/electron/chat-ui-streaming.spec.ts — 7/7 pass, multi-turn / hidden window / reload / streaming
• tests/electron/chat-flow.spec.ts — 2/2 pass, cold-start composer-disabled surface
• tests/electron/session-history-load.spec.ts — 2/2 pass, persisted history replay

30-second tour — what you get

Architecture overview

Capability matrix

Data flow — prompt to tool result

WorkBuddy parity

Bilingual support

OpenBuddy ships with first-class bilingual UI: zh-CN (default) and en-US. Translations live as JSON dictionaries under packages/ui/openbuddy-ui-locale/src/dictionaries/. The locale persists in localStorage under openbuddy:locale and is hot-swappable at runtime via the LocaleService API — no renderer reload required for the active dictionary after the next navigation. See docs/I18N.md for the full workflow and how to add a third locale.

All primary documentation is shipped as separate files per language so contributors can edit them in parallel without merge churn:

Document	English	简体中文
Landing README	README.md	README.zh-CN.md
Codebase analysis	docs/CODEBASE_ANALYSIS.md	docs/CODEBASE_ANALYSIS.zh-CN.md
Docs index	docs/README.md	docs/README.zh-CN.md
Getting started	docs/GETTING_STARTED.md	docs/GETTING_STARTED.zh-CN.md
Architecture	docs/ARCHITECTURE.md	docs/ARCHITECTURE.zh-CN.md
FAQ	docs/FAQ.md	docs/FAQ.zh-CN.md
Performance	docs/PERFORMANCE.md	docs/PERFORMANCE.zh-CN.md
Contributing	CONTRIBUTING.md	CONTRIBUTING.zh-CN.md
Governance	GOVERNANCE.md	GOVERNANCE.zh-CN.md
Code of Conduct	CODE_OF_CONDUCT.md	CODE_OF_CONDUCT.zh-CN.md
Security	SECURITY.md	SECURITY.zh-CN.md
Support	SUPPORT.md	SUPPORT.zh-CN.md
Maintainers	MAINTAINERS.md	MAINTAINERS.zh-CN.md
Sponsors	SPONSORS.md	SPONSORS.zh-CN.md
Brand	BRAND.md	BRAND.zh-CN.md
Changelog	CHANGELOG.md	CHANGELOG.zh-CN.md
Roadmap / TODO	TODO.md	TODO.zh-CN.md

See docs/diagrams/ for the full set of system architecture diagrams in SVG / HTML format.

---

⚔️ OpenBuddy vs WorkBuddy

Only rows we can publicly substantiate — see docs/workbuddy-parity-matrix.md for the full matrix.

Capability	WorkBuddy	OpenBuddy
License	Closed-source	MIT (open)
Data path	Tencent backend	Local + your gateway
Plan mode	✅	✅
Skills	✅	✅ + open catalog
MCP connectors	✅	✅
Experts / Assistants	✅	✅ (local files)
Rewind & fork	✅	✅
Sub-agent Tasks	✅	✅
Automations	✅	✅ (local scheduler)
Slash commands	✅	✅
Local persistence	✅	✅ (restart-safe)
Provider choice	Limited	BYOK — Anthropic / OpenAI / NewAPI / custom
Casdoor OIDC	❌	✅
NewAPI gateway	❌	✅ (BYOK + Service Token)
SCIM v2	❌	✅ (RFC 7644)
SAML 2.0	❌	✅
Plugin SDK	Closed	Cordis open capability mesh
Tests visible to users	❌	309 test files in the repo
Cross-platform	Win / macOS	Win / macOS / Linux
Audit log	Backend	Local + Casdoor tenant ledger

---

🚀 Quick Start

Prerequisites

• Node.js 22+ (we use Node 22 features; see package.json packageManager)
• pnpm 10+ — npm install -g pnpm
• Git with submodule support
• (Optional) Platform build tools — see docs/release-ci.md

Install & Run (development)

# 1. Clone with submodules
git clone --recurse-submodules https://github.com/louloulin/OpenBuddy.git
cd OpenBuddy

# 2. Install deps (also runs `moon sync projects` automatically)
pnpm install

# 3. Start the dev shell — Electron host + Vite renderer + HMR
pnpm electron:dev
#   ↑ equivalent to:  moon run openbuddy:dev.electron

The first run takes ~30s for the Vite cold start. Subsequent restarts are sub-second thanks to moon's incremental DAG.

Build a production installer

# Windows installer (NSIS .exe + MSI)
pnpm electron:build:win

# macOS installer (DMG)
pnpm electron:build:mac

# Linux AppImage / .deb
pnpm electron:build:linux

# All three
pnpm electron:build:all

Verify your environment

# Type-check the entire 32-project monorepo
pnpm workspace:typecheck

# Run the full Vitest suite (309 test files)
pnpm workspace:test

# Closed-loop capability evaluation (real agent run + scoring)
pnpm test:closed-loop

Need a deeper walkthrough? Head to docs/GETTING_STARTED.md.

---

🏗️ Architecture

OpenBuddy is a three-layer Electron app with a Cordis capability mesh under the hood:

┌──────────────────────────────────────────────────────────────┐
│  React Renderer (src/, packages/ui/*)                        │
│    Vite + React 18 + Zustand stores                          │
│    Foundation: --wb-* tokens, 207-icon set, brand atoms      │
└──────────────────────┬───────────────────────────────────────┘
                       │ window.api (typed contextBridge)
┌──────────────────────┴───────────────────────────────────────┐
│  Electron Main + preload bridge                              │
│    ipc.ts                ← allowlisted IPC handlers          │
│    agent-host.ts         ← Pi AgentSession lifecycle         │
│    pi-event-bridge.ts    ← cleanup-aware pi://* events       │
│    pi-resources.ts       ← local persistence (Cordis fs)     │
│    capability-*.ts       ← Cordis capability services        │
└──────────────────────┬───────────────────────────────────────┘
                       │ typed Pi session events
┌──────────────────────┴───────────────────────────────────────┐
│  Pi AgentSession + Cordis capability services                │
│    providers, tools, permissions, plans, tasks, persistence  │
└──────────────────────────────────────────────────────────────┘

Capability mesh — every feature is a Cordis service under packages/<group>/openbuddy-*/:

runtime/      cordis · plugin-host · storage
renderer/     renderer-host (preload bridge glue)
bundle/       base (umbrella for renderer-only deps)
auth/         casdoor · permission
team/         team · subagent
capability/   memory · inspiration · web-search · plan ·
              folder-trust · task · automation · calendar · email · mcp-client · authorization
core/         session
fs/           fs-local
shared/       files-kb · types
collaboration/ coordinator · evidence · inbox · network · policy · protocol · room · task
payment/      Stripe / WeChat Pay / Alipay / HMAC adapters
saml/         SAML 2.0 primitives
scim/         SCIM v2 endpoints (RFC 7644)
webhook-outbox/ transactional outbox + retry/backoff
ui/           26 UI packages (shell, sidebar, settings, workbench, …)

Project layout

src/                     # React frontend
  styles/                # tokens.css / global.css / app.css
  foundation/components/Icon/   # ported from WorkBuddy (207 icons, all implemented)
  lib/                   # pi-client.ts + electron-api.ts (typed bridge wrappers)
  stores/                # Zustand: session / sessions / permission / ...
  components/            # Topbar, Sidebar, HomePage, ChatView, Composer, ...

electron/                # Electron main + preload host
  main/                  # index.ts · window.ts · ipc.ts · agent-host.ts · sessions.ts
  preload/               # contextBridge surface (allowlisted)

apps/
  admin-portal/          # Independent React SPA (Casdoor OIDC + Resource Gateway)

packages/                # one moon project per capability (50+ packages)
  runtime/openbuddy-{cordis,plugin-host,storage}/
  renderer/openbuddy-renderer-host/
  bundle/openbuddy-base/
  auth/openbuddy-{casdoor,permission}/
  team/openbuddy-{team,subagent}/
  capability/openbuddy-{memory,inspiration,web-search,plan,
              folder-trust,task,automation,calendar,email,mcp-client,authorization}/
  core/openbuddy-session/
  fs/openbuddy-fs-local/
  shared/openbuddy-{files-kb,types}/
  collaboration/openbuddy-{coordinator,evidence,inbox,network,policy,
              protocol,room,task}/
  payment/               # Stripe / WeChat Pay / Alipay / HMAC
  saml/                  # SAML 2.0 primitives
  scim/                  # SCIM v2 endpoints
  webhook-outbox/        # transactional outbox
  ui/openbuddy-{shell,sidebar,settings,workbench,…} (19 packages)

.moon/                   # moon workspace + task configuration
  workspace.yml          # 32-project graph (renderer + Electron + packages)
  tasks/                 # typecheck / test / build / dev / electron.* presets
  toolchains.yml         # node 22 / pnpm 10 / typescript 5.6

moon.yml                 # renderer moon project (Vite + React)
electron/moon.yml        # Electron host moon project

scripts/                 # dev/build helpers (thin shims over moon tasks)
docs/                    # all documentation (this folder)

For a deeper dive see docs/ARCHITECTURE.md.

---

🧩 Capabilities

OpenBuddy ships with 63 workspace packages (12 capability, 26 UI, 8 collaboration, …), every one a Cordis service that can be enabled, configured, or extended independently.

Core agent

Package	Purpose
@openbuddy/core-session	Session lifecycle, fork, rewind
@openbuddy/capability-plan	Plan mode + plan approval flow
@openbuddy/capability-task	Sub-agent task spawning & cancellation
@openbuddy/capability-automation	Local scheduler for recurring agent runs
@openbuddy/capability-web-search	Provider-pluggable web search
@openbuddy/capability-inspiration	Prompt templates & starters
@openbuddy/capability-folder-trust	Per-folder permission grants
@openbuddy/capability-authorization	Capability-level policy
@openbuddy/capability-mcp-client	MCP connector governance

File & shell

Package	Purpose
@openbuddy/fs-fs-local	Local filesystem via Cordis
@openbuddy/files-kb	Knowledge-base file indexing

Multi-agent

Package	Purpose
@openbuddy/team-team	Multi-agent team orchestration
@openbuddy/team-subagent	Sub-agent spawning
@openbuddy/collaboration-protocol	A2A message envelopes
@openbuddy/collaboration-room	Shared rooms
@openbuddy/collaboration-inbox	Cross-agent inbox
@openbuddy/collaboration-policy	Cross-agent policy
@openbuddy/collaboration-task	Cross-agent task graph
@openbuddy/collaboration-network	Network topology
@openbuddy/collaboration-evidence	Audit evidence
@openbuddy/collaboration-coordinator	Coordination layer

Enterprise

Package	Purpose
@openbuddy/auth-casdoor	Casdoor OIDC client + admin REST
@openbuddy/auth-permission	Permission prompts & policy UI
@openbuddy/payment	Stripe / WeChat Pay / Alipay / HMAC
@openbuddy/saml	SAML 2.0 primitives
@openbuddy/scim	SCIM v2 endpoints (RFC 7644)
@openbuddy/webhook-outbox	Transactional outbox + retry/backoff

Email & calendar

Package	Purpose
@openbuddy/capability-email	IMAP/SMTP + Gmail/Graph/JMAP API
@openbuddy/capability-calendar	Calendar integration

UI primitives

19 packages under packages/ui/openbuddy-ui-* — shell, sidebar, settings, settings-models, workbench, home, conversation, experts, dialogs, markdown, primitives, modules, theme, runtime, slots, automation, locale, hmr.

---

🛠️ Built With

Layer	Tech
Shell	Electron 44, electron-builder 26, Squirrel, Squirrel.Mac
Renderer	React 18, Vite 5, Zustand 4, React Router 6, react-markdown, lucide-react, KaTeX, Mermaid
Agent runtime	@earendil-works/pi-coding-agent, @earendil-works/pi-agent-core, @earendil-works/pi-ai
Capability mesh	Cordis 3, MCP SDK 1.25
Monorepo	moon 2.5, pnpm 11
Quality	Vitest 2, Playwright 1.58, Testing Library, TypeScript 5.6 strict
Backend integrations	Casdoor, NewAPI, Stripe, WeChat Pay, Alipay, IMAP, SMTP, Gmail API, Graph API, JMAP

---

📚 Documentation

All documentation lives in docs/. Start here:

Doc	What it's for
docs/README.md	Full docs index
docs/GETTING_STARTED.md	30-minute developer setup
docs/ARCHITECTURE.md	Layer-by-layer architecture deep dive
docs/CODEBASE_ANALYSIS.md	Verified 2026-09-05 package inventory & build/runtime architecture
docs/PLUGIN_DEVELOPMENT.md	Build your first Cordis capability
docs/FAQ.md	Frequently asked questions
docs/COMMUNITY.md	Where to ask, chat, and contribute
docs/ROADMAP.md	Public roadmap
SECURITY.md	Security policy & disclosures
SUPPORT.md	How to get help
docs/release-ci.md	Release & CI pipeline
docs/workbuddy-parity-matrix.md	OpenBuddy vs WorkBuddy capability parity
docs/openbuddy-capability-matrix.md	Package-by-package capability list
docs/TESTING.md	Testing strategy & conventions
docs/PERFORMANCE.md	Performance budget & optimization
docs/ACCESSIBILITY.md	WCAG 2.2 AA conformance
docs/OPERATIONS.md	Production deployment & ops
docs/WORKBUDDY_MIGRATION.md	Migrating from Tencent WorkBuddy
docs/EXAMPLES.md	Examples & showcase
docs/GLOSSARY.md	Terminology glossary
docs/ENVIRONMENT.md	Environment variable reference
docs/RELEASING.md	Release process
docs/I18N.md	Translation & localization workflow
docs/COMPARISON.md	OpenBuddy vs Cursor / Continue / aider / Copilot
docs/adr/	Architecture decision records
docs/openbuddy-product-vs-pi.md	How OpenBuddy extends Pi
SECURITY.md	Security policy & disclosures
SUPPORT.md	How to get help
SPONSORS.md	Sponsorship & funding

---

🗺️ Roadmap

The full backlog lives in TODO.md. The public roadmap is in docs/ROADMAP.md. Highlights:

✅ Shipped

• Core layout: Sidebar / HomePage / ChatView / Composer
• In-process Pi agent over the Electron bridge
• WorkBuddy design tokens & 207-icon foundation (all implemented, zero stubs)
• BYOK multi-provider config
• Skills / MCP / Experts surfaces
• Plan mode · Rewind · Tasks · Slash Commands · Automations
• Windows (NSIS + MSI) & macOS (DMG) installers
• CI release workflow (GitHub Actions)
• moon-managed monorepo (moon run everywhere, 32-project DAG, incremental builds)
• Casdoor OIDC + NewAPI gateway + payment adapters + SCIM v2 + SAML 2.0

🚧 In progress

• SceneTabs & skill recommendation bar
• Pinned sessions & workspace grouping
• Permission management panel
• Search across sessions
• Linux builds (AppImage + .deb)
• Code signing & notarization

🔮 Next

• Plugin marketplace (public catalog + install flow)
• Web companion (read-only session view)
• Voice input / output
• Local vector store integration
• 12 more capability packages on the public roadmap

Want to influence the roadmap? Open an issue with the roadmap: label or join the discussion in docs/COMMUNITY.md.

---

🤝 Contributing

OpenBuddy is early and moving fast — contributions of every size are welcome.

1. Read CONTRIBUTING.md for the workflow.
2. Read our CODE_OF_CONDUCT.md.
3. Pick an issue from TODO.md or open a new one to discuss.
4. Fork, branch from master, and hack.
5. Run pnpm electron:dev (= moon run openbuddy:dev.electron).
6. Open a PR — every PR is reviewed within 48h.

Areas that especially need help right now:

• 🐧 Linux packaging & smoke tests
• 🎨 UI polish / screenshots / icons
• 🌍 Docs & i18n (we want Japanese, Korean, Spanish, German next)
• 🔏 CI for macOS signing & notarization
• 🧪 Plugin marketplace catalog curation
• 💼 Enterprise deployment playbooks (Caddy / Nginx / Vault)

All contributors are listed in the GitHub contributors graph. New contributors get a 🎉 in the next release notes.

---

🛡️ Security

OpenBuddy treats security as a first-class concern:

• Context-isolated renderer with allowlisted IPC (electron/preload/index.ts)
• Per-folder trust grants via @openbuddy/capability-folder-trust
• Capability-level policy via @openbuddy/capability-authorization
• Casdoor OIDC with PKCE and refresh token rotation
• SCIM v2 provisioning + SAML 2.0 federation
• Transactional outbox webhook delivery (no lost events)
• Local-first audit ledger persisted across restarts

See SECURITY.md for the full policy and how to report vulnerabilities.

---

🌍 Community

• GitHub Discussions — design proposals & help
• GitHub Issues — bug reports & feature requests
• Discord — real-time chat (link in docs/COMMUNITY.md)
• WeChat group — Chinese-language community
• Office hours — weekly video Q&A (announced in Discussions)

Full details, language-specific channels, and code-of-conduct enforcement contacts are in docs/COMMUNITY.md.

---

⭐ Star History

If OpenBuddy has earned its place on your daily-driver list, please consider giving it a ⭐. It directly fuels the next release cycle.

---

🙏 Acknowledgements

OpenBuddy stands on the shoulders of giants:

• Tencent WorkBuddy — the design north star. OpenBuddy reuses WorkBuddy's --wb-* design tokens, 207-icon foundation (all implemented), and brand atoms for a pixel-close visual experience.
• Pi coding agent — the in-process agent runtime behind OpenBuddy's Electron host.
• Cordis — the dependency-injection framework that powers our capability mesh.
• moon · Electron · React · Vite — moon orchestrates every task; Electron hosts the Cordis/Pi runtime; React + Vite ship the renderer.
• Casdoor · NewAPI — the open-source OIDC IdP and model gateway we integrate with.
• Vitest · Playwright — the test frameworks that keep us honest.

This project is an independent, community-driven open-source effort and is not affiliated with, endorsed by, or sponsored by Tencent.

---

📄 License

OpenBuddy is released under the MIT License — © OpenBuddy contributors.

You are free to use, modify, and distribute OpenBuddy in your own projects, commercial or otherwise, as long as you preserve the copyright notice.