Onboarding: lobehub/lobehub

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 42%)
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

LobeHub is a TypeScript-first, full-stack multi-agent collaboration platform that lets users create, deploy, and collaborate with AI agent teammates. It combines a chat UI (similar to ChatGPT) with an agent harness supporting multi-agent orchestration, MCP (Model Context Protocol) plugin one-click installation, a built-in knowledge base, TTS/STT, and a CLI tool (lh/lobe/lobehub) for interacting with agents from the terminal. The core problem it solves is enabling persistent, composable AI agent workflows across both personal productivity and team collaboration contexts. Monorepo structure: the CLI lives under a package with its own package.json using tsdown for bundling and bun as the runtime/package manager; agent skill definitions live in .agents/skills/ as SKILL.md + YAML files covering domains like builtin-tool, agent-signal, db-migrations, desktop, drizzle, and chat-sdk. The main app is a Next.js frontend with a tRPC backend, Drizzle ORM over PostgreSQL, and Electron for the desktop variant.

Who it's for

TypeScript/React developers and power users who want to self-host or extend an open-source ChatGPT alternative with multi-agent orchestration, plugin ecosystems, and programmable agent pipelines — particularly those building on top of MCP, Vercel AI SDK, or integrating local LLMs via Ollama.

Maturity & risk

Actively developed with high community engagement (tens of thousands of GitHub stars, CI via GitHub Actions visible in the shields, Codecov integration, and Vercel deployment pipeline). The codebase has Vitest-based testing, Gherkin BDD tests, and a release automation workflow. Verdict: production-ready for self-hosting but moving fast — breaking changes between minor versions are common.

The monorepo has deep inter-package dependencies (workspace:* references like @lobechat/agent-gateway-client, @lobechat/device-gateway-client, @lobechat/heterogeneous-agents) that can make partial upgrades fragile. The CLI package (@lobehub/cli v0.0.8) is pre-1.0 and explicitly experimental. The breadth of integrations (PLpgSQL migrations, Drizzle ORM, tRPC, Electron desktop, MCP plugins, dozens of LLM providers) increases the surface area for regressions. Single-organization maintainer risk exists despite community contributors.

Active areas of work

Active work is visible on: the CLI tool (v0.0.8, with references docs under .agents/skills/cli/references/ covering agent, conversation, knowledge, memory, models-providers, search-config, skills-plugins); heterogeneous agent support (.agents/skills/heterogeneous-agent/); desktop app feature implementation (.agents/skills/desktop/references/feature-implementation.md); and MCP plugin marketplace integration. The .agents/skills/ directory itself is a meta-layer being actively expanded to codify engineering patterns.

Get running

git clone https://github.com/lobehub/lobe-chat cd lobe-chat bun install

For the CLI specifically:

cd packages/cli # or the CLI package directory bun run dev

For the main web app:

bun run dev

Daily commands:

Web app dev server:

bun run dev

CLI in dev mode (uses .lobehub-dev as home dir):

LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts

Run CLI tests:

bun run test

Build CLI for distribution:

bun run build && bun run man:generate

Map of the codebase

• .agents/skills/project-overview/SKILL.md — Top-level architectural overview of the entire LobeHub project — essential reading before touching any module.
• .agents/skills/agent-signal/references/architecture.md — Defines the core agent signal/streaming architecture that underpins all LLM interactions and multi-agent collaboration.
• .agents/skills/store-data-structures/SKILL.md — Documents the Zustand store data structures that are the single source of truth for all client-side state.
• .agents/skills/chat-sdk/SKILL.md — Describes the Chat SDK layer — the primary abstraction between UI components and LLM provider calls.
• .agents/skills/data-fetching/SKILL.md — Defines the data-fetching patterns (SWR/server actions) used across every feature, critical for avoiding cache inconsistencies.
• .agents/skills/db-migrations/SKILL.md — Explains Drizzle ORM migration conventions — mandatory reading before any database schema change.
• .agents/skills/agent-runtime-hooks/SKILL.md — Documents the runtime hook system that intercepts agent execution — central to understanding plugin and tool invocation.

How to make changes

Add a new LLM provider

1. Read the provider skill to understand the registration contract and required adapter methods (.agents/skills/cli/references/models-providers.md)
2. Add the provider YAML configuration following the OpenAI reference agent definition (.agents/skills/agent-signal/agents/openai.yaml)
3. Register runtime hooks for the new provider's streaming format (.agents/skills/agent-runtime-hooks/SKILL.md)
4. Add provider documentation following the add-provider-doc skill conventions (.agents/skills/add-provider-doc/SKILL.md)

Add a new built-in tool

