openviber 0.5.1 → 0.5.2

package/README.md

@@ -4,9 +4,7 @@
 
 # OpenViber
 
-### The Open Source Cowork Desktop for Your AI Workforce
-
-<!-- SHIELD GROUP -->
+### You Imagine It. Tasks Build It.
 
 [![Download][download-shield]][viber-npm]
 [![GitHub Stars][github-star]][viber-github]
@@ -19,12 +17,12 @@
 
 ---
 
-**Viber** is an open-source Cowork Agent platform that runs AI teammates on your machine. Unlike cloud-based agent frameworks, Viber runs locally with full privacy, connects outbound to your enterprise channels, and automates real work while you sleep.
+**OpenViber** is an open-source platform that turns your machine into a **Viber** — hosting role-scoped AI workers called **tasks** that automate real work. Unlike cloud-based agent frameworks, OpenViber runs locally with full privacy, connects outbound to your enterprise channels, and works autonomously while you sleep.
 
 ### ⭐ 100% Open Source · 🥇 Local Deployment · 🏆 MCP Integration
 
 - ✅ **Zero Setup** — No servers to host, just `npx openviber start`
-- ✅ **Multi-Agent Workforce** — Specialized agents working in parallel
+- ✅ **Task Workforce** — Role-scoped tasks working in parallel
 - ✅ **Human-in-the-Loop** — Enterprise messaging channels (DingTalk, WeCom)
 - ✅ **Privacy First** — 100% local execution, data never leaves your machine
 
@@ -32,115 +30,119 @@
 
 ## 🚀 Quick Start
 
+The fastest way to get started is using `npx`:
+
 ```bash
+# 1. Set your API key (OpenRouter recommended)
+export OPENROUTER_API_KEY="your_api_key_here"
+
+# 2. Start OpenViber (Standalone Mode)
 npx openviber start
 ```
 
-## 🧠 Personalization (The Three-File Pattern)
-
-OpenViber follows the same configuration pattern that has emerged across all serious agent systems (Claude Projects, Custom GPTs, Cursor Rules). Three markdown files define your agent's complete behavior:
-
-```
-~/.openviber/
-├── soul.md     # How your agent thinks and communicates
-├── user.md     # Who you are and what you're working on  
-├── memory.md   # What your agent remembers over time
+If you prefer to install it globally:
+```bash
+npm install -g openviber
+viber start
 ```
 
-| File | Purpose | Update Frequency |
-|------|---------|------------------|
-| **soul.md** | Communication style, boundaries, operational rules | Monthly |
-| **user.md** | Current projects, priorities, preferences | Daily/Weekly |
-| **memory.md** | Decisions, learned patterns, corrections | Grows organically |
-
-These files work as a system — a detailed personality is useless without user context, and memory without personality produces generic responses. The power comes from alignment between all three.
-
-**The skill transfers**: Time invested in configuring these files isn't locked into OpenViber. The pattern is identical across agent platforms, so your configuration travels with you.
+---
 
-See [Personalization Architecture](./docs/design/personalization.md) for setup instructions.
+## 🛠️ Development Setup
 
-## ✨ Features
+If you want to contribute or run from source:
 
-### 🤖 Multi-Agent Workforce
+### 1. Prerequisites
+- **Node.js** v18+ and **pnpm** (recommended)
+- **tmux** installed (`brew install tmux` on macOS)
 
-Deploy specialized agents that work in parallel via simple YAML configuration:
+### 2. Installation
+```bash
+git clone https://github.com/dustland/openviber.git
+cd openviber
+pnpm install
 
-```yaml
-# examples/jobs/morning-standup.yaml
-name: morning-standup
-schedule: "0 9 * * 1-5"
-prompt: "Check my GitHub notifications and Slack mentions, summarize what needs my attention"
-model: anthropic/claude-sonnet-4-20250514
+# Configure environment
+cp .env.example .env
+# Add your OPENROUTER_API_KEY to .env
 ```
 
