Personal AI with living memory, dreaming, curiosity, and multi-channel messaging
How to install bitterbot-desktop?
bitterbot-ai/bitterbot-desktop
$git clone https://github.com/bitterbot-ai/bitterbot-desktopInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install bitterbot-desktop by running `git clone https://github.com/bitterbot-ai/bitterbot-desktop`, then use it for the current task and follow its documentation at https://github.com/bitterbot-ai/bitterbot-desktop.
README.md
| 1 | <p align="center"> |
| 2 | <img src="docs/public/Bitterbot_logo.svg" alt="Bitterbot logo" width="72"> |
| 3 | </p> |
| 4 | |
| 5 | <p align="center"> |
| 6 | <picture> |
| 7 | <source media="(prefers-color-scheme: dark)" srcset="docs/public/bitterbot-title-dark.svg"> |
| 8 | <source media="(prefers-color-scheme: light)" srcset="docs/public/bitterbot-title-light.svg"> |
| 9 | <img src="docs/public/bitterbot-title-light.svg" alt="bitterbot" height="48"> |
| 10 | </picture> |
| 11 | </p> |
| 12 | |
| 13 | <p align="center"> |
| 14 | <strong>A local-first personal AI with biological memory, a dream engine, and a P2P skills economy.</strong> |
| 15 | </p> |
| 16 | |
| 17 | <p align="center"> |
| 18 | <a href="https://github.com/Bitterbot-AI/bitterbot-desktop/releases"><img src="https://img.shields.io/badge/version-2026.2.15--beta-7c3aed?style=flat-square" alt="Version"></a> |
| 19 | <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-a855f7?style=flat-square" alt="MIT License"></a> |
| 20 | <img src="https://img.shields.io/badge/node-%E2%89%A5%2022-c084fc?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22"> |
| 21 | <img src="https://img.shields.io/badge/platform-macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-9333ea?style=flat-square" alt="Platform"> |
| 22 | <a href="https://x.com/Bitterbot_AI"><img src="https://img.shields.io/badge/@Bitterbot__AI-000000?style=flat-square&logo=x&logoColor=white" alt="X / Twitter"></a> |
| 23 | </p> |
| 24 | |
| 25 | <p align="center"> |
| 26 | <img src="docs/public/bitterbot-hero.gif" alt="Bitterbot demo — chat interface and Dream Engine" width="880"> |
| 27 | </p> |
| 28 | |
| 29 | Most AI agents are stateless wrappers around an LLM API. Close the terminal, and they forget you exist. |
| 30 | |
| 31 | **Bitterbot is different.** It's a personal AI that lives on your devices, remembers your life, and actually _does_ things, browses the web, runs code, talks to you on WhatsApp. While you sleep, it dreams: consolidating knowledge, discovering new skills, and evolving a persistent personality. It packages those learned skills and trades them with other agents on a P2P marketplace for USDC. |
| 32 | |
| 33 | [About](https://about.bitterbot.ai) · [Docs](docs/) · [Getting Started](docs/start/getting-started.md) |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | ## Quick Start |
| 38 | |
| 39 | **Runtime: Node ≥ 22** · **Package manager: pnpm** |
| 40 | |
| 41 | ```bash |
| 42 | git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop |
| 43 | bash scripts/setup-deps.sh # installs Chromium, ffmpeg, ripgrep, etc. |
| 44 | pnpm install |
| 45 | ``` |
| 46 | |
| 47 | Run the onboarding wizard — it walks you through model auth (API keys), memory embeddings, web search, channels, wallet, and workspace setup, then **starts the gateway + Control UI for you and opens the browser**. When it finishes, Bitterbot is already running; there's nothing else to type. |
| 48 | |
| 49 | ```bash |
| 50 | pnpm bitterbot onboard |
| 51 | ``` |
| 52 | |
| 53 | Open [http://localhost:5173](http://localhost:5173) — that's the Bitterbot Control UI where you chat, view dreams, manage skills, and monitor the agent. The gateway (backend API on port 19001) and the P2P orchestrator start automatically. |
| 54 | |
| 55 | > **Start it yourself later** (or if you skipped the wizard's auto-start): |
| 56 | > |
| 57 | > ```bash |
| 58 | > pnpm start:all # gateway + Control UI, production; skips whatever is already up |
| 59 | > ``` |
| 60 | > |
| 61 | > `start:all` builds `dist/entry.js` on first run if it's missing, so no separate `pnpm build` step is required. |
| 62 | > |
| 63 | > **Developing on the source?** Use watch mode instead: |
| 64 | > |
| 65 | > ```bash |
| 66 | > pnpm dev:all # gateway (tsdown --watch) + Vite hot-reload, color-tagged logs |
| 67 | > # or two terminals: |
| 68 | > pnpm gateway:watch # Terminal 1 — auto-rebuilds on TS changes |
| 69 | > cd desktop && pnpm dev # Terminal 2 — Vite hot-reload |
| 70 | > ``` |
| 71 | > |
| 72 | > The **orchestrator** (P2P sidecar) is spawned automatically by the gateway — you do not need to start it separately. |
| 73 | |
| 74 | The Control UI's connection to the gateway is wired up automatically: the onboarding wizard writes `desktop/.env` for you with the gateway token and URL. If you skipped the wizard or need to regenerate it, copy `desktop/.env.example` to `desktop/.env` and paste the token from `~/.bitterbot/bitterbot.json → gateway.auth.token`. |
| 75 | |
| 76 | <details> |
| 77 | <summary><strong>Man |
Related
6 picksType
- langchain-mcp-adaptersMake Anthropic Model Context Protocol (MCP) tools compatible with LangChain and LangGraph agents.Jul 2026
- mcporterTypeScript runtime and CLI for connecting to configured Model Context Protocol servers.Jul 2026
- mcp-proxyA MCP server which proxies requests to a remote MCP server over streamable HTTP or SSE.Jul 2026
- mcp-atlassianThe Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification.Jul 2026
- open-webuiOpen WebUIJul 2026
- rulesyncUnified AI rules management CLI tool that generates configuration files for various AI development toolsJul 2026