1. Study the tool design principles and registration contract (.agents/skills/builtin-tool/tool-design.md)
2. Implement tool architecture following the established pattern (.agents/skills/builtin-tool/architecture.md)
3. Create the tool result UI renderer component (.agents/skills/builtin-tool/ui.md)
4. Register the tool entry point per the main skill file (.agents/skills/builtin-tool/SKILL.md)

Add a new CLI sub-command

1. Review CLI skill conventions for command structure and option naming (.agents/skills/cli/SKILL.md)
2. Determine which domain the command belongs to (agent, conversation, knowledge, etc.) (.agents/skills/cli/references/agent.md)
3. Implement backend handler and wire up data-fetching using established patterns (.agents/skills/data-fetching/SKILL.md)
4. Add backend integration test following CLI backend testing conventions (.agents/skills/cli-backend-testing/SKILL.md)

Add a new database table / schema change

1. Review Drizzle ORM query and schema conventions (.agents/skills/drizzle/SKILL.md)
2. Author the migration file following the migration skill (.agents/skills/db-migrations/SKILL.md)
3. Write a database model test for the new table (.agents/skills/testing/references/db-model-test.md)

Why these technologies

• Bun — Used as the runtime and package manager for the CLI package, providing fast TypeScript execution without a separate build step during development and significantly faster test runs via Vitest.
• tsdown (build) — Bundles the CLI TypeScript source to a single distributable ESM entry point (dist/index.js) with minimal config, replacing heavier bundlers like Webpack for CLI use-cases.
• Drizzle ORM — Type-safe SQL query builder with first-class migration support; chosen over Prisma for its lightweight runtime, better edge/serverless compatibility, and direct SQL control needed for complex agent memory queries.
• Zustand — Minimal, hook-first state management that avoids Redux boilerplate; enables fine-grained subscriptions critical for streaming token-by-token UI updates without re-rendering entire trees.
• Electron — Powers the desktop application shell, enabling native OS integrations (file system, local tools, menu bar) while sharing the same React/TypeScript codebase as the web client.
• Vitest — Fast ESM-native test runner compatible with Bun; used for unit and integration tests across CLI, store actions, and DB model layers with a unified config.

Trade-offs already made

• Skill-based agent knowledge stored as markdown files in .agents/skills/

  • Why: Allows AI agents to read architectural documentation directly from the repo without a separate knowledge-base system, keeping docs co-located with code.
  • Consequence: Documentation can drift from implementation; no automated enforcement that skill docs stay in sync with actual code changes.

• ESM-only package ("type": "module")

  • Why: Aligns with modern Node.js/Bun ecosystems and avoids dual CJS/ESM build complexity.
  • Consequence: Breaks compatibility with older CommonJS consumers and

Traps & gotchas

1. The CLI uses LOBEHUB_CLI_HOME env var to locate its config directory — omitting it in dev causes it to write to your real home directory. 2) The workspace uses Bun exclusively; npm/yarn/pnpm will fail to resolve workspace:* dependencies correctly. 3) The CLI package (@lobehub/cli) is published separately from the main app and has its own release cycle at v0.0.8 — don't assume feature parity with the web UI. 4) PLpgSQL migrations require a running PostgreSQL instance; there is no SQLite fallback for server mode. 5) MCP plugin features require compatible MCP server endpoints configured separately.

Architecture

Concepts to learn

• Model Context Protocol (MCP) — LobeHub's plugin marketplace and one-click tool installation are built on MCP — understanding it is essential for adding or debugging any plugin/tool integration.
• tRPC — All client-server communication in the web app uses tRPC for end-to-end type safety — you need to understand router/procedure patterns to add any new API endpoint.
• Drizzle ORM schema migrations — Database schema is managed via Drizzle with PLpgSQL migrations; incorrect migration authoring can cause data loss across deployments.
• Heterogeneous agent orchestration — LobeHub's multi-agent system allows agents of different types/providers to collaborate — this pattern is non-trivial and governed by .agents/skills/heterogeneous-agent/.
• Server-Sent Events (SSE) for LLM streaming — LLM response streaming uses SSE under Vercel AI SDK; understanding the streaming lifecycle is required for debugging truncated or stuck responses.
• tsdown (esbuild-based bundler) — The CLI is bundled with tsdown rather than webpack/rollup — its tree-shaking and ESM output behavior differs and affects how workspace:* dependencies are inlined at build time.
• Agent signal/event architecture — Real-time multi-agent coordination relies on a custom signal/event system documented in .agents/skills/agent-signal/references/architecture.md — misunderstanding it leads to race conditions in agent workflows.

Related repos