-### 🔧 Zero Configuration Skills
-
-Capabilities defined in `SKILL.md` files — no code required:
+### 3. Launch full stack
+```bash
+# Starts Gateway + Viber runtime (port 6009) and Web UI (port 6006)
+pnpm dev
+```
+- **Viber Board (Web UI)**: [http://localhost:6006](http://localhost:6006)
+- **Viber Gateway**: [http://localhost:6009](http://localhost:6009)
 
-```markdown
----
-name: git-commit
-description: Stage and commit changes
 ---
 
-git add . && git commit -m "$message"
-```
+## 🧵 Interactive Experience
 
-### 🌐 MCP Integration
+OpenViber provides multiple ways to interact with your vibers, designed for both developers and teams.
 
-Connect to any Model Context Protocol server for extended capabilities:
+### 💻 Terminal Chat (tmux-friendly)
+Use OpenViber from any terminal. It integrates deeply with tmux for streaming output and managing long-running tasks.
 
-```yaml
-mcp_servers:
-  - name: github
-    command: npx -y @modelcontextprotocol/server-github
+```bash
+# Start an interactive chat
+viber chat
 ```
 
-### 👤 Human-in-the-Loop
-
-Critical for long-running vibe-working tasks like vibe-coding:
+### 🌐 Viber Board (Web UI)
+A modern, visual interface to manage your tasks, monitor jobs, and chat in real-time. Accessible at `http://localhost:6006` when running `pnpm dev`.
 
-- **Approval Gates** — Pause for human review before critical actions
-- **Interactive Channels** — Real-time collaboration via DingTalk/WeCom
-- **Progressive Autonomy** — Start supervised, gradually increase agent freedom
-- **Context Handoff** — Seamlessly transfer context between human and agent
+### 🏢 Enterprise Channels
+Deploy your tasks to where your team works. Support for **DingTalk** and **WeCom** is built-in.
 
-```yaml
-# Example: Require approval for deployments
-approval_required:
-  - deploy
-  - delete
-  - billing
+```bash
+# Start the enterprise channel server
+# Note: Defaults to port 6009. If running alongside 'viber start' (which also uses 6009), use a different port:
+viber channels --port 6010
 ```
 
-### 💬 Enterprise Channels
+---
 
-Native integrations for DingTalk (钉钉) and WeCom (企业微信):
+## 🧠 Personalization (The Three-File Pattern)
 
-```bash
-openviber start --channel dingtalk --token YOUR_TOKEN
-openviber start --channel wecom --corpid YOUR_CORP
-```
+OpenViber follows a standardized configuration pattern for AI personality. Three markdown files define your task's complete behavior:
 
----
+| File | Scope | Purpose | Update Frequency |
+|------|-------|---------|------------------|
+| **`user.md`** | Shared | Who you are, current projects, priorities | Daily/Weekly |
+| **`soul.md`** | Per-task | Communication style, boundaries, rules | Monthly |
+| **`memory.md`** | Per-task | Decisions, learned patterns, corrections | Grows organically |
 
-## 📚 Examples
+Location: `~/.openviber/vibers/default/`
 
-### 🩹 Antigravity — Self-Healing for AI Coding Tools
+---
 
-A built-in skill example that monitors and recovers AI coding tools:
+## ✨ Key Features
 
+### 🤖 Task Workforce (Jobs)
+Deploy autonomous workers via simple YAML cron jobs.
 ```yaml
-# examples/jobs/antigravity-healer.yaml
-name: antigravity-healer
-schedule: "*/3 * * * * *" # every 3 seconds
-skill: antigravity
-prompt: "Check Antigravity IDE status and auto-recover if errors found"
+# examples/jobs/morning-standup.yaml
+name: morning-standup
+schedule: "0 9 * * 1-5" # Every weekday at 9 AM
+prompt: "Check GitHub notifications, summarize what needs my attention."
+```
+
+### 🔧 Zero Configuration Skills
+Capabilities are defined in `SKILL.md` files. No complex code required to extend your tasks.
+```markdown
+---
+name: git-commit
+description: Stage and commit changes
+---
+git add . && git commit -m "$message"
 ```
 
-- **Monitors** all IDE windows for agent crashes
-- **Auto-recovers** by clicking Retry across multiple windows
-- **Keeps** your flow uninterrupted
+### 🌐 Model Context Protocol (MCP)
+Seamlessly connect to any MCP server to give your tasks access to external tools like Google Maps, Slack, or custom internal APIs.
+
+### 👤 Human-in-the-Loop
+Maintain control with approval gates. Tasks can be configured to pause and ask for permission before executing sensitive actions (e.g., deleting files, making payments).
 
 ---
 
@@ -148,73 +150,54 @@ prompt: "Check Antigravity IDE status and auto-recover if errors found"
 
 ```
 ┌─────────────────────────────────────────────────┐
-│              Viber Cowork Desktop               │
+│                    Viber                        │
 │                                                 │
-│  ┌──────────┐  ┌────────┐  ┌────────────────┐   │
-│  │ViberAgent│──│ Agents │──│     Tools      │   │
-│  │ (Leader) │  │(Workers)│  │(Browser/File)  │   │
-│  └──────────┘  └────────┘  └────────────────┘   │
+│  ┌────────────────────────────────────────────┐  │
+│  │  dev-task  │ researcher-task  │ pm-task    │  │
+│  └────────────────────────────────────────────┘  │
+│        │                                        │
+│   ┌────┴─────────────────────┐                  │
+│   │  Gateway (REST + WS)     │                  │
+│   │  Scheduler + Dispatcher  │                  │
+│   └──────────────────────────┘                  │
 │        │                                        │
 │   ┌────┴─────────────────────┐                  │
-│   │         Scheduler        │                  │
-│   │    (YAML Cron Jobs)      │                  │
+│   │  Worker (Agent Engine)   │                  │
+│   │  Tools + Skills + MCP    │                  │
 │   └──────────────────────────┘                  │
 │        │                                        │
 │   ┌────┴─────────────────────┐                  │
 │   │        Channels          │                  │
-│   │  DingTalk | WeCom | Web  │                  │
+│   │  Board │ DingTalk │ CLI  │                  │
 │   └──────────────────────────┘                  │
 └─────────────────────────────────────────────────┘
           ↓                    ↓
     Outbound Only      Local Execution
 ```
 
-## 📦 Three Pillars
-
-| Component  | What                        | Where            |
-| ---------- | --------------------------- | ---------------- |
-| **Jobs**   | Scheduled tasks (YAML cron) | `examples/jobs/` |
-| **Skills** | Capabilities (SKILL.md)     | `skills/`        |
-| **Tools**  | Low-level primitives        | `src/tools/`     |
-
 ## 📊 Comparison
 
-|            |     Viber      |   Cloud Agents    | IDE Plugins |
-| ---------- | :------------: | :---------------: | :---------: |
-| Deployment |   Local app    |   Cloud server    | Editor only |
-| Connection |    Outbound    |      Inbound      |    None     |
-| Jobs       |   YAML cron    |   Complex code    |   Manual    |
-| Privacy    |   100% local   |    Data leaves    |   Varies    |
-| Channels   | DingTalk/WeCom | WhatsApp/Telegram |    None     |
+| Feature | OpenViber | Cloud Agents | IDE Plugins |
+| :--- | :---: | :---: | :---: |
+| **Deployment** | Local Viber | Cloud Server | Editor Only |
+| **Connectivity** | Outbound | Inbound/Cloud | None |
+| **Autonomy** | Full (Jobs/Cron) | Managed | Manual Trigger |
+| **Privacy** | 100% Local | Data Leaves | Limited |
+| **Channels** | Multi-channel | Web only | Chat only |
 
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-## 📄 License
-
-This project is licensed under the [Apache License 2.0](./LICENSE).
-
-```
-Copyright 2024-2026 Dustland
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
-    http://www.apache.org/licenses/LICENSE-2.0
-```
+## Thanks
 
-### 🙏 Acknowledgments
+Special thanks to the maintainers and contributors of [awesome-openclaw-skills][awesome-openclaw-skills] for curating a high-quality OpenClaw skill catalog that helps power skill discovery in OpenViber.
 
-Viber is built on the shoulders of amazing open-source projects:
+## 📄 License
 
-- [Vercel AI SDK](https://sdk.vercel.ai) — Unified LLM interface
-- [Model Context Protocol](https://modelcontextprotocol.io) — Standardized tool integration
-- [Croner](https://github.com/hexagon/croner) — Lightweight cron scheduling
-- [Zod](https://zod.dev) — TypeScript-first schema validation
+Licensed under the [Apache License 2.0](./LICENSE).
 
 ---
 
@@ -229,17 +212,16 @@ If you find Viber helpful, please ⭐ star us on GitHub!
 </div>
 
 <!-- LINKS -->
-
 [viber-site]: https://viber.dustland.ai
-[viber-github]: https://github.com/dustland/viber
+[viber-github]: https://github.com/dustland/openviber
 [viber-npm]: https://www.npmjs.com/package/openviber
 [docs-site]: https://viber.dustland.ai/docs
-[github-issues]: https://github.com/dustland/viber/issues
-[license-link]: https://github.com/dustland/viber/blob/main/LICENSE
+[github-issues]: https://github.com/dustland/openviber/issues
+[license-link]: https://github.com/dustland/openviber/blob/main/LICENSE
+[awesome-openclaw-skills]: https://github.com/VoltAgent/awesome-openclaw-skills
 
 <!-- SHIELDS -->
-
 [download-shield]: https://img.shields.io/badge/Download-Viber-blue?style=flat-square
-[github-star]: https://img.shields.io/github/stars/dustland/viber?style=flat-square&logo=github
+[github-star]: https://img.shields.io/github/stars/dustland/openviber?style=flat-square&logo=github
 [npm-shield]: https://img.shields.io/npm/v/openviber?style=flat-square&logo=npm
-[license-shield]: https://img.shields.io/badge/License-Apache%202.0-green?style=flat-square
+[license-shield]: https://img.shields.io/badge/License-Apache%202.0-green?style=flat-square