meepo

<div align="center">

# Meepo

**A local AI agent that connects LLMs to your digital life.**

[![CI](https://github.com/leancoderkavy/meepo/actions/workflows/ci.yml/badge.svg)](https://github.com/leancoderkavy/meepo/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-2024_edition-orange.svg)](https://www.rust-lang.org/)
[![macOS](https://img.shields.io/badge/macOS-supported-brightgreen.svg)](#platform-support)
[![Windows](https://img.shields.io/badge/Windows-supported-brightgreen.svg)](#platform-support)

75+ tools · Discord · Slack · iMessage · Email · MCP · A2A · Autonomous Agent Loop

[Quick Start](#quick-start) · [Features](#features) · [Documentation](#configuration-reference) · [Contributing](CONTRIBUTING.md)

</div>

---

Meepo is an open-source, privacy-first AI agent written in Rust that runs as a daemon on your machine. It connects large language models (Claude, GPT-4, Gemini, Llama, Mistral) to your email, calendar, messages, browser, files, code, and more — all without sending your data to third-party agent platforms.

Think of it as a **local AI assistant that actually does things**: reads your email, schedules meetings, searches the web, automates your browser, monitors GitHub, manages reminders, and talks to you over Discord, Slack, or iMessage — all running on your own hardware.

### Why Meepo?

- **Runs locally** — Your data stays on your machine. No cloud agent platform required.
- **75+ tools out of the box** — Email, calendar, browser automation, web search, code PRs, knowledge graph, and more.
- **Works with any LLM** — Claude, GPT-4o, Gemini, Llama 3, Mistral, or any OpenAI-compatible API. Automatic failover between providers.
- **Always-on daemon** — Autonomous observe/think/act loop with scheduled watchers, proactive notifications, and goal tracking.
- **Interoperable** — Speaks [MCP](https://modelcontextprotocol.io/) and [A2A](https://google.github.io/A2A/) protocols. Plug into Claude Desktop, Cursor, or other AI agents.
- **Extensible** — Add custom tools, import SKILL.md files, swap agent personalities with templates, or connect external MCP servers.
- **Cross-platform** — macOS (AppleScript) and Windows (PowerShell/COM) with a clean platform abstraction layer.

---

## Quick Start

The fastest way to get running:

```bash
# macOS (Homebrew)
brew install leancoderkavy/tap/meepo
meepo setup    # Interactive wizard — walks you through API keys, permissions, and channels

# macOS / Linux (curl)
curl -sSL https://raw.githubusercontent.com/leancoderkavy/meepo/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/leancoderkavy/meepo/main/install.ps1 | iex
```

Then start the agent:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY, GOOGLE_AI_API_KEY
meepo start
```

> **No API key?** Use [Ollama](https://ollama.ai) for free local models — see [Using Ollama](#using-ollama-local-llms) below.

One-shot mode (no daemon needed):

```bash
meepo ask "What's on my calendar today?"
```

<details>
<summary><strong>More install options (DMG, from source)</strong></summary>

**macOS (DMG):**

Download the latest `.dmg` from the [Releases page](https://github.com/leancoderkavy/meepo/releases), open it, and drag **Meepo.app** to Applications. On first launch, the setup wizard opens automatically. Or build the DMG yourself:

```bash
git clone https://github.com/leancoderkavy/meepo.git && cd meepo
./installer/scripts/build-dmg.sh
open installer/dist/Meepo-*.dmg
```

See [installer/README.md](installer/README.md) for build options (universal binary, custom icon, etc.).

**From source (macOS/Linux):**
```bash
git clone https://github.com/leancoderkavy/meepo.git && cd meepo
cargo build --release && ./target/release/meepo setup
```

**From source (Windows PowerShell):**
```powershell
git clone https://github.com/leancoderkavy/meepo.git; cd meepo
cargo build --release; .\target\release\meepo.exe setup
```

</details>

## Features

| Category | Highlights |
|----------|-----------|
| **Messaging** | Discord, Slack, iMessage (macOS), email (macOS), CLI one-shots |
| **75+ Tools** | Email, calendar, reminders, notes, contacts, browser, web search, files, code PRs, music, screen capture, research, tasks, finance, health, travel, social |
| **Autonomous Loop** | Observe/think/act cycle, goal tracking, proactive notifications, quiet hours |
| **LLM Providers** | Anthropic Claude, OpenAI, Google Gemini, Ollama (local), any OpenAI-compatible endpoint — with automatic failover |
| **Browser Automation** | Safari + Chrome: tabs, navigation, JS execution, form filling, screenshots |
| **Knowledge Graph** | Persistent memory with SQLite + Tantivy full-text search across sessions |
| **Clone Delegation** | Spawn parallel sub-agents for complex tasks; background clones report back when done |
| **Watchers** | Monitor email, calendar, GitHub, files, or run cron tasks on a schedule |
| **MCP** | Expose tools as an MCP server (STDIO) for Claude Desktop / Cursor; consume external MCP servers |
| **A2A Protocol** | Google's Agent-to-Agent protocol for multi-agent task delegation over HTTP |
| **Remote Gateway** | WebSocket + REST server for mobile apps and external clients (Bearer auth, sessions) |
| **iOS App** | Native SwiftUI companion app — real-time chat, sessions, tool indicators |
| **Templates & Skills** | Swap agent personalities; import OpenClaw-compatible SKILL.md files as tools |
| **Security** | Command allowlists, path traversal protection, SSRF blocking, input sanitization, execution timeouts |

## Requirements

- **macOS** or **Windows**
- **At least one LLM provider:**

| Provider | How to get access |
|----------|-------------------|
| Anthropic Claude | API key from [console.anthropic.com](https://console.anthropic.com) |
| OpenAI | API key from [platform.openai.com](https://platform.openai.com/api-keys) |
| Google Gemini | API key from [aistudio.google.com](https://aistudio.google.com/apikey) |
| Ollama (local) | Free — [ollama.ai](https://ollama.ai). No API key needed. |
| OpenAI-compatible | Together, Groq, LM Studio, etc. |

- **Optional:** [Tavily](https://tavily.com) API key (enables `web_search` tool), Discord bot token, Slack bot token
- **Rust toolchain** only needed when building from source

### Using Ollama (Local LLMs)

Run models locally with zero API costs:

```bash
curl -fsSL https://ollama.ai/install.sh | sh   # Install Ollama
ollama pull llama3.2                             # Pull a model
```

Configure `~/.meepo/config.toml`:

```toml
[agent]
default_model = "ollama"

[providers.ollama]
base_url = "http://localhost:11434"
model = "llama3.2"
```

```bash
meepo start   # No API key needed — everything runs on your machine
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `meepo setup` | Interactive setup wizard (API keys, permissions, channels, connection test) |
| `meepo start` | Start the agent daemon |
| `meepo stop` | Stop a running daemon |
| `meepo ask "..."` | One-shot question (no daemon needed) |
| `meepo init` | Create `~/.meepo/` with default config |
| `meepo config` | Show loaded configuration |
| `meepo doctor` | Diagnose common issues |
| `meepo mcp-server` | Run as an MCP server over STDIO |
| `meepo template list\|use\|info\|reset\|create\|remove` | Manage agent templates |
| `meepo --debug <cmd>` | Enable debug logging |
| `meepo --config <path> <cmd>` | Use custom config file |

## Channels

Meepo monitors multiple messaging platforms simultaneously. Enable them in `~/.meepo/config.toml` or via `meepo setup`:

| Channel | Config Key | Requirements |
|---------|-----------|--------------|
| **Discord** | `[channels.discord]` | Bot token + `MESSAGE_CONTENT` intent ([Developer Portal](https://discord.com/developers/applications)) |
| **Slack** | `[channels.slack]` | Bot token with `chat:write`, `channels:read`, `im:history` ([api.slack.com](https:/

[truncated…]