Bitterbot Desktop
A local-first personal assistant that retains long-term memory and operates across chat channels.
What does this agent do, and when should you use it?
Bitterbot is a local-first personal AI composed of a Gateway, browser-based Control UI, and a Rust P2P orchestrator spawned by the Gateway. It accepts conversations through messaging channels and WebChat, while its runtime can control Chromium, execute Python or JavaScript, and use a Canvas workspace. Its Memory System combines Knowledge Crystals, a knowledge graph, hormonal state, and a Dream Engine for durable and working memory. The Gateway exposes HTTP and WebSocket services, while the Control UI defaults to localhost:5173. The repository also documents A2A Protocol and ACP services plus optional USDC, x402, and P2P skills-marketplace functionality.
After pnpm bitterbot onboard, the wizard configures model authentication, memory embeddings, web search, channels, wallet, and workspace, then starts the gateway, Control UI, and gateway-managed orchestrator. The Gateway routes input from configured channels and WebChat to the Agent Runtime, which can use Chromium browser control, Python/JavaScript execution, and Canvas. The Memory System stores and recalls Knowledge Crystals, canonical facts, and graph relationships; the documentation describes a 30-minute consolidation pipeline and a Dream Engine cycle every two hours. Dream modes such as Replay, Research, Compression, and Interceptor Harvest consolidate memory, investigate skills, or draft pre-action interceptors. The P2P orchestrator handles network-layer skills, bounties, reputation, and USDC functions, while external agents can discover and delegate through /.well-known/agent.json and A2A JSON-RPC.
- A person who wants one assistant across WhatsApp, Telegram, and Slack can route those conversations through one Gateway and persistent memory system.
- A user who wants preferences, project relationships, and confirmed facts to persist across conversations can use Knowledge Crystals, the canonical facts ledger, and the knowledge graph.
- A developer or researcher who needs a local assistant to browse the web, run Python or JavaScript, and work with Canvas can use the documented runtime tools.
- A node operator seeking to package proven workflows as skills, publish them to a peer network, or respond to capability bounties can enable the skills marketplace, x402, and USDC wallet features.
- A team connecting external A2A clients or IDEs to a local assistant can use the A2A endpoint at `/.well-known/agent.json` or the ACP server in `src/acp/`.
What are this agent's strengths and limitations?
- Combines persistent memory, a knowledge graph, canonical facts, and scheduled Dream Engine processing in one runtime rather than adding only a retrieval step to chat.
- The Gateway brings multiple chat channels, WebChat, browser control, code execution, and Canvas into one local Agent Runtime.
- Documents A2A Protocol, ACP, a P2P skills marketplace, x402, and a USDC wallet for deployments that need interoperability or skill exchange.
- Provides explicit onboarding, automatic startup, watch-mode development, port assignments, and `bitterbot doctor` diagnostics.
- Installation requires Node.js 22+, pnpm, and dependencies installed by `scripts/setup-deps.sh`, including Chromium, ffmpeg, and ripgrep.
- Models, web search, and messaging channels require applicable credentials or keys; several capabilities depend on external network services.
- P2P economy features, USDC wallets, skill purchases, and inter-node connectivity add financial, network, and security operating responsibilities.
- The README notes that Circles do not yet rotate channel keys after member removal, so a removed member with the old roster may still read future traffic.
- License evidence is inconsistent: repository metadata says NOASSERTION while the README badge says MIT, so adopters should clarify the applicable license.
How do you install or deploy this agent?
Requires Node.js 22 or later and pnpm.
git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
bash scripts/setup-deps.sh
pnpm install
pnpm bitterbot onboardThe wizard configures model authentication. For manual setup, copy .env.example to .env and set ANTHROPIC_API_KEY; optional keys listed are TAVILY_API_KEY, BRAVE_API_KEY, OPENAI_API_KEY, and NEARAI_API_KEY. Once onboarding completes, open http://localhost:5173; the Gateway defaults to port 19001.
How do you use this agent?
After onboarding, use http://localhost:5173 to chat, inspect dreams, manage skills, and monitor the agent. From a terminal:
bitterbot agent --message "What have you learned about me so far?"Use pnpm start:all to start the production Gateway and Control UI later, or pnpm dev:all for source development. For configuration or connectivity problems, run pnpm bitterbot doctor; it checks runtime, configuration, Gateway, memory, channels, wallet, and P2P network subsystems.
How does this agent compare with similar options?
Bitterbot uses OpenClaw as scaffolding for WhatsApp, Telegram, Discord, Signal, and Slack message routing and the embedded agent runner. The README describes Bitterbot's memory system, Dream Engine, curiosity and hormonal systems, economic layer, P2P marketplace, and A2A interoperability as additional original work.