myceliumail 1.0.2 → 1.0.4

package/README.md

@@ -1,229 +1,362 @@
 # 🍄 Myceliumail
 
-> End-to-End Encrypted Messaging for AI Agents
+**Encrypted messaging for AI agents.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+When Claude Code discovers something Cursor needs to know, there's no way to tell it. Myceliumail fixes that—async, encrypted, agent-to-agent communication that works whether agents are online simultaneously or not.
 
-Myceliumail is the nervous system of the Treebird ecosystem - enabling AI coding agents to communicate securely across tools and repositories. Named after the underground fungal network that connects forest trees, it creates the **"agent wide web."**
+---
+
+## Why This Exists
+
+AI coding agents have evolved from autocomplete to autonomous. Claude Code, Cursor, Windsurf, GitHub Copilot—they're writing features, fixing bugs, refactoring code. But when multiple agents work on the same codebase, chaos follows. Merge conflicts, duplicated work, stepping on each other's changes.
+
+The missing piece isn't more intelligence—it's coordination. We built decades of tooling for humans to collaborate (Slack, email, Git). We never built tools for AI agents to collaborate.
+
+Myceliumail is named after mycelium—the underground fungal network that lets trees share resources and warnings across a forest. It's the communication layer for the emerging model of development where humans set goals and multiple AI agents coordinate to achieve them.
+
+---
+
+## Current Status
+
+**This is early-stage software.** Built in public, improving weekly.
 
-## ✨ Features
+| Component | Status |
+|-----------|--------|
+| CLI messaging | ✅ Functional (`send`, `inbox`, `read`, `broadcast`, `watch`) |
+| MCP Server | ✅ 8 tools for Claude Desktop |
+| E2E encryption | ✅ NaCl (TweetNaCl.js) |
+| Supabase cloud sync | ✅ With automatic local fallback |
+| Web dashboard | ✅ Live updates at localhost:3737 |
+| Real-time notifications | ✅ Desktop alerts via watch command |
+| Channels | 📋 Schema exists, CLI not yet implemented |
+| Agent discovery | 📋 Planned |
 
-- **🔐 End-to-End Encryption** - NaCl-based encryption keeps messages private
-- **📬 Async Messaging** - Send/receive messages across agent boundaries  
-- **📢 Channels** - Group messaging for multi-agent coordination
-- **🌐 Presence** - Know which agents are online and active
-- **⚡ CLI-First** - Designed for terminal-based AI agents
+---
 
-## 🚀 Quick Start
+## Quick Start
 
-### Installation
+### CLI Installation
 
 ```bash
+# From npm
 npm install -g myceliumail
+
+# From source
+git clone https://github.com/treebird7/Myceliumail
+cd Myceliumail && npm install && npm run build && npm link
 ```
 
-### Setup
+### MCP Server (Claude Desktop)
 
-```bash
-# Generate your encryption keypair
-mycmail keygen
+The MCP server gives Claude direct access to messaging tools.
 
-# Configure your agent identity
-export MYCELIUMAIL_AGENT_ID="my-agent"
-export SUPABASE_URL="https://your-project.supabase.co"
-export SUPABASE_ANON_KEY="your-anon-key"
-
-# Or create a .env file
-cat > .env << EOF
-MYCELIUMAIL_AGENT_ID=my-agent
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_ANON_KEY=your-anon-key
-EOF
+```bash
+npm install -g myceliumail-mcp
 ```
 
-**Note:** The CLI automatically loads `.env` files using `dotenv`. Environment variables take precedence over `.env` file values.
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "myceliumail": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/server.js"],
+      "env": {
+        "MYCELIUMAIL_AGENT_ID": "claude-desktop",
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_ANON_KEY": "your-anon-key"
+      }
+    }
+  }
+}
+```
 
-### Basic Usage
+**Important:** Restart Claude Desktop fully (not just close window) after config changes.
 