• lobehub/lobe-chat — The primary web application repo that this monorepo's packages (including the CLI) are built to extend — the CLI is a terminal interface to lobe-chat's agent backend.
• ChatGPTNextWeb/ChatGPT-Next-Web — Direct alternative: another popular open-source self-hosted ChatGPT UI built with Next.js, solving the same self-hosting problem without the multi-agent/MCP focus.
• lobehub/lobe-ui — Companion repo providing the shared React component library (antd-style based) used across LobeHub's frontends.
• modelcontextprotocol/modelcontextprotocol — The MCP specification repo — LobeHub's plugin one-click install and MCP marketplace features are built on top of this protocol.
• mckaywrigley/chatbot-ui — Ecosystem predecessor/inspiration: an earlier open-source ChatGPT UI that established the pattern LobeHub expanded upon with agents and plugins.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CLI command modules in .agents/skills/cli/references/

The CLI package (@lobehub/cli) has multiple command reference files (agent.md, conversation.md, generate.md, knowledge.md, memory.md, models-providers.md, search-config.md, skills-plugins.md) indicating a rich feature surface. The package.json shows a test setup with vitest but there is no evidence of comprehensive unit tests for these command handlers. Adding tests for the core CLI commands would improve reliability and help new contributors understand expected behavior.

• [ ] Review each reference file under .agents/skills/cli/references/ (agent.md, conversation.md, generate.md, knowledge.md, memory.md, models-providers.md, search-config.md, skills-plugins.md) to understand the command contracts
• [ ] Locate the corresponding source files in src/ (e.g. src/commands/agent.ts, src/commands/conversation.ts, etc.) and identify untested code paths
• [ ] Create vitest test files (e.g. src/commands/tests/agent.test.ts) covering happy paths and error cases for each command using bun's test runner as configured in vitest.config.mts
• [ ] Mock external dependencies like @lobechat/agent-gateway-client and @lobechat/device-gateway-client to keep tests isolated
• [ ] Ensure coverage reports via 'npm run test:coverage' show meaningful improvement for the commands directory

Add a GitHub Actions CI workflow for the @lobehub/cli package build and test pipeline

The package.json for @lobehub/cli defines build (tsdown), type-check (tsc --noEmit), and test (vitest) scripts, but there is no visible GitHub Actions workflow file dedicated to this CLI package. Given the package is published to npm (publishConfig points to npmjs.org) and has a prepublishOnly step, a missing CI workflow means PRs can break the build or tests without automated feedback. A targeted workflow would gate merges on passing type checks and tests.

• [ ] Create .github/workflows/cli-ci.yml targeting the packages/@lobehub/cli directory (or wherever it lives in the monorepo)
• [ ] Configure the workflow to trigger on pull_request and push to main when files under the CLI package path change, using paths filtering
• [ ] Add steps: checkout, setup bun (matching the dev script which uses 'bun src/index.ts'), install dependencies with workspace support, run 'npm run type-check', run 'npm run test', and run 'npm run build'
• [ ] Cache bun dependencies to speed up CI runs
• [ ] Add a badge to the CLI package README or the root README referencing this new workflow status

Create a dedicated SKILL.md reference doc and example agent YAML for the heterogeneous-agent desktop local-tools skill

The file structure shows .agents/skills/desktop/references/local-tools.md exists alongside feature-implementation.md, menu-config.md, and window-management.md, but the .agents/skills/heterogeneous-agent/ skill only has a debug-workflow.md reference and a top-level SKILL.md. There is no agent YAML example for heterogeneous agents targeting desktop local tools (contrast with .agents/skills/agent-signal/agents/openai.yaml which provides a concrete agent definition). Adding this bridges the gap between the desktop local-tools reference and the heterogeneous-agent skill, giving contributors a working example to build on.

• [ ] Study .agents/skills/agent-signal/agents/openai.yaml as the canonical example of an agent YAML definition in this repo
• [ ] Study .agents/skills/desktop/references/local-tools.md to understand the available local tool surface (file system, shell, OS integrations via @lobechat/local-file-shell)
• [ ] Create .agents/skills/heterogeneous-agent/agents/desktop-local-tools.yaml that demonstrates a heterogeneous agent wired to at least two desktop local tools, following the

Good first issues

1. Add unit tests for CLI knowledge and memory commands referenced in .agents/skills/cli/references/knowledge.md and memory.md — these reference docs exist but test coverage for the CLI is sparse at v0.0.8. 2) The .agents/skills/desktop/references/local-tools.md file exists but desktop local tool integration likely lacks E2E Gherkin scenarios — add BDD test coverage for at least one local tool flow. 3) The add-setting-env skill (.agents/skills/add-setting-env/SKILL.md) suggests a pattern for env-var-backed settings but new providers added to the system may not consistently follow it — audit and document missing env vars for 2-3 newer providers.

Top contributors

• @arvinxx — 36 commits
• @tjx666 — 16 commits
• @nekomeowww — 12 commits
• @Innei — 11 commits
• @lobehubbot — 10 commits

Recent commits

