GREMLIN

Gremlin

Your chaotic little helper that gets things done.

Personal AI Agent Platform

Gremlin is a personal AI agent platform that lets users delegate real-world tasks to an autonomous AI assistant through the messaging apps they already use (Discord, Telegram, WhatsApp, Slack, SMS) while providing a polished dashboard for task management, oversight, and control.

Key Features

• Chat to Start, Dashboard to Manage — Messaging apps are the input layer. The dashboard is the control plane.
• Plan Before You Act — Agent proposes a plan, user confirms with one tap. No misfires.
• Graduated Autonomy — 4-tier delegation system from Notify to Autopilot.
• Structured Identity — Rich user model with editable preference graph.
• Secure by Default — Zero capabilities on install; mandatory auth; sandboxed skills.
• Observable Actions — Append-only audit trail; anomaly detection; daily digests.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        UI Layer                                 │
│     Web Dashboard  •  Mobile App  •  Desktop Tray App          │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                  Messaging Integration Layer                    │
│   Discord  •  Telegram  •  WhatsApp  •  Slack  •  SMS  •  Email│
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                       API Gateway                               │
│         REST + WebSocket  •  Auth  •  Rate Limiting            │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                      Agent Runtime                              │
│     LLM Orchestrator  •  Planning Engine  •  Tool Executor     │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                  Task & Workflow Engine                         │
│     Queue  •  Scheduler  •  State Machine  •  Temporal.io      │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                  Memory & User Model                            │
│    Preference Graph  •  Relationship Map  •  Routine Tracker   │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────────┐
│                       Data Layer                                │
│      PostgreSQL + pgvector  •  Redis  •  Object Storage        │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+
• Python 3.11+
• An LLM API key (Anthropic or OpenAI)

Setup

1. Clone the repository

   git clone https://github.com/yourusername/gremlin.git
   cd gremlin

2. Copy environment configuration

   cp .env.example .env

3. Configure your API keys

   Edit .env and add your LLM API key:

   ANTHROPIC_API_KEY=your_key_here
   # or
   OPENAI_API_KEY=your_key_here

4. Start the services

   docker-compose up -d

5. Access the dashboard

   Open http://localhost:3000 in your browser.

Connecting Messaging Platforms

Discord

1. Create a bot at https://discord.com/developers/applications
2. Add the bot token to .env:

   DISCORD_BOT_TOKEN=your_bot_token

3. Invite the bot to your server with message read/write permissions

Telegram

1. Create a bot via @BotFather on Telegram
2. Add the bot token to .env:

   TELEGRAM_BOT_TOKEN=your_bot_token

Project Structure

gremlin/
├── packages/
│   ├── gateway/          # API Gateway (Node.js/Fastify)
│   ├── agent/            # Agent Runtime (Python)
│   ├── shared/           # Shared types and utilities
│   ├── web/              # Web Dashboard (Next.js)
│   └── adapters/
│       ├── discord/      # Discord adapter
│       ├── telegram/     # Telegram adapter
│       ├── slack/        # Slack adapter
│       └── whatsapp/     # WhatsApp adapter (Twilio)
├── db/
│   └── migrations/       # PostgreSQL migrations
├── docker-compose.yml    # Service orchestration
└── package.json          # Root workspace config

Delegation Tiers

Tier	Behavior	Example
Notify	Agent monitors but only reports	Price drop alerts, news monitoring
Draft	Agent prepares output, user sends	Email replies, message responses
Do + Summarize	Agent acts, sends summary after	Calendar management, file org
Autopilot	Agent acts silently, logs only	Routine tasks, learned patterns

Security

Gremlin is designed with security as a core principle:

• Localhost-only by default — All services bind to 127.0.0.1
• Mandatory authentication — No auth: none option exists
• Credential encryption — Stored in OS keychain, never in plaintext
• Capability tokens — Scoped, time-limited, auditable
• Taint tracking — External data can't trigger actions without confirmation
• Audit logging — Append-only, queryable, exportable

API Reference

Tasks API

Method	Endpoint	Description
POST	/api/v1/tasks	Create a new task
GET	/api/v1/tasks	List tasks with filtering
GET	/api/v1/tasks/:id	Get task detail
PATCH	/api/v1/tasks/:id	Update task (approve plan, change tier)
DELETE	/api/v1/tasks/:id	Cancel a task

Memory API

Method	Endpoint	Description
GET	/api/v1/memory	Browse user model
GET	/api/v1/memory/:key	Get specific memory
PATCH	/api/v1/memory/:key	Update memory
DELETE	/api/v1/memory/:key	Delete memory

WebSocket

Connect to /api/v1/stream?token=<jwt> for real-time updates:

const ws = new WebSocket(`ws://localhost:3000/api/v1/stream?token=${token}`);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Handle events: task.created, task.plan.proposed, task.completed, etc.
};

Development

Install dependencies

npm install
cd packages/agent && pip install -e ".[dev]"

Run in development mode

# Start databases
docker-compose up -d gremlin-postgres gremlin-redis

# Run gateway
cd packages/gateway && npm run dev

# Run agent (in another terminal)
cd packages/agent && python -m src.main

# Run adapters (in other terminals)
cd packages/adapters/discord && npm run dev
cd packages/adapters/telegram && npm run dev
cd packages/adapters/slack && npm run dev
cd packages/adapters/whatsapp && npm run dev

Run tests

npm test
cd packages/agent && pytest

##thanks thanks team

License

MIT License — see LICENSE for details.