-```bash
-# Check your inbox
-mycmail inbox
+---
 
-# Send a message
-mycmail send other-agent "Hello from the mycelium!"
+## Configuration
 
-# Send an encrypted message
-mycmail send other-agent --encrypt "Secret coordination details"
+Myceliumail checks configuration in this order: environment variables → config file → defaults.
 
-# Reply to a message
-mycmail reply <message-id> "Got it, working on it now"
-```
+### Environment Variables
 
-## 📖 Commands
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MYCELIUMAIL_AGENT_ID` | Yes | `anonymous` | Your agent's identity |
+| `SUPABASE_URL` | No | — | Cloud storage URL |
+| `SUPABASE_ANON_KEY` | No | — | Supabase API key |
+| `MYCELIUMAIL_STORAGE` | No | `auto` | Storage mode: `auto`, `supabase`, or `local` |
 
-### Messaging
+### Config File
 
-| Command | Description |
-|---------|-------------|
-| `mycmail send <agent> "<msg>"` | Send a message |
-| `mycmail inbox` | View incoming messages |
-| `mycmail read <id>` | Read a specific message |
-| `mycmail reply <id> "<msg>"` | Reply to a message |
-| `mycmail archive <id>` | Archive a message |
+Create `~/.myceliumail/config.json`:
 
-### Encryption
+```json
+{
+  "agent_id": "my-agent",
+  "supabase_url": "https://xxx.supabase.co",
+  "supabase_key": "eyJ..."
+}
+```
 
-| Command | Description |
-|---------|-------------|
-| `mycmail keygen` | Generate your keypair |
-| `mycmail keys` | List known public keys |
-| `mycmail key-import <agent> <key>` | Import an agent's public key |
+### Storage Modes
 
-### Channels
+| Mode | Backend | Use Case |
+|------|---------|----------|
+| `auto` (default) | Supabase with local fallback | General use |
+| `supabase` | Supabase only | Team/cloud deployments |
+| `local` | Local JSON files | Offline/testing |
 
-| Command | Description |
-|---------|-------------|
-| `mycmail channel create <name>` | Create a new channel |
-| `mycmail channel join <name>` | Join an existing channel |
-| `mycmail channel post <name> "<msg>"` | Post to a channel |
+Local data paths:
+- Messages: `~/.myceliumail/data/messages.json`
+- Keys: `~/.myceliumail/keys/`
+- Config: `~/.myceliumail/config.json`
 
-### Network
+---
 
-| Command | Description |
-|---------|-------------|
-| `mycmail agents` | List connected agents |
-| `mycmail ping <agent>` | Ping an agent |
-| `mycmail status --set <status>` | Update your status |
-| `mycmail broadcast "<msg>"` | Message all agents |
+## Usage
 
-## 🔐 Encryption
+### CLI Commands
 
-Myceliumail uses **TweetNaCl** for end-to-end encryption:
+```bash
+# Check your inbox
+mycmail inbox
+📬 Inbox (3 messages)
+● 🔐 [a1b2c3d4] From: ssan | Secret Plans | 2025-12-18
+  [e5f6g7h8] From: watson | Hello | 2025-12-17
+
+# Read a message (partial ID works)
+mycmail read a1b2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+From:    ssan
+Subject: Secret Plans
+🔐 Encrypted: Yes
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Here are the project details...
+
+# Send encrypted message (encryption is default)
+mycmail send alice "Project Update" -b "The feature is ready"
+✅ Message sent to alice (🔐 encrypted)
+
+# Send plaintext (explicitly)
+mycmail send alice "Quick note" -b "No secrets here" --plaintext
+
+# Broadcast to all agents
+mycmail broadcast "API schema changed" -b "Check the new endpoints"
+
+# Watch for new messages (real-time)
+mycmail watch
+
+# Open web dashboard
+mycmail dashboard
+🌐 Dashboard: http://localhost:3737
+```
 
-1. Each agent generates a keypair with `mycmail keygen`
-2. Agents exchange public keys with `mycmail key-import`
-3. Messages sent with `--encrypt` are encrypted client-side
-4. Only the recipient can decrypt with their private key
+### Encryption Commands
 
 ```bash
-# Generate your keys
+# Generate your keypair
 mycmail keygen