• ce516ff — 🐛 fix(space): show document update time (#14366) (AmAzing129)
• 9e23183 — 💄 style: add grok-4.3 for xAI (#14382) (hezhijie0327)
• 79b84a6 — 🌐 chore: translate non-English comments to English in brief-types and conversation (#14410) (lobehubbot)
• 56e811f — 🌐 chore: translate non-English comments to English in agentSignal and builtin-tool-claude-code (#14432) (lobehubbot)
• 5fb795b — ✨ feat(cli): add lh hetero exec for standalone heterogeneous agent runs (#14431) (arvinxx)
• fbe71e7 — ✅ test(workflows,workflows-hono): mixed export of agent signal types for workflow (#14429) (nekomeowww)
• d83f0a0 — ♻️ refactor(chat): introduce agentDispatcher.selectRuntimeType (#14428) (arvinxx)
• fe65741 — ♻️ refactor(hetero-agent): extract producer pipeline into shared package (#14425) (arvinxx)
• b5e4cd0 — 🐛 fix: revoke sessions after password reset (#14424) (tjx666)
• f565ca9 — 🐛 fix: revoke sessions after password reset (#14424) (tjx666)

Security observations

• High · SSRF Protection Disabled by Default Comment Misleading — .env.example. The .env.example contains a comment stating 'Default is 0 (SSRF protection enabled)' for SSRF_ALLOW_PRIVATE_IP_ADDRESS, but the variable is commented out. If an operator misreads the documentation or sets SSRF_ALLOW_PRIVATE_IP_ADDRESS=1, all SSRF protection is disabled, allowing attackers to make the server perform requests to internal network resources, cloud metadata endpoints (e.g., 169.254.169.254), and other private infrastructure. Fix: Ensure SSRF protection is enforced by default in code without requiring explicit opt-in. Add validation in startup code that warns or exits if SSRF_ALLOW_PRIVATE_IP_ADDRESS is set to 1 in production environments. Consider removing the option to fully disable SSRF protection.
• High · Proxychains Included in Production Docker Image — Dockerfile. The Dockerfile installs and copies proxychains-ng into the distroless production image. Proxychains is a tool designed to route traffic through proxy chains and is typically a penetration testing/offensive security tool. Its presence in a production container increases the attack surface, could be used by an attacker who gains code execution to route malicious traffic, and suggests potential operational security concerns about how outbound network traffic is being managed. Fix: Remove proxychains from the production image unless there is a documented, justified use case. If proxy support is needed, use standard HTTP_PROXY/HTTPS_PROXY environment variables or a proper sidecar proxy (e.g., Envoy). If proxychains is required, document the reason clearly and ensure it is not accessible to untrusted workloads.
• High · Node.js 24 Slim Base Image May Contain Unpatched Vulnerabilities — Dockerfile. The Dockerfile uses node:24-slim as the base image. Slim images may still contain outdated system libraries. The build does run apt update, but does not run apt upgrade, meaning pre-installed OS packages may remain unpatched. This could expose the container to known CVEs in base OS libraries. Fix: Add 'apt upgrade -y' after 'apt update' in the Dockerfile RUN instruction, or switch to a minimal, frequently-rebuilt base image with automated vulnerability scanning. Integrate container image scanning (e.g., Trivy, Snyk) into the CI/CD pipeline.
• High · API Key Selection Mode Exposed via Environment Variable Without Validation Documentation — .env.example. The API_KEY_SELECT_MODE variable (supporting 'random' and 'turn') is documented in .env.example, suggesting API keys are managed and cycled application-side. If API keys are stored insecurely (e.g., in plaintext environment variables without secret management), a container escape or environment variable leak could expose all API keys at once. Fix: Use a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets with encryption at rest) instead of plain environment variables for API keys. Implement secret rotation and audit logging for API key usage.
• Medium · Content Security Policy Disabled by Default — .env.example. The ENABLED_CSP variable in .env.example has a comment saying 'Default is 0 (enabled)' but is commented out. The variable name ENABLED_CSP=1 implies CSP and X-Frame-Options headers are controlled by this flag. If not explicitly set or if the default behavior in code is to disable these headers, the application is vulnerable to clickjacking and cross-site scripting attacks. Fix: Enable CSP and X-Frame-Options headers by default (fail-secure). CSP should be opt-out, not opt-in. Review the application code to ensure security headers are sent on all responses regardless of this environment variable's value.
• Medium · SSRF Whitelist Bypass Risk via IP Address List — .env.example. SSRF_ALLOW_IP_ADDRESS_LIST allows specific private IPs to be whitelisted. IP-based whitelisting can be bypassed through DNS rebinding attacks, where an attacker controls a domain that initially resolves to an allowed public IP but later resolves to a whitelisted private IP after the DNS TTL expires. Additionally, if the list is managed via environment variables, it could be manipulated. Fix: Implement DNS rebinding protection by resolving hostnames to IPs at request time and validating the resolved

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.