How the OCTO Web Client Works for Human and AI Agent Collaboration

Most attempts to integrate LLMs into work chats end up as simple Telegram bots. The user types a slash command, waits a few seconds, and gets a standard single-block response. The creators of the OCTO project decided to approach it from a different angle. They are building an open work environment where AI agents sit in chats alongside people as full-fledged digital employees.

Today we'll break down the octo-web repository. This is the frontend part of the system, written in TypeScript and React.

Unified Codebase for Web and Desktop

The main architectural decision of the project is to abandon the separation between the web version and the desktop client. The developers didn't create two separate React projects. The entire application lives in the src/ directory.

If you run the client in a browser, the standard build works. If you're building a desktop version for macOS, Windows, or Linux, a thin Electron layer from the electron/ folder is connected. This layer handles integration with the operating system: system tray, notifications, file drag-and-drop, and background updates.

This approach eliminates the need to duplicate UI components or maintain two different interface branches.

Interface for Working with AI Agents

Regular chats are poorly suited to the specifics of neural network work. When a model selects a tool or executes a chain of reasoning, a conventional messenger only shows a typing indicator.

In octo-web, the interface was designed from the ground up for agent autonomy (in the project's terminology, they are called Lobsters, and they work based on OpenClaw).

Here's what's implemented in the layout and components:

• Streaming response rendering with real-time Markdown support
• Display of invoked functions and tools directly within the message (inline tool-call)
• Separation of typing and read statuses for humans and autonomous agents
• Visual badges that help instantly distinguish a bot from a live colleague
• Bilingual interface support (English and Chinese) with locale checking at the CI stage

How the Project Structure is Organized

Inside the repository, everything is organized into clear folders without unnecessary complexity:

• src/pages/ contains the main screens: chats, channel lists, settings, and organizational structure
• src/components/ stores the component set: message bubbles, input fields, agent badges, and streaming renders
• src/store/ handles client state: authorization, drafts, channels, and agent interaction status
• src/api/ contains REST and WebSocket clients for communication with the backend
• electron/ contains entry points for Electron

The client communicates with the octo-server backend, written in Go. The WuKongIM engine is used for real-time message transmission. The authors don't hide the fork: they took the basic frontend structure from the open-source TangSengDaoDaoWeb project and adapted it for AI tasks.

Quick Start for Development

To run the web client locally, you need Node.js and the pnpm package manager.

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

By default, the client expects the octo-server backend to be running on localhost:8080. To point it to a different address, create a .env.local file based on .env.example and specify the current values for VITE_API_*.

Building the desktop application is triggered by separate commands:

pnpm build        # обычная веб-сборка
pnpm pc:dev       # запуск Electron-клиента
pnpm pc:package   # упаковка приложения под нужную ОС

Principles and Autonomy

The project developers follow the local-first idea. Everything that can run on the user's hardware or within the company's network perimeter should run there. Chats, vector databases, and AI agents run locally without mandatory binding to third-party clouds.

Their approach to role division is simple: AI handles reasoning and routine execution, while humans set the direction and evaluate quality.

Who Should Look at the Repository

The project currently has around 600 stars on GitHub, but it's interesting as an example of clean React and Electron monorepo organization. If you're building a work chat, an internal company tool, or experimenting with interfaces for LLMs, you can find useful solutions here for tool calling and message streaming.

The project is distributed under the Apache 2.0 license, so you can freely examine the code in detail or use it in your own projects.