octo-web

🌐 Read in: English · 简体中文

OCTO Web

Web & PC (Electron) client for the OCTO messaging platform — one React codebase, two shipped surfaces.

octo-web is the TypeScript / React front-end that talks to octo-server over REST + WebSocket. The same codebase ships two ways: as a browser build (the canonical OCTO chat surface), and as an Electron-packaged desktop PC client.

🌟 Why OCTO Web

• One codebase, two products. Browser + PC (Electron) are built from the same src/ — no parallel React trees, no diverging UX. Branch switches happen at platform-capability boundaries only.
• Lobster-ready UI. First-class surfaces for AI agent conversations: streaming replies, typing indicator, inline tool-call previews, read receipts, agent-vs-human identity chips.
• Full bilingual shell. English and Simplified Chinese ship together out of the box; i18n keys live in src/locales/ and are enforced in CI.

🚀 Quickstart

git clone https://github.com/Mininglamp-OSS/octo-web.git
cd octo-web
pnpm install
pnpm dev

By default the web build expects an octo-server instance reachable at http://localhost:8080. Point it at your own server by copying .env.example to .env.local and editing the VITE_API_* values.

📦 Modules / Architecture

Top-level layout:

Key build targets:

pnpm build        # build the browser bundle
pnpm pc:dev       # launch the Electron shell against the dev build
pnpm pc:package   # produce a distributable PC bundle (macOS / Windows / Linux)
pnpm test         # run unit + component tests

The PC Electron shell is intentionally thin — it hosts the same React app and forwards IPC for native capabilities (tray, notifications, file drop, auto- update). The browser build runs without any Electron dependency.

🔗 OCTO Ecosystem

graph TD
  subgraph Clients[Clients]
    Web[octo-web<br/>Web / PC]
    Android[octo-android<br/>Android]
    iOS[octo-ios<br/>iOS]
  end

  subgraph Core[Core Services]
    Server[octo-server<br/>Backend API]
    Matter[octo-matter<br/>Task / Todo]
    Summary[octo-smart-summary<br/>AI Summary]
    Admin[octo-admin<br/>Admin Console]
  end

  subgraph Shared[Shared Libraries & Integrations]
    Lib[octo-lib<br/>Core Go Library]
    Adapters[octo-adapters<br/>Third-party Adapters]
  end

  Web --> Server
  Android --> Server
  iOS --> Server
  Admin --> Server
  Server --> Matter
  Server --> Summary
  Server --> Adapters
  Server -.uses.-> Lib
  Matter -.uses.-> Lib
  Adapters -.uses.-> Lib

🧭 Philosophy

OCTO ships under three shared principles that apply to every repository in this matrix:

1. Local-first. Anything that can run on the user's own box — chats, embeddings, agents — should. Your data stays yours; cloud is a choice, not a requirement.
2. Humans judge, AI thinks and acts. Humans focus on taste (what matters, what's right, what to ship). Lobster agents — OpenClaw-powered digital doubles — carry the thinking and execution load.
3. Release-as-product. Every open-source cut is shipped as a self-contained product, not a code dump: one squash per release, Apache 2.0, no internal baggage, reproducible from this repo alone.

🤝 Contributing

We love pull requests! Before you open one, please read:

• CONTRIBUTING.md — workflow, branch model, commit style
• CODE_OF_CONDUCT.md — community expectations

For security issues please follow SECURITY.md instead of the public tracker.

📄 License

Apache License 2.0 — see LICENSE for the full text and NOTICE for third-party attributions.

🙏 Acknowledgments

octo-web owes its original scaffolding to:

• TangSengDaoDaoWeb — our upstream, by the TangSengDaoDao team.
• WuKongIM — the real-time messaging core that octo-server drives behind this client.

See NOTICE for the full attribution list and third-party component licenses.