diff --git a/README.md b/README.md index 0fddb84d2..7cf60f699 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,298 @@ -# ClawX -> Graphical AI Assistant based on OpenClaw +

ClawX

-ClawX is a modern desktop application that provides a beautiful graphical interface for OpenClaw, making AI assistants accessible to everyone without command-line knowledge. +

+ The Desktop Interface for OpenClaw AI Agents +

+ +

+ Features • + Why ClawX • + Getting Started • + Architecture • + Development • + Contributing +

+ +

+ Platform + Electron + React + TypeScript + License +

+ +--- + +## Overview + +**ClawX** bridges the gap between powerful AI agents and everyday users. Built on top of [OpenClaw](https://github.com/OpenClaw), it transforms command-line AI orchestration into an accessible, beautiful desktop experience—no terminal required. + +Whether you're automating workflows, managing AI-powered channels, or scheduling intelligent tasks, ClawX provides the interface you need to harness AI agents effectively. + +--- + +## Why ClawX + +Building AI agents shouldn't require mastering the command line. ClawX was designed with a simple philosophy: **powerful technology deserves an interface that respects your time.** + +| Challenge | ClawX Solution | +|-----------|----------------| +| Complex CLI setup | One-click installation with guided setup wizard | +| Configuration files | Visual settings with real-time validation | +| Process management | Automatic gateway lifecycle management | +| Multiple AI providers | Unified provider configuration panel | +| Skill/plugin installation | Built-in skill marketplace and management | + +--- ## Features -- 🎯 **Zero CLI Required** - Complete all installation, configuration, and usage through GUI -- 🎨 **Modern UI** - Beautiful, intuitive desktop application interface -- 📦 **Ready to Use** - Pre-installed skill bundles, ready immediately -- 🖥️ **Cross-Platform** - Unified experience on macOS / Windows / Linux -- 🔄 **Seamless Integration** - Fully compatible with OpenClaw ecosystem +### 🎯 Zero Configuration Barrier +Complete the entire setup—from installation to your first AI interaction—through an intuitive graphical interface. No terminal commands, no YAML files, no environment variable hunting. -## Tech Stack +### 💬 Intelligent Chat Interface +Communicate with AI agents through a modern chat experience. Support for multiple conversation contexts, message history, and rich content rendering with Markdown. -- **Runtime**: Electron 33+ -- **Frontend**: React 19 + TypeScript -- **UI Components**: shadcn/ui + Tailwind CSS -- **State Management**: Zustand -- **Build Tools**: Vite + electron-builder -- **Testing**: Vitest + Playwright +### 📡 Multi-Channel Management +Configure and monitor multiple AI channels simultaneously. Each channel operates independently, allowing you to run specialized agents for different tasks. + +### ⏰ Cron-Based Automation +Schedule AI tasks to run automatically. Define triggers, set intervals, and let your AI agents work around the clock without manual intervention. + +### 🧩 Extensible Skill System +Extend your AI agents with pre-built skills. Browse, install, and manage skills through the integrated skill panel—no package managers required. + +### 🔐 Secure Provider Integration +Connect to multiple AI providers (OpenAI, Anthropic, and more) with credentials stored securely in your system's native keychain. + +### 🌙 Adaptive Theming +Light mode, dark mode, or system-synchronized themes. ClawX adapts to your preferences automatically. + +--- + +## Getting Started + +### System Requirements + +- **Operating System**: macOS 11+, Windows 10+, or Linux (Ubuntu 20.04+) +- **Memory**: 4GB RAM minimum (8GB recommended) +- **Storage**: 500MB available disk space + +### Installation + +#### Pre-built Releases (Recommended) + +Download the latest release for your platform from the [Releases](https://github.com/ValueCell-ai/ClawX/releases) page. + +#### Build from Source + +```bash +# Clone the repository +git clone https://github.com/ValueCell-ai/ClawX.git +cd ClawX + +# Install dependencies (pnpm recommended) +pnpm install + +# Initialize OpenClaw submodule +pnpm openclaw:init + +# Start in development mode +pnpm dev +``` + +### First Launch + +When you launch ClawX for the first time, the **Setup Wizard** will guide you through: + +1. **Language & Region** – Configure your preferred locale +2. **AI Provider** – Enter your API keys for supported providers +3. **Skill Bundles** – Select pre-configured skills for common use cases +4. **Verification** – Test your configuration before entering the main interface + +--- + +## Architecture + +ClawX employs a **dual-process architecture** that separates UI concerns from AI runtime operations: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ClawX Desktop App │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Electron Main Process │ │ +│ │ • Window & application lifecycle management │ │ +│ │ • Gateway process supervision │ │ +│ │ • System integration (tray, notifications, keychain) │ │ +│ │ • Auto-update orchestration │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ IPC │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ React Renderer Process │ │ +│ │ • Modern component-based UI (React 19) │ │ +│ │ • State management with Zustand │ │ +│ │ • Real-time WebSocket communication │ │ +│ │ • Rich Markdown rendering │ │ +│ └────────────────────────────────────────────────────────────┘ │ +└──────────────────────────────┬──────────────────────────────────┘ + │ + │ WebSocket (JSON-RPC) + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ OpenClaw Gateway │ +│ │ +│ • AI agent runtime and orchestration │ +│ • Message channel management │ +│ • Skill/plugin execution environment │ +│ • Provider abstraction layer │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Design Principles + +- **Process Isolation**: The AI runtime operates in a separate process, ensuring UI responsiveness even during heavy computation +- **Graceful Recovery**: Built-in reconnection logic with exponential backoff handles transient failures automatically +- **Secure Storage**: API keys and sensitive data leverage the operating system's native secure storage mechanisms +- **Hot Reload**: Development mode supports instant UI updates without restarting the gateway + +--- + +## Use Cases + +### 🤖 Personal AI Assistant +Configure a general-purpose AI agent that can answer questions, draft emails, summarize documents, and help with everyday tasks—all from a clean desktop interface. + +### 📊 Automated Monitoring +Set up scheduled agents to monitor news feeds, track prices, or watch for specific events. Results are delivered to your preferred notification channel. + +### 💻 Developer Productivity +Integrate AI into your development workflow. Use agents to review code, generate documentation, or automate repetitive coding tasks. + +### 🔄 Workflow Automation +Chain multiple skills together to create sophisticated automation pipelines. Process data, transform content, and trigger actions—all orchestrated visually. + +--- ## Development ### Prerequisites -- Node.js 22+ -- pnpm (recommended) or npm +- **Node.js**: 22+ (LTS recommended) +- **Package Manager**: pnpm 9+ (recommended) or npm +- **Git**: For submodule management -### Setup +### Project Structure -```bash -# Clone the repository -git clone https://github.com/ValueCell-ai/ClawX.git -cd clawx - -# Install dependencies -pnpm install - -# Start development server -pnpm dev +``` +ClawX/ +├── electron/ # Electron main process +│ ├── main/ # Application entry, window management +│ ├── gateway/ # OpenClaw Gateway process manager +│ ├── preload/ # Secure IPC bridge scripts +│ └── utils/ # Utilities (storage, auth, paths) +├── src/ # React renderer process +│ ├── components/ # Reusable UI components +│ │ ├── ui/ # Base components (buttons, inputs) +│ │ ├── layout/ # Layout components (sidebar, header) +│ │ └── common/ # Shared components +│ ├── pages/ # Application pages +│ │ ├── Dashboard/ # Home dashboard +│ │ ├── Chat/ # AI chat interface +│ │ ├── Channels/ # Channel management +│ │ ├── Skills/ # Skill browser & manager +│ │ ├── Cron/ # Scheduled tasks +│ │ └── Settings/ # Configuration panels +│ ├── stores/ # Zustand state stores +│ └── types/ # TypeScript type definitions +├── openclaw/ # OpenClaw submodule +├── resources/ # Static assets (icons, images) +└── tests/ # Test suites ``` ### Available Commands ```bash # Development -pnpm dev # Start development server with hot reload -pnpm build # Build for production +pnpm dev # Start with hot reload +pnpm dev:electron # Launch Electron directly + +# Quality +pnpm lint # Run ESLint +pnpm lint:fix # Auto-fix issues +pnpm typecheck # TypeScript validation # Testing -pnpm test # Run unit tests -pnpm test:e2e # Run E2E tests -pnpm test:coverage # Generate coverage report +pnpm test # Run unit tests +pnpm test:watch # Watch mode +pnpm test:coverage # Generate coverage report +pnpm test:e2e # Run Playwright E2E tests -# Code Quality -pnpm lint # Run ESLint -pnpm lint:fix # Fix linting issues -pnpm typecheck # TypeScript type checking - -# Packaging -pnpm package # Package for current platform -pnpm package:mac # Package for macOS -pnpm package:win # Package for Windows -pnpm package:linux # Package for Linux +# Build & Package +pnpm build # Full production build +pnpm package # Package for current platform +pnpm package:mac # Package for macOS +pnpm package:win # Package for Windows +pnpm package:linux # Package for Linux ``` -## Project Structure +### Tech Stack -``` -clawx/ -├── electron/ # Electron main process -│ ├── main/ # Main process entry and handlers -│ ├── gateway/ # Gateway process management -│ ├── preload/ # Preload scripts -│ └── utils/ # Utilities -├── src/ # React renderer process -│ ├── components/ # React components -│ ├── pages/ # Page components -│ ├── stores/ # Zustand state stores -│ ├── hooks/ # Custom React hooks -│ ├── types/ # TypeScript types -│ └── styles/ # Global styles -├── resources/ # Static resources -├── tests/ # Test files -└── build_process/ # Build documentation -``` +| Layer | Technology | +|-------|------------| +| Runtime | Electron 33+ | +| UI Framework | React 19 + TypeScript | +| Styling | Tailwind CSS + shadcn/ui | +| State | Zustand | +| Build | Vite + electron-builder | +| Testing | Vitest + Playwright | +| Animation | Framer Motion | +| Icons | Lucide React | -## Architecture +--- -ClawX follows a dual-port architecture: +## Contributing -- **Port 23333**: ClawX GUI (default interface) -- **Port 18789**: OpenClaw Gateway (native management) +We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or translations—every contribution helps make ClawX better. -``` -┌─────────────────────────────────┐ -│ ClawX App │ -│ ┌───────────────────────────┐ │ -│ │ Electron Main Process │ │ -│ │ - Window management │ │ -│ │ - Gateway lifecycle │ │ -│ │ - System integration │ │ -│ └───────────────────────────┘ │ -│ ┌───────────────────────────┐ │ -│ │ React Renderer Process │ │ -│ │ - Modern UI │ │ -│ │ - WebSocket communication │ │ -│ └───────────────────────────┘ │ -└───────────────┬─────────────────┘ - │ WebSocket (JSON-RPC) - ▼ -┌─────────────────────────────────┐ -│ OpenClaw Gateway │ -│ - Message channel management │ -│ - AI Agent runtime │ -│ - Skills/plugins system │ -└─────────────────────────────────┘ -``` +### How to Contribute + +1. **Fork** the repository +2. **Create** a feature branch (`git checkout -b feature/amazing-feature`) +3. **Commit** your changes with clear messages +4. **Push** to your branch +5. **Open** a Pull Request + +### Guidelines + +- Follow the existing code style (ESLint + Prettier) +- Write tests for new functionality +- Update documentation as needed +- Keep commits atomic and descriptive + +--- + +## Acknowledgments + +ClawX is built on the shoulders of excellent open-source projects: + +- [OpenClaw](https://github.com/OpenClaw) – The AI agent runtime +- [Electron](https://www.electronjs.org/) – Cross-platform desktop framework +- [React](https://react.dev/) – UI component library +- [shadcn/ui](https://ui.shadcn.com/) – Beautifully designed components +- [Zustand](https://github.com/pmndrs/zustand) – Lightweight state management + +--- ## License -MIT +ClawX is released under the [MIT License](LICENSE). You're free to use, modify, and distribute this software. + +--- + +

+ Built with ❤️ by the ValueCell Team +