Proteus

An autonomous agent system that runs 24/7 as a daemon. Proteus is generic and modular—capable of handling any domain through pluggable modules. It receives messages via multiple channels (WhatsApp, Telegram), executes tasks, and learns from interactions.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    proteus-agent.service (:3480)            │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │   Daemon    │  │   Modules    │  │    Synthesis      │   │
│  │  (task loop)│  │  (pluggable) │  │  (auto-generate)  │   │
│  └─────────────┘  └──────────────┘  └───────────────────┘   │
│                           │                                 │
│  ┌────────────────────────▼─────────────────────────────┐   │
│  │              HTTP Server (:3480)                     │   │
│  │   Webhooks, RAG search, Semantic search, Dashboard   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                 proteus-channels.service (:3478)            │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │  WhatsApp   │  │   Telegram   │  │   (extensible)    │   │
│  └─────────────┘  └──────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Features

• Multi-Channel Communication — WhatsApp and Telegram support with unified API
• Parallel Task Execution — Up to 3 concurrent tasks with execution slots
• Pluggable Module System — Domain-specific handlers with lifecycle management
• Autonomy System:
  • Memory consolidation (extracts patterns from learnings)
  • Proactive learning (captures insights from completed tasks)
  • Goal decomposition (breaks complex tasks into subtasks with contracts)
  • Self-correction loops (analyzes failures, retries with adjustments)
• Module Synthesis — Auto-generates new modules for unknown domains
• Task Contracts — Scope boundaries with acceptance criteria verification
• Distributed Tracing — trace_id propagation across subtasks
• RAG & Semantic Search — Full-text and embedding-based message search

Project Structure

proteus/
├── agent/                  # Main agent daemon
│   └── src/
│       ├── daemon.ts       # Main loop
│       ├── task-runner.ts  # Task execution via Claude/Gemini
│       ├── database.ts     # SQLite with better-sqlite3
│       ├── autonomy.ts     # Intelligence layer
│       ├── modules/        # Pluggable domain handlers
│       └── synthesis/      # Module auto-generation
├── channels/               # Unified channels server
│   └── src/
│       ├── server.ts       # HTTP API server
│       └── adapters/       # WhatsApp, Telegram adapters
├── channels-mcp/           # MCP server for channels API
├── gmail-mcp/              # MCP server for Gmail API
├── data/                   # Runtime data (gitignored)
├── CLAUDE.md               # Claude Code instructions
├── GEMINI.md               # Gemini CLI instructions
└── .mcp.json               # MCP server configuration

Prerequisites

• Node.js 20+
• Claude CLI (claude) installed and authenticated
• Telegram Bot Token (for Telegram channel)
• WhatsApp Web session (for WhatsApp channel)

Installation

# Clone the repository
git clone <repo-url>
cd proteus

# Install dependencies
npm install

# Build all packages
npm run build

# Build MCP servers
cd channels-mcp && npm install && npm run build && cd ..
cd gmail-mcp && npm install && npm run build && cd ..

Configuration

Owner Profile

Create data/owner.json:

{
  "id": "owner_name",
  "name": "Your Name",
  "contact": {
    "primary": { "type": "telegram", "value": "YOUR_CHAT_ID" },
    "whatsapp": "YOUR_PHONE_NUMBER"
  },
  "locale": {
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "preferences": {
    "businessHours": { "start": 8, "end": 18, "workDays": [1,2,3,4,5] },
    "communicationStyle": "casual",
    "maxActionsPerTask": 50
  },
  "activeModules": ["developer", "assistant"]
}

Channels Configuration

Create data/channels.json:

{
  "webhook": {
    "url": "http://localhost:3480/webhook/channel"
  },
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_BOT_TOKEN"
  },
  "whatsapp": {
    "enabled": true
  }
}

Gmail (optional)

cd gmail-mcp
GMAIL_DATA_DIR=../data npm run auth

Running

Development

# Terminal 1: Channels server
npm run dev:channels

# Terminal 2: Agent daemon
npm run dev:agent

Production (systemd)

Create service files for proteus-agent and proteus-channels, then:

sudo systemctl enable proteus-channels proteus-agent
sudo systemctl start proteus-channels proteus-agent

HTTP Endpoints

Agent Server (:3480)

Endpoint	Description
GET /health	Health check
GET /dashboard	System state JSON
GET /rag/search?q=	Keyword search
GET /semantic/search?q=	Semantic search
GET /semantic/hybrid?q=	Combined search
POST /webhook/channel	Channel events webhook

Channels Server (:3478)

Endpoint	Description
GET /status	All channels status
GET /qr	WhatsApp QR code page
POST /send	Send message
GET /messages/:channel/:id	Read messages
GET /conversations/:channel	List conversations
GET /search/:channel?q=	Search contacts

MCP Tools

The agent uses MCP servers for external integrations:

• channels — Send/read messages via WhatsApp/Telegram
• gmail — Email operations (list, read, send, reply)

Development

# Build all
npm run build

# Build specific workspace
npm run build:agent
npm run build:channels

# Watch mode
npm run dev:agent
npm run dev:channels

License

MIT