Bitterbot Desktop
A local-first personal assistant that retains long-term memory and operates across chat channels.
Per-dimension scores and reasoning
Evidence shows: README describes local-first, default loopback binding, workspace restrictions, user confirmation mechanisms (e.g., circles default-deny, agent writes require approval), sensitive data encryption (X25519, AES-256-GCM), dependency pinning (pnpm overrides, minimumReleaseAge), external effects (wallet, P2P marketplace) with disclaimers. Deductions: lack of specific code verification, least privilege only partially implemented (e.g., tool workspace restrictions optional), user confirmation only in some scenarios, data flow transparency insufficient, rollback mechanism not mentioned, source attribution partial (LICENSE mentions OpenClaw and pi-agent but no detailed attribution).
Evidence shows: README and package.json consistent, dependency list complete, CI workflow present. Deductions: no specific failure message examples, dependency availability not verified (static review), self-consistency based only on docs, no internal code consistency check.
Evidence shows: README identifies target users (individuals), scenarios (chat, memory, skill trading), capability boundaries described (e.g., circles default-deny, tool restrictions), environment fit (macOS/Linux/Windows, Node>=22). Deductions: trigger precision not detailed (e.g., skill trigger conditions), capability boundaries partially vague (e.g., autonomous earning boundaries), environment fit not covering all platform details.
Evidence shows: README structure clear, install steps detailed, license explicit (MIT), version number present (2026.2.15), CHANGELOG referenced. Deductions: naming stability unverified (non-semantic version), examples and FAQ insufficient, known limitations partial (e.g., circles member removal issue), maintenance responsibility unclear (no contribution guide), version changelog not provided.
Evidence shows: output usability (CLI, UI, API), marginal value (unique features like memory, dream engine), cost-benefit (free open source, but requires API keys). Deductions: output usability unverified (static), marginal value based on marketing, cost-benefit not quantified (e.g., resource consumption).
Evidence shows: README claims partially linked to docs (e.g., memory architecture), but no concrete evidence (e.g., test results). Deductions: claim traceability insufficient, cross-source corroboration lacking (single source), fact-inference separation not explicit (e.g., promotional language).
- The repository includes experimental financial features (wallet, P2P marketplace) involving real money, posing financial risk.
- Many dependencies, some pre-release (e.g., @whiskeysockets/baileys 7.0.0-rc.9), may be unstable.
- Security docs recommend local-only use but lack a full threat model.
- Publisher identity unverified; proceed with caution.
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.jsonor the ACP server insrc/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 doctordiagnostics.
- 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.
FAQ
What credentials are required for a first run?
ANTHROPIC_API_KEY in .env; the README also lists optional Tavily, Brave, OpenAI, and NearAI keys.