jsebot

v2026.3.18

Published

4 months ago

JSEBot: personal AI assistant & SDK (OpenClaw fork). Rubi-powered agent framework for CLI, IoT, and cloud.

🤖 JSEBot — Personal AI Assistant

JSEBot is a personal AI assistant you chat with.

It takes 2 minutes to install.

Ready? → START HERE: Simple Install Guide

Or pick your OS: Windows · Mac · Linux · Kali

For developers: Docs · Vision · Contributing

🚀 What is JSEBot?

JSEBot is a personal AI assistant that runs locally on your devices — with full control over privacy, data, and integrations.

🤖 Your AI, Your Rules — Deploy locally, keep data private, use any LLM (Anthropic, OpenAI, local models)
💬 Multi-Channel — Seamless replies on WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Google Chat, and 15+ others
🎨 Rubi Avatar System — Animated sprite-based avatar with zero dependencies (works everywhere)
⚡ Always-On — Gateway daemon (systemd/launchd) runs in the background
🔌 Extensible — First-class skills, tools, and plugin system
📱 Hardware Ready — Pi 5 handheld, M5Stack CoreS3 dashboard, macOS/iOS/Android nodes

Perfect for power users, developers, and anyone who wants AI that works with their workflow, not against it.

Hero Banner

Phase 1-3 Complete: Logo • Splash Screens • Rubi Avatar Animation
Phase 4 Live: Docs • Web • Social Branding

📋 Table of Contents

⚡ Quick Start

1. Install JSEBot

npm install -g jsebot
jsebot onboard

The onboarding wizard guides you through:

✅ Gateway setup (local control plane)
✅ Model selection & authentication (OpenAI, Anthropic, local)
✅ Channel configuration (WhatsApp, Telegram, Slack, etc.)
✅ Workspace setup & first agent
✅ Daemon installation (macOS/Linux/WSL)

2. Start the Gateway

# With daemon (recommended)
jsebot gateway --install-daemon

# Or manually
jsebot gateway --port 18789 --verbose

3. Send Your First Message

jsebot message send --to "@your-name" --message "Hello from JSEBot! 🚀"

4. Chat with the Assistant

# Quick interaction (Haiku model)
jsebot agent --message "What time is it?" --thinking low

# Complex reasoning (Opus model)
jsebot agent --message "Plan my week" --thinking high --model claude-opus-4-1

# With context from file
jsebot agent --message "Summarize this" --file contract.pdf --thinking medium

✨ Features

🤖 Multi-Channel Inbox

Unified assistant across 20+ messaging platforms:

Mainstream: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal
Apple: iMessage (BlueBubbles), FaceTime (via Jello)
Teams: Microsoft Teams, Matrix, Mattermost, Nextcloud Talk
Social: IRC, Twitch Chat, Nostr
Regional: Feishu, LINE, Zalo (Vietnam)
Web: WebChat (in-browser), Control UI
Voice: Wake words (macOS/iOS), continuous voice (Android)

🎨 Rubi Avatar System (Phase 3)

Zero-dependency sprite animation engine:

6 Animation States: Idle → Blink → Talking → Thinking → Success → Error
3 Render Targets: CLI (terminal), Browser (HTML5 canvas), Hardware (Pi 5, M5Stack)
Smart Fallback: ASCII art when sprites unavailable
Memory Efficient: Lazy loading + LRU cache
Frame Control: 100-500ms customizable timing

Live Demos:

🔌 First-Class Tools

Browser: Headless Chromium with screenshot/DOM query
Canvas: Agent-driven UI rendering (macOS/web)
Code Execution: Safe sandboxed environment
Cron: Scheduled tasks (onetime, recurring)
Skills: 50+ bundled + community marketplace
Webhooks: Inbound event handling

💾 Session Model

main: Direct DM conversations
Groups: Channel isolation + mention gating
Activation Modes: Always-on, wake-word, manual trigger
Queue Modes: Sequential (ordered), concurrent, batch
Reply-Back: Auto-deliver responses to original channel

🔒 Security Defaults

DM Pairing: Unknown senders get a short code; approve to allowlist
No DM Access: By default, dmPolicy="pairing" blocks unsolicited DMs
Audit Log: Full event history with timestamps
Config Validation: jsebot doctor flags risky settings