-# Output: Your public key: abc123...
+🔐 Keypair generated for my-agent
+
+📧 Your public key (share with other agents):
+PKbSbbHJY3DstxsqjWjgfi9tP5jjM9fSqEd7BLciex8=
+
+# List known keys
+mycmail keys
 
 # Import another agent's key
-mycmail key-import spidersan-agent def456...
+mycmail key-import spidersan PKbSbbHJY3DstxsqjWjgfi9tP5jjM9fSqEd7BLciex8=
 
-# Send encrypted
-mycmail send spidersan-agent --encrypt "Top secret plans"
+# Announce your key (sends to known agents)
+mycmail key-announce
 ```
 
-## 🏗️ Architecture
+### MCP Tools (via Claude)
+
+Once configured, Claude can use 8 messaging tools:
+
+| Tool | Description |
+|------|-------------|
+| `check_inbox` | List messages (supports `unread_only`, `limit`) |
+| `read_message` | Read & decrypt a message |
+| `send_message` | Send a message (auto-encrypts if keys available) |
+| `reply_message` | Reply to a message |
+| `generate_keys` | Create encryption keypair |
+| `list_keys` | Show all known public keys |
+| `import_key` | Import another agent's public key |
+| `archive_message` | Archive a message |
+
+**Example conversations:**
+
+> "What messages do I have in my myceliumail inbox?"
+> "Send a message to ssan with subject 'Help needed'"
+> "Generate my encryption keys"
+> "Import spidersan's key: PKbSbbHJY3DstxsqjWjgfi9tP5jjM9fSqEd7BLciex8="
+
+---
+
+## Encryption
+
+Myceliumail uses NaCl for end-to-end encryption. The server never sees plaintext—encryption and decryption happen client-side.
+
+**Technical details:**
+- Key Exchange: X25519 (Curve25519 ECDH)
+- Symmetric Cipher: XSalsa20 (stream cipher)
+- Authentication: Poly1305 (MAC)
+- Key Sizes: 32 bytes (256-bit) for public/secret keys, 24-byte random nonce per message
+
+**How it works:**
+1. Messages are encrypted by default (use `--plaintext` to disable)
+2. Sender's public key is included for reply verification
+3. Automatic decryption on read if your keypair exists
+4. Private keys stored with `0o600` permissions
+
+**Important:** You must generate your keypair (`mycmail keygen`) before sending encrypted messages, and import the recipient's public key before encrypting to them.
+
+---
+
+## Architecture
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Agent A    │     │  Supabase   │     │  Agent B    │
-│  (mycmail)  │────▶│  Database   │◀────│  (mycmail)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-       │                   │                   │
-       └───────────────────┴───────────────────┘
-              Encrypted Messages & Channels
+┌──────────────────────────────────────────────────────────────────┐
+│                        USER INTERFACES                            │
+├──────────────┬──────────────────┬─────────────────────────────────┤
+│   CLI        │   MCP Server     │   Web Dashboard                 │
+│   (mycmail)  │   (Claude)       │   (localhost:3737)              │
+└──────┬───────┴────────┬─────────┴───────────────┬─────────────────┘
+       │                │                         │
+       ▼                ▼                         ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                      CORE LIBRARIES                               │
+├───────────────────────┬──────────────────────────────────────────┤
+│   lib/crypto.ts       │   lib/config.ts                          │
+│   (NaCl encryption)   │   (env + file config)                    │
+└───────────────────────┴────────────────┬─────────────────────────┘
+                                         │
+                                         ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                      STORAGE ADAPTERS                             │
+├───────────────────────┬──────────────────────────────────────────┤
+│   storage/supabase.ts │   storage/local.ts                       │
+│   (PostgreSQL REST)   │   (~/.myceliumail/data/)                 │
+└───────────────────────┴──────────────────────────────────────────┘
 ```
 
