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.
- 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.
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘
- Docker & Docker Compose
- Node.js 20+
- Python 3.11+
- An LLM API key (Anthropic or OpenAI)
-
Clone the repository
git clone https://github.com/yourusername/gremlin.git cd gremlin -
Copy environment configuration
cp .env.example .env
-
Configure your API keys
Edit
.envand add your LLM API key:ANTHROPIC_API_KEY=your_key_here # or OPENAI_API_KEY=your_key_here
-
Start the services
docker-compose up -d
-
Access the dashboard
Open http://localhost:3000 in your browser.
- Create a bot at https://discord.com/developers/applications
- Add the bot token to
.env:DISCORD_BOT_TOKEN=your_bot_token
- Invite the bot to your server with message read/write permissions
- Create a bot via @BotFather on Telegram
- Add the bot token to
.env:TELEGRAM_BOT_TOKEN=your_bot_token
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
| 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 |
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: noneoption 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
| 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 |
| 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 |
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.
};npm install
cd packages/agent && pip install -e ".[dev]"# 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 devnpm test
cd packages/agent && pytest##thanks thanks team
MIT License — see LICENSE for details.