🦞 GroupMe Claw Bot

An AI-powered group chat member that blends in with your crew. It summarizes articles, fact-checks claims, generates images, and creates friendly chaos — all while adapting to your group's communication style.

Powered by: ChatGPT (conversation) + Gemini (image generation)
Deployed on: Railway
Inspired by: OpenClaw

---

What It Does

Feature	How to trigger	Example
Conversation	Mention @claw or the bot name	@claw what do you think about that?
Article Summary	Share a URL (auto-detects)	Just paste a link — bot reads + summarizes it
Fact Check	@claw fact check [claim]	@claw fact check the earth is 6000 years old
Image Generation	@claw generate/draw/create [description]	@claw draw a lobster riding a motorcycle
Random Chime-ins	Automatic (~8% chance)	Bot decides if the convo is worth jumping into

The bot learns your group's tone (slang level, humor, formality, emoji usage) and adapts its personality to match. It's not a helpful assistant — it's a friend with opinions.

---

Setup Guide

1. Create a GroupMe Bot

1. Go to dev.groupme.com and log in
2. Click Bots → Create Bot
3. Select your group chat
4. Set a name (e.g., "Claw") and optional avatar
5. Leave Callback URL blank for now (you'll update it after Railway deploy)
6. Save — note down your Bot ID
7. Your Access Token is shown at the top of the bots page

2. Get API Keys

OpenAI (ChatGPT):

• Go to platform.openai.com/api-keys
• Create a new API key
• Fund your account (GPT-4o costs ~$2.50/1M input tokens)

Google Gemini:

• Go to aistudio.google.com/apikey
• Create an API key
• Gemini image generation is free tier eligible

3. Deploy to Railway

Option A: One-click from GitHub

1. Push this code to a GitHub repo
2. Go to railway.app → New Project → Deploy from GitHub repo
3. Select your repo
4. Go to Variables tab and add all env vars from .env.example
5. Railway auto-deploys and gives you a public URL

Option B: Railway CLI

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Init project
railway init

# Set environment variables
railway variables set GROUPME_BOT_ID=your_bot_id
railway variables set GROUPME_ACCESS_TOKEN=your_access_token
railway variables set GROUPME_GROUP_ID=your_group_id
railway variables set OPENAI_API_KEY=sk-your-key
railway variables set GEMINI_API_KEY=your-gemini-key
railway variables set BOT_NAME=Claw
railway variables set BOT_MENTION_TRIGGER=@claw
railway variables set RESPOND_CHANCE=0.08

# Deploy
railway up

4. Connect GroupMe to Railway

1. After deploy, Railway gives you a URL like https://groupme-claw-bot-production-xxxx.up.railway.app
2. Go back to dev.groupme.com/bots
3. Edit your bot → set Callback URL to your Railway URL (just the root, e.g., https://your-app.up.railway.app)
4. Save

5. Test It

Send a message in your GroupMe group:

@claw hey what's good

Check Railway logs to confirm messages are being received.

---

Environment Variables

Variable	Required	Description
GROUPME_BOT_ID	✅	Bot ID from dev.groupme.com
GROUPME_ACCESS_TOKEN	✅	Your GroupMe access token
GROUPME_GROUP_ID	✅	The group's ID (visible in group URL or API)
OPENAI_API_KEY	✅	OpenAI API key for ChatGPT
GEMINI_API_KEY	✅	Google AI API key for image generation
OPENAI_MODEL	❌	Model to use (default: gpt-4o, cheaper: gpt-4o-mini)
BOT_NAME	❌	Bot's display name (default: Claw)
BOT_MENTION_TRIGGER	❌	How to summon it (default: @claw)
RESPOND_CHANCE	❌	Random chime-in probability 0.0-1.0 (default: 0.08)
PORT	❌	Server port (Railway sets this automatically)

---

How the Personality Works

The bot maintains a rolling memory of the last 80 messages and continuously analyzes the group's communication patterns:

• Slang density — detects "bruh", "ngl", "bet", "fr", etc.
• Humor level — tracks "lol", "lmao", "💀", "haha"
• Formality — proper punctuation, capitalization patterns
• Emoji usage — how often the group uses emojis
• Message length — are people writing essays or one-liners?
• Profanity — adjusts its own language filter accordingly

This data feeds into a dynamic system prompt that adapts ChatGPT's personality in real-time. The bot will literally text differently in a professional group vs. a friend group.

---

Architecture

GroupMe Group Chat
    │
    ▼ (webhook POST on every message)
┌──────────────────┐
│   Express Server  │ ← Railway
│   (index.js)      │
├──────────────────┤
│ Intent Router     │
│  ├─ @mention?     │──→ Conversation (ChatGPT)
│  ├─ URL shared?   │──→ Scrape + Summarize (ChatGPT)
│  ├─ Fact check?   │──→ Verify claim (ChatGPT)
│  ├─ Image req?    │──→ Generate image (Gemini) → Upload to GroupMe Image Service
│  └─ Random?       │──→ Should I chime in? (GPT-4o-mini) → Conversation
├──────────────────┤
│ Memory System     │
│  ├─ Chat history  │
│  ├─ User profiles │
│  └─ Tone analysis │
└──────────────────┘

---

Cost Estimate

With moderate group chat activity (~100-200 messages/day where the bot responds to ~20):

Service	Monthly Cost
Railway	~$5 (Hobby plan)
OpenAI GPT-4o	~$2-5
OpenAI GPT-4o-mini (chime-in decisions)	~$0.10
Gemini	Free tier covers most usage
Total	~$7-10/month

Use gpt-4o-mini as the main model to cut costs to ~$3-5/month total.

---

Customization

Make it more/less chatty:

RESPOND_CHANCE=0.15   # 15% = very chatty
RESPOND_CHANCE=0.03   # 3% = mostly quiet, speaks when spoken to

Change personality:
Edit the buildSystemPrompt() function in lib/brain.js. The CORE IDENTITY section defines who the bot is.

Add new capabilities:
Add new intent detection in index.js and handler functions. The pattern is:

1. Detect intent in the router
2. Process with the appropriate module
3. Send response via groupme.sendMessage()

---

Monitoring

Hit your Railway URL in a browser to see the health dashboard:

{
  "status": "🦞 Claw is alive",
  "uptime": 3600,
  "messagesProcessed": 142,
  "groupTone": {
    "formality": 0.25,
    "humor": 0.7,
    "slang": 0.6,
    "avgLength": 35,
    "emoji": 0.4,
    "profanity": 0.15
  }
}

---

License

MIT — do whatever you want with it. 🦞