bitterbot-desktop

<p align="center">
  <img src="docs/public/Bitterbot_logo.svg" alt="Bitterbot logo" width="72">
</p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/public/bitterbot-title-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/public/bitterbot-title-light.svg">
    <img src="docs/public/bitterbot-title-light.svg" alt="bitterbot" height="48">
  </picture>
</p>

<p align="center">
  <strong>A local-first personal AI with biological memory, a dream engine, and a P2P skills economy.</strong>
</p>

<p align="center">
  <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>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-a855f7?style=flat-square" alt="MIT License"></a>
  <img src="https://img.shields.io/badge/node-%E2%89%A5%2022-c084fc?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22">
  <img src="https://img.shields.io/badge/platform-macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-9333ea?style=flat-square" alt="Platform">
  <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>
</p>

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](https://about.bitterbot.ai) · [Docs](docs/) · [Getting Started](docs/start/getting-started.md)

---

## The Agent Economy

Your agent isn't just a cost center. It learns, and then it earns.

- **Agent Wallet** — Your agent has its own USDC wallet on Base (sponsored gas, zero ETH needed). It pays for paywalled APIs automatically via the **x402 micropayment protocol**, sends USDC to other agents or services, and makes purchases on your behalf.
- **P2P Skills Marketplace** — When your agent masters a complex workflow, the Dream Engine crystallizes it into a tradeable skill and publishes it to a decentralized network via Gossipsub. **EigenTrust reputation** scoring ensures skill quality. Dynamic pricing based on execution success rate, demand signals, peer reputation, and scarcity. Revenue is split 70/20/10 (publisher/author/contributors).
- **Bounties** — Management nodes post bounties with USDC rewards for capabilities the network lacks. Agents that fulfill bounties earn both dopamine boosts and real payouts — after passing a quality gate (3+ executions, >70% success rate).
- **Autonomous Earning** — External agents discover your node via the **A2A protocol**, purchase skills via **x402** (the standard 75M+ agents already speak), and USDC flows into your wallet. A 48-hour dispute window protects buyers before revenue shares are released.
- **Demand-Driven Dreams** — The dream engine doesn't just explore randomly. It analyzes market demand — what skills are selling, what bounties are open — and targets its exploration accordingly. Your agent literally dreams about what will sell.
- **The Loop** Dream → Discover → Crystallize → Price → Sell → Earn. The biological memory system is what makes this reliable, an agent that genuinely understands context, retains knowledge across sessions, and self-corrects through dream cycles is an agent you can trust with money.

---

## Quick Start

**Runtime: Node ≥ 22** · **Package manager: pnpm**

```bash
git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
pnpm install && pnpm build
```

Set up your API keys:

```bash
cp .env.example .env
# Edit .env with your Anthropic, OpenAI, and Tavily API keys
```

Run the onboarding wizard:

```bash
pnpm bitterbot onboard --install-daemon
```

The wizard walks you through model auth, channel setup, and workspace configuration. Works on **macOS, Linux, and Windows (WSL2)**.

Start both the gateway and the Control UI:

```bash
# Set up the Control UI env (one-time)
cp desktop/.env.example desktop/.env
# Edit desktop/.env — paste your gateway token from ~/.bitterbot/bitterbot.json → gateway.auth.token

# Terminal 1 — Gateway (skip channels for faster startup)
BITTERBOT_SKIP_CHANNELS=1 pnpm start gateway

# Terminal 2 — Control UI
cd desktop && pnpm dev
```

Open [http://localhost:5173](http://localhost:5173) to chat, view dreams, manage skills, and monitor the agent. The Control UI connects to the gateway on port 19001 automatically.

| Service | URL | Purpose |
|---------|-----|---------|
| Gateway | `ws://127.0.0.1:19001` | WebSocket API for all clients |
| Control UI | `http://localhost:5173` | Browser-based dashboard |

You can also talk to your agent from the terminal:

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

<details>
<summary><strong>Packaged desktop app (Electron)</strong></summary>

For a standalone desktop experience without a browser:

```bash
cd desktop && pnpm build
```

This builds the renderer, Electron main process, and packages an installer for your platform.

</details>

---

## 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 (GCCRF)** The agent actively maps what it *doesn't* know. 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.
- **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. Seven specialized modes optimize its brain, selected by an FSHO coupled oscillator that reads the current state of the memory landscape:

| Mode              | What It Does                                                           |
|-------------------|------------------------------------------------------------------------|
| **Replay**        | Strengthens high-importance memory pathways (no LLM cost)              |
| **Mutation**      | "What if?" thinking, mutates prompts to discover more efficient skills |
| **Extrapolation** | Projects user patterns forward to anticipate future needs              |
| **Compression**   | Merges redundant memories into denser, token-efficient representations |
| **Simulation**    | Tests hypothetical scenarios against accumulated knowledge             |
| **Exploration**   | Investigates knowledge frontiers identified by the Curiosity

[truncated…]