{"id":46270417,"url":"https://github.com/ethereal-lemons/limebot-os","last_synced_at":"2026-05-02T09:02:18.272Z","repository":{"id":340032837,"uuid":"1163541835","full_name":"Ethereal-Lemons/LimeBot-OS","owner":"Ethereal-Lemons","description":"LimeBot Open Source a self-hosted, agentic AI assistant with multi-channel support, persistent memory, and a real-time web dashboard.","archived":false,"fork":false,"pushed_at":"2026-05-02T04:14:45.000Z","size":2488,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-02T06:21:40.615Z","etag":null,"topics":["ai-assistant","chatbot","self-hosted","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ethereal-Lemons.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T19:37:52.000Z","updated_at":"2026-05-02T04:14:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ethereal-Lemons/LimeBot-OS","commit_stats":null,"previous_names":["lemonmantisorg/limebot-os"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Ethereal-Lemons/LimeBot-OS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethereal-Lemons%2FLimeBot-OS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethereal-Lemons%2FLimeBot-OS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethereal-Lemons%2FLimeBot-OS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethereal-Lemons%2FLimeBot-OS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ethereal-Lemons","download_url":"https://codeload.github.com/Ethereal-Lemons/LimeBot-OS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethereal-Lemons%2FLimeBot-OS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","chatbot","self-hosted","tools"],"created_at":"2026-03-04T03:05:36.172Z","updated_at":"2026-05-02T09:02:18.266Z","avatar_url":"https://github.com/Ethereal-Lemons.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"web/public/limeLogo.png\" width=\"128\" alt=\"LimeBot Logo\" /\u003e\n\u003c/div\u003e\n\n# 🍋 LimeBot\n\n\n\n\u003e A persistent, self-evolving agentic AI that lives across your devices  with a soul, a memory, and a personality that's actually yours. Inspired by the powerful [OpenClaw](https://github.com/openclaw/openclaw) and the lightweight architecture of [Nanobot](https://github.com/HKUDS/nanobot).\n\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-lime.svg)](https://opensource.org/licenses/MIT)\n[![Status](https://img.shields.io/badge/Status-Public%20Beta-orange.svg)](#-getting-started)\n[![Optimized for](https://img.shields.io/badge/Optimized%20for-Google%20Gemini-blue.svg)](https://ai.google.dev/)\n[![Python](https://img.shields.io/badge/Python-3.11--3.14-blue.svg)](https://www.python.org/)\n[![LiteLLM](https://img.shields.io/badge/LLM-LiteLLM%20Universal-blueviolet.svg)](https://github.com/BerriAI/litellm)\n[![Local First](https://img.shields.io/badge/Privacy-Local%20First-green.svg)](#-privacy--security)\n\nLimeBot is not a wrapper around an API. It's a full agentic system  event-driven, multi-channel, and built to remember who you are. It browses the web, manages your files, schedules reminders, spawns sub-agents for complex tasks, and evolves its personality through every conversation. All of it runs on your hardware. **Currently in public Beta and works best with Google Gemini.**\n\n---\n\n## ✨ What It Can Actually Do\n\n### 🧠 It Remembers Everything\nThree-tier memory system that persists across sessions:\n- **Episodic Memory**  every conversation is appended to a daily markdown journal (`persona/memory/YYYY-MM-DD.md`)\n- **Semantic Memory**  entries are embedded and stored in a local LanceDB vector database, enabling fuzzy recall of anything said weeks ago\n- **Auto-RAG**  before every reply, LimeBot automatically searches its memory (semantically first, grep fallback) and injects relevant context into the prompt without you asking\n- **Reflection Engine**  a background cron job runs every 4 hours, reads today's journal, and distills the key facts into a permanent `MEMORY.md` long-term essence file\n\n### 👤 It Has a Real Persona\nNot a hardcoded system prompt. A living identity that evolves:\n- **`SOUL.md`**  core values, personality, and behavioral boundaries\n- **`IDENTITY.md`**  name, emoji, avatar URL, style, catchphrases, interests, birthday\n- **Local-first persona files**  first boot auto-creates starter `SOUL.md`, `IDENTITY.md`, and `MEMORY.md` from shipped `.example` templates so users get a clean bot without committing live persona state\n- **Per-platform styles**  separate voice for Discord, WhatsApp, and Web\n- **Per-user profiles**  builds a relationship profile for each person it talks to, tracking affinity scores, relationship level, in-jokes, and milestones\n- **Dynamic Mood**  optional `MOOD.md` that shifts based on conversations and persists between sessions\n- **Setup Interview**  if the local persona files are missing or invalid, the bot interviews you to rebuild its identity and saves the result automatically once it has enough to work with.\n\n### 🌐 It Browses the Web\nFull Playwright-powered browser automation:\n- Navigate to any URL, click elements, fill forms, scroll pages\n- `google_search()` shortcut for quick lookups\n- Extract page text, take DOM snapshots, list all media on a page\n- Download high-resolution images from Pinterest, Reddit, Wikimedia, direct URLs\n- Results stream back in real time with progress updates in the dashboard\n\n### 📁 It Has Access to Your Files\nWhitelisted filesystem operations:\n- Read, write, create, delete, move, rename files and directories\n- All operations sandboxed to `ALLOWED_PATHS`  nothing outside those roots is touchable unless you explicitly allow it\n- Dangerous operations (write, delete, run) require explicit confirmation through the web UI before executing\n\n### ⚙️ It Can Run Commands\nSecure subprocess execution with real-time output streaming:\n- Runs shell commands inside the project root\n- Shell injection filter blocks `;`, `\u0026\u0026`, `|`, backticks, `$()`, and env manipulation\n- **Stall detection**  if a command produces no output for 30 seconds (likely waiting for interactive input), it's automatically terminated with guidance to retry using non-interactive flags\n- Requires user confirmation via the dashboard before any command executes\n- **Autonomous Mode**  optionally bypass all confirmation prompts for full hands-off operation\n- **Session-based approval**  approve a tool once for the current session without enabling full autonomy\n\n### 🕐 It Schedules Its Own Reminders\nPersistent cron system:\n- One-time reminders: `\"remind me in 2 hours to call mom\"`\n- Repeating jobs: full cron expression support (`0 8 * * *`)\n- Jobs survive restarts (persisted to `data/cron.json`)\n- With Dynamic Personality enabled: automatic morning greetings and silence check-ins\n\n### 🤖 It Can Spawn Sub-Agents\nFor complex multi-step tasks, LimeBot can delegate work to an isolated background agent:\n- Sub-agent runs in its own session with its own tool loop\n- Built-in specialist profiles like `reviewer`, `verifier`, and `explorer` can be recommended automatically when the request wording matches the task\n- Custom subagents can also be suggested when their descriptions overlap strongly with the current request\n- Reports back to the parent session when complete\n- The web chat renders delegated results as a dedicated sub-agent report card instead of raw trace text\n- Useful for long-running research, file processing, or anything that shouldn't block the main conversation\n\n### 🔌 Model Context Protocol (MCP) Support\nLimeBot is a fully-featured MCP client:\n- **Universal Tool Integration**  connect to any MCP server (Fetch, Filesystem, Brave Search, etc.) to immediately expand the bot's capabilities.\n- **Dynamic Discovery**  tools from connected MCP servers are automatically prefixed with `mcp_server_name_` and injected into the AI's tool registry.\n- **Configurable Servers**  manage server arguments and environment variables directly from the web dashboard.\n- **Safety \u0026 Resilience**  built-in timeouts and error handling ensure that misbehaving MCP servers don't hang the main agent loop.\n\n---\n\n## 📡 Channels\n\n| Channel | How it works |\n|---------|-------------|\n| **Web Dashboard** | React + Vite UI connecting over WebSocket. Streams tokens as they arrive, shows live tool execution cards, confirmation prompts, thinking traces, and ghost activity indicators. **Includes a Custom CSS editor for global UI personalization.** |\n| **Discord** | Full `discord.py` integration. Responds to DMs and `@mentions`. Configurable allow-list by user ID and channel ID. Custom presence status, activity type, and display name. |\n| **WhatsApp** | Connects to a local `whatsapp-web.js` bridge over WebSocket. Contact approval whitelist with pending/blocked states. QR code displayed in the web dashboard for easy pairing. |\n| **Telegram** | Bot API long-polling scaffold. Supports text send/receive, per-user allow-listing, optional per-chat allow-listing, and startup wiring for future expansion. |\n\n---\n\n## 🤖 LLM Support\n\nLimeBot uses [LiteLLM](https://github.com/BerriAI/litellm)  any model it supports, LimeBot supports:\n\n| Provider | Example model string |\n|----------|---------------------|\n| **Gemini** (default) | `gemini/gemini-2.0-flash` |\n| **OpenAI** | `openai/gpt-4o` |\n| **Anthropic** | `anthropic/claude-3-5-sonnet-20241022` |\n| **xAI** | `xai/grok-2` |\n| **DeepSeek** | `deepseek/deepseek-chat` |\n| **Qwen (DashScope)** | `qwen/qwen-max` |\n| **NVIDIA Reference** | `nvidia/meta/llama-3.1-405b-instruct` |\nSwitch models live from the web dashboard without restarting.\n\n### 🛡️ AI Gateway \u0026 Proxy Support\nLimeBot supports routing all LLM traffic through external security or caching middleware (like AI Gateway, Open Guardian, or Helicone):\n- **`LLM_PROXY_URL`**  configure a global proxy URL in the dashboard or `.env`. This overrides the default base URL for all providers.\n- **Provider Normalization**  LiteLLM handles the complex routing and header manipulation required to use custom gateways with cloud providers.\n\n---\n\n## 🧩 Skills\n\nSkills extend what LimeBot can do. Each skill is a folder with a `SKILL.md` (the LLM instructions) and a `skill.py` or script (the execution logic).\n\n**Built-in skills:**\n\n| Skill | What it does |\n|-------|-------------|\n| `browser` | Full Playwright web browsing  navigate, click, type, search, extract |\n| `download_image` | Download high-res images from Pinterest, Reddit, Wikimedia, or direct URLs |\n| `filesystem` | Extended file operations beyond the core toolbox |\n| `discord` | Optional higher-level Discord administration helpers |\n| `docx-creator` | Generate formatted Microsoft Word `.docx` documents |\n\n**Install community skills from GitHub:**\n```bash\n# Full URL\npython -m core.skill_installer install https://github.com/user/my-lime-skill\n\n# GitHub shorthand\npython -m core.skill_installer install user/my-lime-skill\n\n# Or via the CLI wrapper\nnpm run lime-bot skill install https://github.com/user/my-lime-skill\n```\n\nThe installer auto-detects the repo's default branch, and automatically runs `pip install` or `npm install` if dependency files are present.\n\n**Other skill commands:**\n```bash\npython -m core.skill_installer list\npython -m core.skill_installer update \u003cskill_name\u003e\npython -m core.skill_installer uninstall \u003cskill_name\u003e\npython -m core.skill_installer enable \u003cskill_name\u003e\npython -m core.skill_installer disable \u003cskill_name\u003e\n```\n\nSkills can also be managed from the **Skills** tab in the web dashboard.\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites \u0026 Requirements\n- **OS**: Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+)\n- **CPU**: Dual-core (Quad-core recommended for browser tools)\n- **RAM**: 4GB Minimum (8GB recommended for multitasking)\n- **Disk**: ~2GB for installation (venv, node_modules, Chromium)\n- **Software**: Node.js 18+, Python 3.11-3.14\n- **Windows asyncio**: LimeBot relies on asyncio's default Proactor loop on Windows instead of manually forcing a deprecated event loop policy, which keeps Python 3.11-3.14 on one runtime path.\n- **Connectivity**: Stable internet for LLM API and web browsing\n\n### Quick Start\n```bash\ngit clone https://github.com/LemonMantis5571/LimeBot.git\ncd LimeBot\nnpm run lime-bot start\n```\n\nThe CLI handles everything on first run: creates a Python venv, installs backend + frontend dependencies, and opens the web UI. On first chat, LimeBot will interview you to build its persona.\n\n### Manual Start (Developers)\n```bash\n# Terminal 1  Backend\ncp .env.example .env   # fill in your keys\npip install -r requirements.txt\npython main.py\n\n# Terminal 2  Frontend\ncd web \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n### Docker\n```bash\ndocker-compose up --build\n```\n\n### Codex OAuth (CLI-only)\nLimeBot can now store and manage ChatGPT Codex OAuth locally through the CLI without putting the login flow in the web dashboard.\n\n```bash\nlimebot auth codex login\nlimebot auth codex import\nlimebot auth codex status\nlimebot auth codex logout\n```\n\n- `login` starts the browser-based ChatGPT OAuth flow using the local CLI\n- `import` pulls an existing login from `%USERPROFILE%\\.codex\\auth.json` (or `CODEX_HOME/auth.json`)\n- credentials are stored locally in `data/oauth_profiles.json`\n- the dashboard can read status, but sign-in itself stays CLI-only\n\n---\n\n## ⚙️ Configuration\n\nCopy `.env.example` to `.env`:\n\n```env\n# Core\nLLM_MODEL=gemini/gemini-2.0-flash\nGEMINI_API_KEY=your_key_here\nDASHSCOPE_API_KEY=your_dashscope_key_here\n# Optional for Qwen region routing:\n# LLM_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1\n\n# Channels (all optional)\nDISCORD_TOKEN=your_discord_bot_token\nENABLE_WHATSAPP=false\nWEB_PORT=8000\nFRONTEND_PORT=5173\n\n# Security\nALLOWED_PATHS=./persona,./logs,./temp\nAPP_API_KEY=optional_dashboard_password\n\n# Features\nENABLE_DYNAMIC_PERSONALITY=false   # per-user affinity, mood tracking, proactive greetings\nLLM_PROXY_URL=http://localhost:8080/v1 # Optional: Route all traffic through a gateway\n```\n\nEverything can also be changed live from the **Config** tab in the web dashboard  changes write `.env` and trigger a clean restart.\n\n---\n\n## 🛡️ Privacy \u0026 Security\n\n- **Local-first**  all conversations, memories, and personal data stay on your machine.\n- **Sandboxed Filesystem**  LimeBot can only read/write files in directories you explicitly whitelist.\n- **Human-in-the-loop**  sensitive actions (running code, deleting files) require your confirmation.\n- **Open Source**  audit the code yourself. No hidden telemetry.\n\n---\n\n## 🤝 Contributing\n\nWe love contributions! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to submit PRs, report bugs, or request features.\n\n---\n\n## 📄 License\n\nMIT © [LemonMantis5571](https://github.com/LemonMantis5571)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereal-lemons%2Flimebot-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethereal-lemons%2Flimebot-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereal-lemons%2Flimebot-os/lists"}