octo-web: One React Codebase for Browser and Electron Clients of the OCTO Workplace
Web & desktop (Electron) client for the OCTO open workplace — one React + TypeScript codebase shipping browser and PC surfaces, with first-class AI agent UX.
At a glance
- What is it?
- octo-web is the TypeScript and React front-end for the OCTO messaging platform, shipped as both a browser build and an Electron desktop client. Its distinguishing feature is a first-class UI for AI agent conversations, but adopting it means adopting the OCTO server stack behind it.
- Who is it for?
- octo-web is worth adopting only if you are already running octo-server, or you are willing to stand up that Go backend, because the client is a front-end with no standalone mode. If you want a chat UI that talks to an arbitrary backend, the TangSengDaoDaoWeb upstream is the more honest starting point.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem octo-web Solves: Two Surfaces, One React Tree
Most messaging products that want both a browser client and a desktop app end up maintaining two front-ends. The desktop build drifts, the feature set diverges, and every UI change is made twice. octo-web takes the opposite position. According to the README, the same src/ directory produces both the browser build and the Electron-packaged PC client, and the README states that branch switches happen at platform-capability boundaries only. The Electron layer is described as intentionally thin: it hosts the same React app and forwards IPC for native capabilities such as tray, notifications, file drop, and auto-update. The browser build runs without any Electron dependency.
The audience is narrower than the tagline suggests. This is not a general-purpose chat component library you can drop into an existing product. It is the client half of a specific platform, and the README is explicit that it talks to octo-server over REST plus WebSocket. If you do not run octo-server, there is nothing for this client to talk to. The second audience is teams building agent-facing chat interfaces who want a reference implementation of what that UX looks like: streaming replies, typing indicators, inline tool-call previews, read receipts, and agent-versus-human identity chips are listed as first-class surfaces in the README. That list is the most transferable part of the project, even for people who never deploy it.
Architecture: A Route Layer, a UI Kit, a Store, and a Transport
The README gives a top-level layout table, and it is worth reading as a data-flow description rather than a directory listing. src/pages/ holds route-level views for chat, channels, org, and settings. src/components/ is the shared UI kit, and the README names message bubbles, inputs, agent chips, and streaming renderers as members of it. src/store/ holds client state: auth, channels, draft, and what the README calls agent orchestration UI state. src/api/ is the REST plus WebSocket client that talks to octo-server. src/locales/ holds the i18n resources for English and Simplified Chinese. The electron/ directory contains the main and renderer bootstrap for the PC build.
The separation between src/api/ and src/store/ is the part that matters for anyone extending this. Transport concerns sit in one place, and orchestration UI state sits in another, which is a sensible split when streaming agent replies arrive incrementally over a socket. The README does not describe the WebSocket message schema, the reconnection strategy, or how streaming chunks are merged into store state. Those are the questions a contributor will hit first, and the supplied material does not answer them. The docs/ directory is described as holding design docs, architecture notes, and screenshots, so that is where to look before reading source.
Getting It Running: pnpm, a Local Server, and VITE_API_* Variables
The README quickstart is four commands. Clone the repository, cd into it, run pnpm install, then run pnpm dev. The package manager is pnpm, not npm or yarn, and the repository is described as a monorepo with Turborepo in its topics, so pnpm is a hard requirement rather than a preference.
Configuration happens through environment files. The README states that the web build expects an octo-server instance reachable at http://localhost:8080 by default, and that you point it elsewhere by copying .env.example to .env.local and editing the VITE_API_* values. The README does not enumerate which VITE_API_* keys exist, so read .env.example directly in your checkout. Note the VITE_ prefix: these are Vite build-time variables, which means they are baked into the bundle at build time rather than read at runtime. If you build once and deploy to several environments, that matters.
The build targets are listed explicitly. pnpm build produces the browser bundle. pnpm pc:dev launches the Electron shell against the dev build. pnpm pc:package produces a distributable PC bundle for macOS, Windows, and Linux. pnpm test runs unit and component tests. The README also mentions that i18n keys live in src/locales/ and are enforced in CI, which means a missing translation key is a build failure rather than a runtime fallback. If you add a string, add both locales.
The AI Agent UX Is the Actual Differentiator
Strip away the desktop packaging and the most distinctive thing here is the agent conversation surface. The README lists streaming replies, typing indicators, inline tool-call previews, read receipts, and agent-versus-human identity chips as first-class. In a conventional chat client, a message is a message. Here the UI has to represent a participant that is neither fully a user nor fully a bot: it streams partial output, it may invoke tools mid-reply, and the reader needs to know which parts came from a human and which from an agent.
That set of concerns is what most teams building agent chat get wrong on the first pass, usually by rendering agent output as an ordinary message bubble and discovering later that tool calls and partial streams do not fit. octo-web treats those as component-level concerns, with agent chips and streaming renderers living in src/components/ and orchestration state in src/store/. You can read that structure as a design argument even if you never run the code.
The README also ties the agents to a specific runtime. It describes Lobsters as OpenClaw-powered digital doubles, and the ecosystem table assigns Lobster agent scheduling to octo-server. So the agent behaviour itself is not implemented in this repository. octo-web renders it. If you want to change how an agent decides what to do, this is the wrong repository.
Where octo-web Is the Wrong Tool
Three constraints are visible in the material. The first is the backend dependency. There is no mock mode, no local-only mode, and no adapter layer for a different protocol described in the README. The client speaks REST plus WebSocket to octo-server. Adopting octo-web without octo-server gives you a UI that cannot log in.
The second is the platform assumption. The README describes OCTO as local-first, with chats, embeddings, and agents running on the user's own box where possible. That is a stated philosophy, and the supplied material does not show how much of it is implemented in this client versus in the Go services. Treat the local-first claim as an architectural direction to verify, not a guarantee you can rely on when writing a data-handling policy.
The third is scope of reuse. The Electron shell is deliberately thin, so anyone hoping to find substantial native desktop code here, for example deep OS integration beyond tray, notifications, file drop, and auto-update, will not find it in this repository. The README names exactly those four native capabilities and stops. If your desktop requirements go past that list, you are writing the native layer yourself.
The Alternative: TangSengDaoDaoWeb and WuKongIM
The README credits two upstream projects directly. octo-web owes its original scaffolding to TangSengDaoDaoWeb by the TangSengDaoDao team, and WuKongIM is described as the real-time messaging core that octo-server drives behind this client. That attribution is the most useful comparison available, because it tells you what octo-web added on top.
The difference in approach is where the agent layer sits. TangSengDaoDaoWeb is a messaging web client. octo-web is a fork-line descendant of it with agent conversation surfaces, bilingual shell, and an Electron packaging path layered on. If your requirement is a chat front-end for a WuKongIM-backed server and you have no interest in agent participants, the upstream is closer to your problem and carries less OCTO-specific surface to maintain. If you specifically need streaming agent replies, tool-call previews, and identity chips in the message list, that is the layer octo-web adds, and reimplementing it on the upstream is real work.
On the real-time core, the choice is largely already made for you. WuKongIM sits behind octo-server, and octo-web talks to octo-server. You are not picking between two socket protocols here; you are picking whether to adopt the OCTO stack as a whole.
Maintenance Cost, Release Cadence, and the Apache-2.0 Terms
The release history shows v1.14.0, v1.15.0, and v1.16.0 on consecutive Mondays in late August and early September 2026, with the most recent push to main on 2026-09-10. A weekly minor cadence is a commitment signal, and it also means the client moves. If you fork it, budget for regular rebasing, particularly in src/api/ where server contract changes land.
The README describes a release-as-product policy: one squash per release, Apache 2.0, no internal baggage, reproducible from this repo alone. That is a claim about the release process, not something a reader can confirm from the README text. The practical consequence if it holds is that each tag is a clean diff rather than a slice of a larger internal history, which makes auditing a version easier.
On licensing, the repository is Apache-2.0, with a LICENSE file for the full text and a NOTICE file for third-party attributions. Apache-2.0 includes an explicit patent grant and requires preservation of notices, which is why the NOTICE file matters here: the README points to it for the full attribution list and third-party component licenses, including the TangSengDaoDaoWeb and WuKongIM credits. Read NOTICE before you redistribute a packaged PC build. This is a description of what the repository states, not legal advice; your own counsel should review the NOTICE contents against your distribution model.
Editorial conclusion
octo-web is worth adopting only if you are already running octo-server, or you are willing to stand up that Go backend, because the client is a front-end with no standalone mode. If you want a chat UI that talks to an arbitrary backend, the TangSengDaoDaoWeb upstream is the more honest starting point. Before committing, verify three things in your own checkout: that .env.example exposes the VITE_API_* keys your deployment needs, that your target OS is covered by the pnpm pc:package output, and that the Apache-2.0 NOTICE file lists every third-party component your legal review cares about.
Community notes