See Security for full details.

📦 Installation

npm (Recommended)

Requirements: Node ≥22

npm install -g jsebot

# Verify
jsebot --version

Then run onboarding:

jsebot onboard --install-daemon

Git Clone (Development)

git clone https://github.com/Ericnussa/JSEclaw.git
cd JSEclaw

# Install dependencies
pnpm install

# Build from source
pnpm build

# Run from dist
node dist/cli.js onboard --install-daemon

# Or use pnpm wrapper (runs TypeScript directly)
pnpm jsebot onboard

Docker

docker run -it --rm \
  -v ~/.jsebot:/root/.jsebot \
  -p 18789:18789 \
  ericnussa/jsebot:latest \
  jsebot onboard

# Then run daemon
docker run -d \
  --name jsebot-gateway \
  -v ~/.jsebot:/root/.jsebot \
  -p 18789:18789 \
  ericnussa/jsebot:latest \
  jsebot gateway --port 18789

Full Deployment Guide with Kubernetes, systemd, launchd examples.

🎮 CLI Commands

jsebot onboard              # Setup wizard
jsebot gateway              # Start control plane daemon
jsebot agent                # Chat with assistant
jsebot message send         # Send to a channel/user
jsebot channel add          # Configure new channel
jsebot skill install        # Install community skill
jsebot doctor               # Audit configuration
jsebot update               # Update to latest version

Common patterns:

# Ask a question
jsebot agent --message "What's the weather?" --thinking low

# Send to specific channel
jsebot message send \
  --to "@john" \
  --channel discord \
  --message "Hey, let's catch up!"

# Use local model
jsebot agent \
  --message "Write a poem" \
  --model ollama/mistral

# Stream response
jsebot agent --message "tell me a story" --stream

# Verbose logging
jsebot gateway --verbose --port 18789

For complete CLI reference, see CLI Guide.

🎨 Feature Showcase

Animation Gallery

The Rubi avatar system supports 6 animation states across 3 platforms:

| State | Duration | Use Case | | ------------ | -------------- | -------------------- | | Idle | Infinite | Waiting for input | | Blink | 100-200ms | Natural eye movement | | Talking | ~30-50ms/frame | Active conversation | | Thinking | ~100ms/frame | Processing response | | Success | 300-500ms | Task complete ✓ | | Error | 200-300ms | Error state ⚠️ |

Screenshot Examples:

Idle State: Calm resting position
Thinking State: Animated thinking gesture
Success State: Happy confirmation
Error State: Alert/concerned expression

See Phase 3 Report for frame-by-frame breakdowns and timings.

Platform Support

| Platform | Avatar | Voice | Screen | | ------------------ | ----------------- | ------------------- | -------------------- | | macOS | ✅ CLI + Canvas | ✅ Wake word + TTS | ✅ Menu bar + Canvas | | iOS | ✅ Node app | ✅ Voice I/O | ✅ Companion app | | Android | ✅ Node app | ✅ Continuous voice | ✅ Floating widget | | Linux | ✅ CLI | ✅ TTS (PipeWire) | ✅ Terminal UI | | Pi 5 Handheld | ✅ Full 320×480 | ✅ I2S audio | ✅ 5.5" display | | M5Stack CoreS3 | ✅ Scaled 320×240 | ✅ Built-in speaker | ✅ 3.5" IPS | | Windows (WSL2) | ✅ CLI | ✅ Windows TTS | ✅ Terminal |

See Deployment Guide for hardware setup instructions.

Demo Links

🎮 CLI Avatar Demo — Run sprite engine in your terminal
📱 Pi 5 Handheld Demo — Interactive web demo of handheld UI
🖥️ M5Stack Dashboard Demo — Desk buddy status display

📚 Documentation

Getting Started

Installation — Step-by-step setup guide
Quick Start — 5-minute hello-world
Configuration — Gateway, channels, agents

Core Concepts

Architecture — Gateway model, sessions, channels
API Reference — Sprite engine, CLI renderer, hardware APIs
Skills & Tools — Available tools + how to create custom ones

Operations

Deployment — Production setups (Docker, Kubernetes, systemd)
Security — DM policies, audit logs, incident response
Troubleshooting — Common issues + solutions
CLI Reference — All commands with examples

