butterfly-bot 0.8.0

Butterfly Bot is an opinionated personal-ops AI assistant built for people who want results, not setup overhead.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

## Butterfly Bot

<div style="margin-bottom: "20px">
        <img width="300px" alt="Butterfly-Bot-NTT" src="https://github.com/user-attachments/assets/36eceb35-b517-498a-803f-1c3b5a655ddb" />
</div>

[![CI](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/ci.yml)
[![codecov](https://img.shields.io/codecov/c/github/truemagic-coder/butterfly-bot/main.svg)](https://codecov.io/gh/truemagic-coder/butterfly-bot)
[![Crates.io](https://img.shields.io/crates/v/butterfly-bot.svg)](https://crates.io/crates/butterfly-bot)
[![Rust](https://img.shields.io/badge/Rust-1.93%2B-orange?logo=rust)](https://www.rust-lang.org/tools/install)
[![fmt](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/fmt.yml/badge.svg)](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/fmt.yml)
[![clippy](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/clippy.yml/badge.svg)](https://github.com/truemagic-coder/butterfly-bot/actions/workflows/clippy.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Butterfly Bot is an opinionated personal-ops AI assistant built for people who want results, not setup overhead.

It is built to be **Zapier-first**: most real-world integrations run through Zapier MCP, so the fastest path is simply adding your Zapier MCP token in the Config screen.

Get your Zapier key here: [https://zapier.com/mcp](https://zapier.com/mcp) and setup your integrations there.

<img width="1272" height="898" alt="Screenshot from 2026-02-22 12-09-04" src="https://github.com/user-attachments/assets/c31ddd32-70c3-4865-9ad0-58e8d0e42686" />

### Install

#### Ubuntu

Download the `deb` file for Ubuntu from the latest [GitHub Release](https://github.com/truemagic-coder/butterfly-bot/releases)

#### Mac

Download the `app` file for Mac from the latest [GitHub Release](https://github.com/truemagic-coder/butterfly-bot/releases)

### Why users pick it:

- **Fast value:** works out-of-the-box with default settings.
- **OpenAI-first:** optimized for OpenAI routing and coding with simple key-based setup.
- **UI-first:** polished desktop app with collaboration-first workflow tabs for execution, planning, and chat.
- **Automation:** full toolset provided for your always-on agent.
- **Integrations:** Zapier-first MCP integration model for connecting your existing SaaS stack in minutes.
- **Security:** WASM-only execution for tools plus OS keychain-backed secrets - no plaintext secrets or insecure tools.
- **Memory:** best-in-class memory that remembers the facts and when they happened.

### OpenAI setup (recommended)

1. Open the app and go to `Config`.
2. Paste your **OpenAI API key**.
3. Save the config and start chatting.

Notes:

- Router model defaults to **`gpt-4.1-mini`** on `api.openai.com`.
- Memory models run on OpenAI defaults.
- **Grok API key** is optional and only used for internet search.

### Zapier-first setup (60 seconds)

If you only configure one thing, configure Zapier:

1. Open the app and go to `Config`.
2. Paste your **Zapier MCP token** and save the config.

That single token unlocks most production workflows because Butterfly Bot can route actions through Zapier's connected apps (email, calendar, tasks, CRM, docs, alerts, and more).

Want a fast start? Use the ready-made templates in [examples/](examples/) and paste a `context.md` + `heartbeat.md` pair into the app.

## Human ↔ Agent collaboration tabs

Butterfly Bot now separates conversation from execution so humans and agents can coordinate in one shared workflow surface:

- **Inbox** - actionable items and ownership handoffs.
- **Kanban** - stage-based workflow overview.
- **Dependencies** - blocker and prerequisite visibility.
- **Gantt** - estimate-based timeline visualization.
- **Audit** - authoritative lifecycle and state-transition ledger.
- **Chat** - human ↔ agent conversation only.
- **Activity** - operational/system timeline updates.
- **Config / Diagnostics / Context / Heartbeat** - setup, runtime health, and agent behavior controls.

This keeps work artifacts, operational evidence, and chat clearly separated while still connected through shared item references and lifecycle state.

## Built for the money layer: Agentic Wallet + x402 Payments

Butterfly Bot is built around a **first-of-its-kind hardware-encrypted agentic wallet** so your AI can act, pay, and execute with strong built-in protection.

What this means for non-technical users:

- **Your wallet is protected by hardware-grade encryption by default.**
- **Your assistant can run agentic payments with x402** for real autonomous commerce flows.
- **You stay in control** with approval checkpoints for sensitive actions.

Simple story: your assistant is not just smart - it can also be an economic actor.

Read the deeper details: [docs/solana-x402-economic-actor.md](docs/solana-x402-economic-actor.md)

## Documentation map

| I need… | Go here |
|---|---|
| Product and architecture deep dive | [docs/product-deep-dive.md](docs/product-deep-dive.md) |
| Security audit behavior and guidance | [docs/security-audit.md](docs/security-audit.md) |
| Threat model and trust boundaries | [docs/threat-model.md](docs/threat-model.md) |
| TPM/custody hardening plan | [docs/tpm-cocoon-security-plan.md](docs/tpm-cocoon-security-plan.md) |
| Cross-platform reliability plan | [docs/everyone-plan.md](docs/everyone-plan.md) |
| Coverage to 100% plan | [docs/coverage-100-plan.md](docs/coverage-100-plan.md) |
| Daily blackbox report template | [docs/blackbox-daily-report-template.md](docs/blackbox-daily-report-template.md) |
| Security evidence requirements | [docs/security-evidence-manifest.md](docs/security-evidence-manifest.md) |

## Examples (Context + Heartbeat)

- [examples/01-autonomous-inbox-management/context.md](examples/01-autonomous-inbox-management/context.md)
- [examples/01-autonomous-inbox-management/heartbeat.md](examples/01-autonomous-inbox-management/heartbeat.md)
- [examples/02-morning-briefings-digests/context.md](examples/02-morning-briefings-digests/context.md)
- [examples/02-morning-briefings-digests/heartbeat.md](examples/02-morning-briefings-digests/heartbeat.md)
- [examples/03-calendar-scheduling-task-management/context.md](examples/03-calendar-scheduling-task-management/context.md)
- [examples/03-calendar-scheduling-task-management/heartbeat.md](examples/03-calendar-scheduling-task-management/heartbeat.md)
- [examples/04-personal-family-executive-assistance/context.md](examples/04-personal-family-executive-assistance/context.md)
- [examples/04-personal-family-executive-assistance/heartbeat.md](examples/04-personal-family-executive-assistance/heartbeat.md)
- [examples/05-research-summarization-monitoring/context.md](examples/05-research-summarization-monitoring/context.md)
- [examples/05-research-summarization-monitoring/heartbeat.md](examples/05-research-summarization-monitoring/heartbeat.md)

## Developer quick commands

- Build: `cargo build --release`
- Test: `cargo test --all`
- Strict lint: `cargo clippy --all-targets --all-features -- -D warnings`
- Coverage: `cargo llvm-cov --workspace --tests --lcov --output-path lcov.info`

### License

MIT