🥚 EggAgent

Your personal AI that grows with you.

EggAgent is a self-improving AI agent framework that runs on your own devices. Private, fast, and local-first — you control your data. Talk to it from Telegram, Discord, Slack, WhatsApp, or any of 31 supported platforms. It learns from your conversations, creates new skills on its own, and remembers everything across sessions.

Features

🌐 31 Platform Adapters

Talk to your agent from anywhere:

Platform	Platform	Platform
Telegram	Discord	Slack
WhatsApp	Signal	Matrix
Mattermost	IRC	LINE
Microsoft Teams	Google Chat	Feishu/Lark
WeCom	DingTalk	Email
SMS/Twilio	Home Assistant	BlueBubbles (iMessage)
Nostr	Twitch	QQ Bot
Yuanbao	Weixin (WeChat)	Zalo
Nextcloud Talk	Synology Chat	Tlon (Urbit)
ClickClack	Raft	Generic Webhook
API Server

🧠 Self-Improving

• Skill Creation — Automatically creates skills from complex tasks
• Skill Improvement — Refines skills based on success/failure patterns
• Learning Loop — Observes sessions, extracts patterns, evolves capabilities
• Memory — Session store with context compression across conversations

🎤 Voice Support

• Speech-to-Text — Whisper integration for voice messages
• Text-to-Speech — OpenAI TTS for voice responses
• Mobile-Ready — Works with iPhone/Android voice assistants

🔌 Multi-LLM Support

• OpenAI — GPT-4o, o1, o3-mini
• Anthropic — Claude Opus 4, Sonnet 4
• Ollama — Llama, Mistral, Phi-3 (local)
• OpenRouter — Any model via API

🛠️ Built-in Tools

• Terminal execution (Local, Docker, SSH)
• Browser automation (Playwright)
• File operations
• Web search
• Code execution

⏰ Cron Scheduler

• Automated daily reports
• Scheduled tasks with interval parsing
• Enable/disable jobs on the fly

🔧 Plugin System

• 14 lifecycle hooks
• Hard boundary enforcement
• ClawHub compatible (clawhub.ai)

Quick Start

One-Line Install

macOS / Linux:

curl -fsSL https://eggagent.vercel.app/install.sh | bash

Windows (PowerShell):

powershell -c "irm https://eggagent.vercel.app/install.ps1 | iex"

npm:

npm install -g eggagent

Guided Setup

# Install EggAgent
npm install -g eggagent

# Run the setup wizard
eggagent setup

The wizard walks you through:

1. Choosing your LLM provider (OpenAI, Anthropic, Ollama, OpenRouter)
2. Connecting chat platforms (Telegram, Discord, Slack, etc.)
3. Enabling voice capabilities
4. Setting your agent's personality

Interactive Chat

# Start chatting
eggagent run

# Use a specific model
eggagent run --model claude-sonnet-4-20250514

Gateway Daemon

# Start the multi-platform gateway
eggagent gateway --port 18789

Architecture

eggagent/
├── packages/
│   ├── core/           # Agent Loop, Events, Prompt Builder
│   ├── llm/            # StreamFn, Provider Registry
│   ├── tools/          # Tool Planner, Tool Executor
│   ├── memory/         # Session Store, Context Compressor
│   ├── gateway/        # WebSocket Daemon + 31 Platform Adapters
│   ├── plugin-sdk/     # Plugin System (14 hooks)
│   ├── clawhub/        # ClawHub Client
│   ├── learning/       # Self-Improving Skills
│   ├── delegation/     # Multi-Agent System
│   ├── voice/          # STT + TTS (Whisper, OpenAI)
│   ├── cron/           # Task Scheduler
│   └── cli/            # CLI Entry Point
├── extensions/
│   ├── openai/         # OpenAI Provider
│   ├── anthropic/      # Anthropic Provider
│   ├── ollama/         # Ollama Provider
│   ├── terminal/       # Shell Execution (3 backends)
│   └── browser/        # Browser Automation
├── skills/             # Built-in Skills
└── workspace/          # Agent Workspace (SOUL.md, AGENTS.md)

Programmatic Usage

import { AgentLoop } from "@eggagent/core";
import { openaiProvider } from "@eggagent/extension-openai";

const agent = new AgentLoop({
  model: "gpt-4o",
  streamFn: openaiProvider.stream,
  tools: [],
});

for await (const event of agent.run("Hello!")) {
  if (event.type === "text") {
    process.stdout.write(event.text);
  }
}

Platform Setup Examples

Telegram

# 1. Create a bot via @BotFather
# 2. Get your bot token
# 3. Set environment variable
export TELEGRAM_BOT_TOKEN="your-token"

# 4. Start the gateway
eggagent gateway

Discord

# 1. Create a bot at discord.com/developers
# 2. Get your bot token
export DISCORD_TOKEN="your-token"

# 3. Start the gateway
eggagent gateway

WhatsApp

# 1. Set up Meta Cloud API
export WHATSAPP_PHONE_NUMBER_ID="your-id"
export WHATSAPP_TOKEN="your-token"

# 2. Start the gateway
eggagent gateway

Configuration

Environment Variables

# LLM Providers
OPENAI_API_KEY=your-key
ANTHROPIC_API_KEY=your-key

# Platform Tokens
TELEGRAM_BOT_TOKEN=your-token
DISCORD_TOKEN=your-token
SLACK_BOT_TOKEN=your-token
WHATSAPP_TOKEN=your-token

# Voice
OPENAI_API_KEY=your-key  # Used for both STT and TTS

# Gateway
EGGGATEWAY_PORT=18789
EGGGATEWAY_HOST=127.0.0.1

Config File

After running eggagent setup, your config is saved to ~/.eggagent/config.json:

{
  "name": "My EggAgent",
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "sk-..."
  },
  "platforms": {
    "telegram": "bot-token",
    "discord": "bot-token"
  },
  "voice": {
    "enabled": true,
    "apiKey": "sk-..."
  }
}

Personality

EggAgent has a warm, quirky egg personality defined in workspace/SOUL.md:

• Warm and approachable
• A little quirky (occasional egg puns)
• Curious and eager to learn
• Protective of your privacy
• Self-improving through tasks

"Crack open possibilities."

License

MIT