Project

Roadmap — Phase 1-5 status + upcoming features
Contributing — Development guide + PR process
Code of Conduct — Community guidelines
Vision — Long-term direction & philosophy

📊 Performance Metrics

Core Engine

| Metric | Value | Notes | | ----------------------- | ----------------- | ------------------------------------------ | | Dependencies | 0 (sprite engine) | Pure JS/TS, no external libraries | | Memory Usage | ~1.5 MB (idle) | Base footprint; grows with active channels | | Startup Time | ~500ms | From binary to gateway ready | | Message Latency | <100ms (local) | Gateway to agent, excludes LLM | | Sprite Cache | 2-5 MB | Lazy-loaded per platform | | Concurrent Sessions | 50+ | Tested up to 100 users |

Channel Performance

| Channel | Throughput | Latency | Status | | ------------ | ----------- | ------- | --------- | | WhatsApp | 50 msg/min | <200ms | ✅ Stable | | Telegram | 100 msg/min | <100ms | ✅ Stable | | Slack | 200 msg/min | <50ms | ✅ Stable | | Discord | 500 msg/min | <50ms | ✅ Stable | | WebChat | Unlimited | <10ms | ✅ Stable |

🤝 Contributing

We love contributions! Whether it's:

🐛 Bug fixes — Submit a PR with test
✨ Features — Open a discussion first
📚 Docs — Typos, guides, examples
🎨 Design — UI/UX improvements
🛠️ Skills — Publish to community marketplace

Development Setup

git clone https://github.com/Ericnussa/JSEclaw.git
cd JSEclaw

pnpm install
pnpm build

# Run tests
pnpm test

# Dev mode (auto-reload)
pnpm gateway:watch

See Contributing Guide for full details.

🔐 Security

JSEBot connects to real messaging services. Treat inbound messages as untrusted input.

Key Defaults

DM Pairing Enabled: Unknown senders get a code; must approve to chat
Group Mode: Mention gating (must mention the bot to respond)
Audit Log: All events logged with timestamps + metadata
Config Validation: jsebot doctor surfaces risky settings

Disclosure

Found a security issue? Please don't open a public issue. Email [email protected] with:

Affected versions
Proof of concept
Suggested fix (if possible)

See Security Policy for details.

❓ FAQ

Q: Is JSEBot free?
A: Yes! JSEBot is MIT-licensed open source. You pay for LLM API calls (OpenAI, Anthropic) or run local models for free.

Q: Is it private?
A: Yes. Your gateway runs locally. Only channel connections (WhatsApp, Telegram, etc.) need internet; you control the data flow.

Q: Can I use local models?
A: Yes! Ollama, LLaMA.cpp, Hugging Face, vLLM all work. See Model Setup.

Q: Does it work offline?
A: The gateway and agent work offline. Channels (WhatsApp, etc.) need internet, but local connections (SSH, Slack) work without external APIs.

Q: How do I deploy to production?
A: See Deployment Guide. We support Docker, Kubernetes, systemd, launchd, and bare metal.

Q: Can I run on a Raspberry Pi?
A: Yes! We have a dedicated Pi 5 setup guide. Tested with Pi 5 (8GB).

Q: Where's the Rubi avatar?
A: Integrated via the sprite engine (Phase 3). See Feature Showcase and Phase 3 Report.

More FAQ: See FAQ.

📈 Project Status

| Phase | Component | Status | Docs | | ----- | --------------------------- | ----------- | ------------------------------- | | 1 | Logo & Icons | ✅ Complete | Phase 1 | | 2 | Splash Screens & Onboarding | ✅ Complete | Phase 2 | | 3 | Rubi Avatar & Animations | ✅ Complete | Phase 3 | | 4 | Docs & Web Branding | ✅ Complete | Phase 4 ← You are here | | 5 | Community & Marketplace | 🚀 Upcoming | Roadmap |

🙏 Thanks

JSEBot stands on the shoulders of giants:

Anthropic (Claude) — Building safe, helpful AI models powering thoughtful responses
Community — Contributors, testers, and feedback providers

📄 License

MIT License — See LICENSE for details.

Made with ❤️ by Eric | Twitter | GitHub | Discord

⭐ If this helps, please star the repo! It means a lot.