bitterbot-desktop

Most AI agents are stateless wrappers around an LLM API. Close the terminal, and they forget you exist.

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.

About · Docs · Getting Started

Quick Start

Runtime: Node ≥ 22 · Package manager: pnpm

git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
bash scripts/setup-deps.sh    # installs Chromium, ffmpeg, ripgrep, etc.
pnpm install

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.

pnpm bitterbot onboard

Open 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.

Start it yourself later (or if you skipped the wizard's auto-start):

pnpm start:all              # gateway + Control UI, production; skips whatever is already up

start:all builds dist/entry.js on first run if it's missing, so no separate pnpm build step is required.

Developing on the source? Use watch mode instead:

pnpm dev:all                # gateway (tsdown --watch) + Vite hot-reload, color-tagged logs
# or two terminals:
pnpm gateway:watch          # Terminal 1 — auto-rebuilds on TS changes
cd desktop && pnpm dev      # Terminal 2 — Vite hot-reload

The orchestrator (P2P sidecar) is spawned automatically by the gateway — you do not need to start it separately.

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.

If you prefer to configure everything by hand instead of using the wizard:

cp .env.example .env
# Edit .env with your Anthropic API key (ANTHROPIC_API_KEY)
# and optionally: TAVILY_API_KEY, BRAVE_API_KEY, OPENAI_API_KEY, NEARAI_API_KEY

Then run pnpm bitterbot configure to set gateway port/bind/auth, channels, and other options interactively. Or edit ~/.bitterbot/bitterbot.json directly.

You can also talk to your agent from the terminal:

bitterbot agent --message "What have you learned about me so far?"

A Biological Brain

Bitterbot's memory isn't a vector database with a retrieval step. It's a cognitive architecture grounded in computational neuroscience.

• Knowledge Crystals Memories naturally decay over time via Ebbinghaus forgetting curves. Unused info fades; frequently accessed facts become permanent. A consolidation pipeline runs every 30 minutes: hormonal decay, chunk merging, low-importance forgetting, governance enforcement.
• Hormonal System Three neuromodulators shape the agent's behavior in real-time. Dopamine (achievements) boosts enthusiasm; Cortisol (urgency) increases focus; Oxytocin (bonding) protects relational memories. Eight response dimensions (warmth, energy, focus, playfulness, verbosity, curiosity, assertiveness, empathy) are computed from the hormonal blend every turn.
• Curiosity Engine The agent actively maps what it doesn't know via a unified five-component GCCRF reward function. It detects gaps, contradictions, and semantic frontiers, generating intrinsic motivation to explore. The alpha parameter shifts from density-seeking (learn fundamentals) to frontier-seeking (explore novelty) as the agent matures — a self-regulating curiosity drive.
• Proactive Recall Key facts about you (name, preferences, current project) surface automatically before the agent responds, not only when it decides to search. Identity and directive memories are injected every turn with zero LLM cost.
• Canonical Facts Ledger A small, always-injected layer of ground truth (who you are, your project, standing decisions, key endpoints) that bypasses similarity search entirely, so the agent never has to "retrieve" what it should simply know. Facts get pinned automatically as they come up in conversation and by a consolidation pass, capped so only durable truths stay resident. Re-stating a fact strengthens it; contradicting it supersedes the old belief while keeping its history.
• Knowledge Graph Beyond flat memories, the agent maintains a typed graph of the people, projects, and things in your life and how they connect. Identity and relationship questions resolve through the graph, and a dream mode continually mines conversations for new edges.
• Evolving Identity You define the immutable safety axioms (GENOME.md). The agent's actual personality (the Phenotype) evolves organically based on lived experience, constrained by your genome.

The Dream Engine

Every 2 hours, the agent goes offline to dream. Twelve specialized modes optimize its brain, selected by an FSHO coupled oscillator that reads the current state of the memory landscape:

Each cycle is scored by a Dream Quality Score that measures crystal yield, merge efficiency, orphan rescue, Bond stability, and token efficiency, closing the feedback loop so the dream engine learns which modes work best.

Dreams rewrite the agent's working memory, updating its self-concept, theory of mind about you, and active context. The personality is an output of experience, not a static prompt. On first launch, the agent develops a persistent personality within hours.

Continuous Memory

Most AI memory systems focus on storage and retrieval. Bitterbot closes the loop: memory, emotion, curiosity, and identity form a single self-regulating