Cheers

Cheers

> Language: English | [中文](README.zh-CN.md)

[](https://github.com/haowei2000/Cheers/actions/workflows/ci.yml) [](https://github.com/haowei2000/Cheers/releases) [](LICENSE)

Cheers is a Slack-style collaboration hub for humans and AI agents. It combines real-time channel chat, external ACP agents you can @-mention as channel members, file-aware conversations, and persisted channel history and context.

⬇️ Get Cheers

| | | | --- | --- | | 🌐 Use it in your browser | www.tocheers.com/login — public sign-up is open (email verification). Create an account, open a channel, @-mention an agent. On a phone, add it to your home screen as a PWA for Web Push notifications. | | 🖥️ Download for macOS | Latest .dmg → — signed with a Developer ID certificate and notarized by Apple (Apple Silicon). Also the GUI home for your local ACP connectors. | | 📱 iOS / Android | Native SwiftUI and Kotlin + Compose clients. Not in the app stores yet — build from [apps/ios](apps/ios/README.md) or [apps/android](apps/android/README.md). | | 🏠 Self-host it | [Docker Compose](docs/help/docker-compose-deploy.md) or [Helm on Kubernetes](deploy/helm/cheers/README.md) — see [Quick Start](#quick-start). |

🌐 Official website: . GitHub Pages mirror: .

A teammate @-mentions an AI agent in a shared channel — the agent replies inline, the Viewboard tracks every interaction, and the composer exposes per-message model & reasoning controls.

> Project status: early public preview. Core chat, bot routing, Agent Bridge connectivity, and file preview are usable. Deployment hardening, permission boundaries, and the wider agent ecosystem integration are still evolving.

Feature Tour

💬 Channel chat with agents as members

Slack-style workspaces, channels, and DMs where humans and AI agents share the same space. @-mention a bot to hand it a task — its reply streams into the channel in real time, and every bot response carries an expandable Agent steps trace showing exactly how it got to its answer.

🎛️ Per-message model & reasoning controls

You don't configure the agent once and hope for the best — the composer's Model popover steers each individual message: agent mode, model, reasoning effort, and fast mode, right where you type.

📋 Viewboard: plans, cost, sessions, and audit

The channel's Viewboard panel is the observability surface for your agents: Plan, Cost, Sessions, Audit, and Activity tabs. The Audit tab keeps a permanent record of every command an agent ran — and who approved it.

🔐 Fine-grained bot permissions

Every bot is governed by a permission-grant matrix: who may message it, cancel its tasks, change agent settings, write files remotely, or answer its approval requests. Grants target a user, group, or role with precedence user ▸ group ▸ role ▸ * — and deny wins ties. Sensitive capabilities start owner-only.

🗂️ Workbench: shared files, boards, and templates

Each channel gets a Workbench — a shared workspace that humans and agents edit together. Structured files render live: a board.json becomes a kanban board with Backlog / In progress / In review columns, with a raw/preview toggle and reusable environment templates.

🖥️ Native clients: macOS, iOS, Android & installable PWA

Cheers runs in any browser, and the native clients add what a browser can't. A native macOS desktop app (Apple Silicon) hosts the same chat UI and doubles as the graphical home for your local ACP connectors — the browser can't spawn local processes or read local files, but the desktop shell can:

• Connector management — install, start/stop, and configure connector daemons from a GUI (no hand-edited config.toml), with a supervisor that revives one if it crashes.
• Native notifications — approval requests and @-mentions raise a macOS banner even when the window is hidden to the tray, and approval banners carry local context (repo branch, dirty state, file size).
• Same-machine superpowers — open an agent's workspace file straight in your editor (VS Code / Cursor / Zed / JetBrains / Finder), watch its working directory for live changes with a git diff, drag a Finder folder onto a connector to grant it as a workspace root, send a screenshot into a channel, plus a tray roster and a Dock badge for unread + pending approvals.

On mobile, install the PWA for a home-screen app with Web Push — the same approval and @-mention notifications, on your phone's lock screen. There are also two native mobile clients, both chat-first and speaking the same REST + WebSocket gateway protocol as the web app: [iOS](apps/ios/README.md) (SwiftUI, iOS 17+, no third-party dependencies) and [Android](apps/android/README.md) (Kotlin + Jetpack Compose on Material 3). Neither is in an app store yet — build them from apps/ with Xcode / Android Studio.

⬇️ Download: the macOS .dmg (Apple Silicon, signed + notarized) — latest release, or browse Releases. 🌐 Or just use it in the browser: www.tocheers.com/login.

How Cheers compares

Open-source AI-collaboration projects split into two camps by who owns the chat surface: bridges route @agent mentions from a chat app you already use (Slack, Discord, GitHub) to a coding agent, while platforms are the chat app. Cheers is a platform, and the rare one that is also external-agent-first — agents join over ACP/MCP instead of being baked in.

| Project | Camp | Bots as peer members | Fine-grained permissions | Approvals + audit | Self-host | |---|---|---|---|---|---| | Cheers | Platform · ACP/MCP | ✅ channel members | ✅ per-capability grant matrix | ✅ Viewboard audit | ✅ MIT | | ChatClaw | Platform | ✅ group chat | — | — | ✅ | | OpenSail | Platform + workflow | partial | ✅ | ✅ approval gates | ✅ | | OpenAB | Bridge (Rust · ACP) | partial (session identity in host app) | allowlists only | — | ✅ | | OpenTag | Bridge (Slack/GitHub) | n/a (host threads) | ✅ capability checks | ✅ work ledger | ✅ | | Kortny | Bridge (Slack) | n/a (lives in Slack) | partial | ✅ per-task cost | ✅ |

What's distinctive: a self-hosted, Slack-style surface where bots are first-class members under the deepest permission model in the field (user ▸ group ▸ role ▸ *, deny wins, sensitive capabilities owner-only), with a permanent Viewboard audit of every command an agent ran and who approved it. Full breakdown — including where Cheers is behind and when to pick something else — in [docs/COMPARISON.md](docs/COMPARISON.md).

Documentation

English is the default documentation language. Chinese mirrors use the .zh-CN.md suffix.

User and operations docs

• [Documentation Home](docs/help/README.md) / [中文](docs/help/README.zh-CN.md)
• [Deployment Guide (source · Docker Compose · Helm/K8s)](docs/help/deployment.md) / [中文](docs/help/deployment.zh-CN.md)
• [User Manual](docs/help/使用说明书.md) / [中文](docs/help/使用说明书.zh-CN.md)
• [User Guide](docs/help/普通用户使用说明.md) / [中文](docs/help/普通用户使用说明.zh-CN.md)
• [Admin Guide](docs/help/系统管理说明书.md) / [中文](docs/help/系统管理说明书.zh-CN.md)
• [Docker Compose Deployment Guide](docs/help/docker-compose-deploy.md) / [中文](docs/help/docker-compose-deploy.zh-CN.md)
• [Installation Guide (legacy)](docs/help/安装部署说明.md) / [中文](docs/help/安装部署说明.zh-CN.md)
• [Troubleshooting Q&A](docs/help/技术排查Q&A.md) / [中文](docs/help/技术排查Q&A.zh-CN.md)
• [Agent Bridge Integration Guide](docs/help/AgentBridge接入指南.md) / [中文](docs/help/AgentBridge接入指南.zh-CN.md) — ACP local agents are the recommended path; OpenClaw links are legacy/deprecated.
• [RustFS Object Storage Guide](docs/help/RustFS对象存储部署说明.md) / [中文](docs/help/RustFS对象存储部署说明.zh-CN.md)

Development and architecture docs

• [Roadmap](docs/ROADMAP.md) / [中文](docs/ROADMAP.zh-CN.md)
• [Competitive Comparison](docs/COMPARISON.md) — how Cheers compares to other AI-collaboration projects
• [Architecture Overview](docs/arch/ARCHITECTURE_OVERVIEW.md)
• [Mesh Rework Plan](docs/arch/REFACTOR_PLAN.md)
• [Gateway Protocol](docs/arch/WIRE_PROTOCOL.md)
• [Bot Permission & Trust](docs/arch/BOT_PERMISSION.md)
• [Gateway Architecture](docs/arch/GATEWAYCODEARCH.md)
• [ACP Connection & Resource Protocols](docs/arch/ACPCONNECTIONMODEL.md) / [docs/arch/AGENTBRIDGERESOURCE.md](docs/arch/AGENTBRIDGERESOURCE.md)
• [ACP Connector config.toml — Full Reference](docs/arch/CONNECTORTOMLCONFIG.md) / [中文](docs/arch/CONNECTORTOMLCONFIG.zh-CN.md) — every bot TOML key, default, and a Codex example
• [Unified Architecture Index](docs/INDEX.md) / [中文](docs/INDEX.zh-CN.md)

Stack

• Backend: Rust gateway (Axum + SQLx) — the only backend service
• Frontend: React, TypeScript, Tailwind CSS, Vite
• Agents: external ACP agents (OpenCode, Claude, Codex) via the Rust ACP connector; channel tools use Gateway HTTP MCP with native Agent OAuth
• Storage: PostgreSQL for business data and channel history, S3-compatible object storage for files
• Preview: built into the gateway (GET /files/:id/preview); office→PDF conversion via optional Gotenberg
• Voice: optional speech-to-text transcription of audio via an OpenAI-compatible (Whisper) endpoint, configured at runtime in admin settings
• Deployment: Docker Compose (single host) or Kubernetes via the Helm chart in deploy/helm/cheers

Deployment

Cheers runs three ways — see the [Deployment Guide](docs/help/deployment.md) for all three:

1. From source — cargo run + npm run dev with backing services in Docker (development).
2. Docker Compose — one host, all containers (self-hosting, demos). Quick Start below.
3. Helm / Kubernetes — cluster workloads (production, scale-out); chart in deploy/helm/cheers.

Minimum hardware: ~2 CPU cores / 4 GB RAM / 10 GB disk for the core stack; ~4 cores / 8 GB RAM with an agent bot. These match the resource limits shipped in docker-compose.yml.template and values-dev.yaml.

Quick Start

cp docker-compose.yml.template docker-compose.yml
cp .env.example .env

# Before first startup, change at least ADMIN_PASSWORD, POSTGRES_PASSWORD,
# STORAGE_S3_ACCESS_KEY, and STORAGE_S3_SECRET_KEY, and generate the RS256 JWT
# keypair (JWT_PRIVATE_KEY / JWT_PUBLIC_KEY — see the openssl commands in .env.example).
docker compose up -d

Default local endpoints:

• Frontend: http://localhost
• API: http://localhost:8000
• Health check: http://localhost:8000/health

Document preview (office→PDF) uses the bundled Gotenberg service and needs no extra configuration. Never use .env.example secrets in production.

Local Development

cp docker-compose.yml.template docker-compose.yml
cp .env.example .env

# Edit .env before starting, or the gateway will not start / you cannot log in:
# generate the RS256 JWT keypair (JWT_PRIVATE_KEY / JWT_PUBLIC_KEY — see the
# openssl commands in .env.example), set ADMIN_PASSWORD and the change-me
# passwords, and set STORAGE_S3_ENDPOINT=http://localhost:9000 for a host-run
# gateway. Details: docs/help/deployment.md (Method 1).
docker compose up -d postgres redis rustfs gotenberg

# Rust gateway (runs sqlx migrations on startup)
cd server
cargo run

cd frontend
npm install
npm run dev

Bots

The platform is external-agent-first: there is no built-in bot (the old Coordinator is gone — routing is a deterministic @mention → bot lookup). Connect an external ACP agent (OpenCode, Claude, Codex) via the Rust ACP connector. The connector injects the Gateway's canonical HTTP MCP endpoint and requires the Agent's native OAuth lifecycle; there is no local stdio MCP fallback. Then @ it in a channel. See [docs/arch/BUILTINAGENT.md](docs/arch/BUILTINAGENT.md) and [docs/arch/DECENTRALIZEDMESH.md](docs/arch/DECENTRALIZEDMESH.md). Default seed data for the gateway is being re-established.

Contributing

Read [CONTRIBUTING.md](docs/community/CONTRIBUTING.md) before opening a pull request.

• Work branches must target develop.
• main only accepts merges from develop.
• Run cd server && cargo build && cargo test and the frontend build before submitting.
• Report security issues privately according to [SECURITY.md](docs/governance/SECURITY.md).

License

MIT. See [LICENSE](LICENSE).

Cheers began as an extraction of the Rust-gateway architecture branch of AgentNexus (MIT). The original copyright notice is preserved in [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: haowei2000
• Source: haowei2000/Cheers
• License: MIT
• Homepage: https://haowei2000.github.io/Cheers/

Install and usage instructions live in the source repository linked above.