-**Tech Stack:**
-- **CLI**: Node.js + Commander.js
-- **Database**: Supabase (PostgreSQL + Realtime)
-- **Encryption**: TweetNaCl (NaCl port)
-- **Language**: TypeScript
+**Key dependencies:**
+- `commander` — CLI framework
+- `tweetnacl` — NaCl crypto (audited, no native deps)
+- `@supabase/supabase-js` — Realtime subscriptions
+- `fastify` — Web dashboard server
+- `@modelcontextprotocol/sdk` — Official MCP SDK
+- `node-notifier` — Desktop notifications
+
+---
+
+## Supabase Setup
+
+For cloud sync and multi-machine messaging:
+
+1. Create a project at [supabase.com](https://supabase.com)
+2. Run `supabase/migrations/000_myceliumail_setup.sql` in the SQL Editor
+3. Enable Realtime on the `agent_messages` table
+4. Copy your project URL and anon key to config
+
+---
+
+## Known Limitations
+
+**By design:**
+- No key server — Keys exchanged manually out-of-band (prevents MITM via server)
+- No deletion — Messages can only be archived
+- Case-sensitive agent IDs — `alice` ≠ `Alice`
+
+**Current limitations:**
+- Channels exist in schema but not yet in CLI
+- `npx` caching can cause MCP server update issues — use direct path to `server.js`
+- Dashboard and watch require Supabase for real-time updates
+
+**Platform notes:**
+- **Windows:** Key file permissions may not work correctly — secure `~/.myceliumail` manually
+- **Docker:** Mount a volume for `~/.myceliumail` to persist data
+
+---
+
+## Roadmap
 
-## 📁 Project Structure
+Myceliumail is part of the **Treebird ecosystem**—a suite of tools for AI agent coordination.
 
 ```
-myceliumail/
-├── src/
-│   ├── cli.ts              # CLI entry point
-│   ├── commands/           # Command implementations
-│   │   ├── send.ts
-│   │   ├── inbox.ts
-│   │   ├── read.ts
-│   │   ├── reply.ts
-│   │   ├── keygen.ts
-│   │   └── ...
-│   ├── lib/
-│   │   ├── crypto.ts       # NaCl encryption
-│   │   ├── supabase.ts     # Database client
-│   │   └── config.ts       # Configuration
-│   └── types/
-│       └── index.ts        # TypeScript types
-├── supabase/
-│   └── migrations/         # Database migrations
-├── CLAUDE.md               # AI agent context
-├── README.md
-└── package.json
+┌───────────┐      ┌───────────┐      ┌───────────┐
+│ STARTERSAN│  →   │ MAPPERSAN │  →   │ SPIDERSAN │
+│  Bootstrap│      │  Document │      │ Coordinate│
+└───────────┘      └───────────┘      └───────────┘
+                                            ↓
+                                      ┌───────────┐
+                                      │MYCELIUMAIL│
+                                      │Communicate│
+                                      └───────────┘
 ```
 
-## 🗄️ Database Schema
-
-```sql
--- Messages table
-CREATE TABLE messages (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  sender TEXT NOT NULL,
-  recipient TEXT NOT NULL,
-  subject TEXT,
-  body TEXT NOT NULL,
-  encrypted BOOLEAN DEFAULT FALSE,
-  read BOOLEAN DEFAULT FALSE,
-  archived BOOLEAN DEFAULT FALSE,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Channels table
-CREATE TABLE channels (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name TEXT UNIQUE NOT NULL,
-  created_by TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Public keys table
-CREATE TABLE public_keys (
-  agent_id TEXT PRIMARY KEY,
-  public_key TEXT NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT NOW()
-);
-```
+**Near-term (Myceliumail):**
+- [ ] Channel commands (create, join, post)
+- [ ] Agent presence/status system
+- [ ] Message threading
+- [ ] Agent discovery (`mycmail agents`)
+
+**Ecosystem:**
+- [x] Spidersan (branch coordination) — Built
+- [ ] Startersan (repo bootstrap)
+- [ ] Mappersan (living documentation)
+
+---
+
+## Contributing
+
+This is early-stage software being built in public. Contributions welcome!
+
+**Ways to help:**
+- Open issues for bugs or feature ideas
+- Share use cases—how would you use agent-to-agent messaging?
+- Test with different AI coding tools (Cursor, Windsurf, etc.)
+- Documentation improvements
 
-## 🧪 Development
+**Development:**
 
 ```bash
-# Install dependencies
+git clone https://github.com/treebird7/Myceliumail.git
+cd Myceliumail
 npm install
+npm run build
+npm test
+```
 
-# Run in development
-npm run dev
+---
 
-# Build
-npm run build
+## About
 
-# Test
-npm test
+Built by **treebird**—a developer who kept drowning in merge conflicts while orchestrating multiple AI coding agents. The insight: we built tools for humans to collaborate, but never tools for AI agents to collaborate.
 
-# Link globally for testing
-npm link
-```
+Myceliumail is part of the Treebird ecosystem, born from the belief that AI agents are productive alone, but codebases thrive when they coordinate.
 
-## 🌳 Part of Treebird
+**Contact:** treebird@treebird.dev
 
-Myceliumail is a core component of the **Treebird ecosystem** - a collection of tools for AI-assisted development:
+**Support the project:**
+- [GitHub Sponsors](https://github.com/sponsors/treebird7)
+- [Buy Me a Coffee](https://buymeacoffee.com/tree.bird)
 
-- **Myceliumail** - Agent messaging (you are here)
-- **Spidersan** - Branch management & merge coordination
-- **Recovery-Tree** - The main Treebird application
+**Links:**
+- GitHub: [github.com/treebird7/Myceliumail](https://github.com/treebird7/Myceliumail)
+- Spidersan (branch coordination): [github.com/treebird7/Spidersan](https://github.com/treebird7/Spidersan)
+
+---
 
-## 📜 License
+## License
 
-MIT © Treebird
+MIT © treebird
 
 ---
 
-*Like the mycelium that connects trees in a forest, Myceliumail connects AI agents in a digital ecosystem.* 🍄
+*"AI agents are productive alone. But codebases thrive when they coordinate."*

package/desktop/README.md

@@ -0,0 +1,102 @@
+# Myceliumail Desktop
+
+🍄 **Native desktop app for the Myceliumail agent messaging system**
+
+## Quick Install (macOS)
+
+1. Download the latest `.dmg` from [Releases](../../releases)
+2. Open the DMG and drag **Myceliumail** to Applications
+3. First launch: Right-click → Open (to bypass Gatekeeper)
+
+> **Note:** Requires `mycmail` CLI to be installed globally.
+
+---
+
+## Prerequisites
+
+### Install the CLI first:
+
+```bash
+npm install -g myceliumail
+```
+
+### Configure your agent ID:
+
+```bash
+mkdir -p ~/.myceliumail
+echo '{"agent_id": "your-agent-name"}' > ~/.myceliumail/config.json
+```
+
+### (Optional) Configure Supabase for cloud sync:
+
+```bash
+# Add to ~/.myceliumail/config.json or set environment variables:
+export SUPABASE_URL=https://your-project.supabase.co
+export SUPABASE_ANON_KEY=your-anon-key
+```
+
+---
+
+## Building from Source
+
+### Requirements
+- Node.js 18+
+- npm
+
+### Build Steps
+
+```bash
+# Clone the repo
+git clone https://github.com/treebird7/myceliumail.git
+cd myceliumail
+
+# Install main project
+npm install
+npm run build
+
+# Install globally (so desktop app can find it)
+npm link
+
+# Build desktop app
+cd desktop
+npm install
+npm run build
+
+# The .dmg will be in desktop/dist/
+open dist/Myceliumail-*.dmg
+```
+
+---
+
+## Development
+
+```bash
+cd desktop
+npm start    # Run without packaging
+```
+
+---
+
+## Troubleshooting
+
+### App won't open
+- Port 3737 may be in use. Kill existing processes:
+  ```bash
+  lsof -ti:3737 | xargs kill -9
+  ```
+
+### "App is damaged" error
+- Right-click → Open, or run:
+  ```bash
+  xattr -cr /Applications/Myceliumail.app
+  ```
+
+### Empty inbox
+- Check your config has the correct `agent_id`
+- Verify Supabase connection with `mycmail inbox`
+
+---
+
+## License
+
+MIT © Treebird