🪲 Beetlebot — Your Autonomous Life Agent

IT DOESN'T SUGGEST PLANS. IT HANDLES THEM.

Quickstart · How it works · CLI · Docs · The Colony · Discord

Beetlebot is an open-source AI agent that autonomously plans your social life, weekend adventures, travel, and downtime. It reads your calendar, watches the weather, understands the season, knows your budget, learns your taste — and acts. Not a chatbot you talk at. A personal assistant that works for you.

Other tools give you text. Beetlebot gives you your time back.

The first time you wake up to a fully planned weekend you didn't have to think about — that's the moment. This is what AI was supposed to feel like.

Highlights

Autonomous by default — Beetlebot doesn't wait for you to ask. It monitors your calendar, checks the forecast, and acts when the moment is right. You set the goal once — it takes it from there.
Autopilots — goal + trigger + action. "Empty Weekend + Rain" fires Friday at noon and books an indoor plan before you even open your phone.
Packs — community-built planning skills for your city. Toronto Date Night. Rainy Day Rescue. Cottage Weekend. Install a pack or build your own.
Modes — Auto picks the best planning type by default, or switch to Explore, Date Night, Family, Social, Travel, Relax, or Focus. Different priorities, different actions, same intelligence.
Memory — learns your preferences, remembers your history, and gets better over time. Local-first — your data never leaves your machine.
Multi-channel — talks to you on web chat, Telegram, WhatsApp. Meets you where you already are.
Soft-holds — proactively reserves time on your calendar, then follows through. No more "I should have booked that."
Smart guardrails — you control what runs on autopilot and what needs a thumbs-up. Full audit trail on every action.

How it works

   Telegram / WhatsApp / Web Chat
                │
                ▼
  ┌──────────────────────────────┐
  │       Beetlebot Runtime      │
  │     Next.js + TypeScript     │
  │    http://localhost:3000     │
  └──────────────┬───────────────┘
                 │
    ┌────────────┼────────────────┐
    │            │                │
    ▼            ▼                ▼
 Autopilot    Plan            Memory
  Engine     Compiler          Layer
    │            │                │
    ├── Triggers ├── Packs        ├── Profile
    ├── Scheduler├── Modes        ├── Taste
    └── Runs     └── Soft-holds   ├── Logistics
                                  └── History
                 │
    ┌────────────┼────────────────┐
    │            │                │
    ▼            ▼                ▼
 Calendar     Weather        Guardrails
 (Google)    (context)      (you control)

Quickstart

Runtime: Node >= 18.

git clone https://github.com/richardsondx/beetlebot.git
cd beetlebot
npm install
cp .env.example .env   # then fill in your keys (see below)
npm run db:push         # push schema to local SQLite
npm run dev

Open http://localhost:3000.

That's it. The beetle is alive.

Environment variables

Copy .env.example to .env and configure:

# Required for local dev and self-host
DATABASE_URL="file:./dev.db"
ENCRYPTION_KEY="<generate with: openssl rand -base64 32>"

# Required — at least one AI provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...

Only needed when you want public callbacks/webhooks (OAuth, WhatsApp, Telegram webhooks):

NEXT_PUBLIC_APP_URL="https://xxxx.ngrok-free.app"
BEETLEBOT_BASE_URL="https://xxxx.ngrok-free.app"

Self-hosting (private panel + public callbacks)

Recommended model:

Keep Beetlebot private on the server (127.0.0.1:48653)
Expose only callback/webhook paths through a local edge (127.0.0.1:8787)
Tunnel the edge with ngrok (temporary or stable hostname)

This keeps the admin panel off the public internet while still enabling integrations like Google Calendar and WhatsApp.

For the full step-by-step setup (Caddy allowlist, ngrok config, systemd services, and verification), see:

Self-hosting guide

Database

Beetlebot uses SQLite (via Prisma) — zero config, local-first.

npm run db:push        # Push schema to local SQLite
npm run prisma:generate # Generate Prisma client

Encryption

Sensitive integration credentials (OAuth tokens, API keys) are encrypted at rest in the database using AES-256-GCM. Generate your key once and keep it in .env:

openssl rand -base64 32
# paste the output as ENCRYPTION_KEY in .env

CLI

Beetlebot ships with a full CLI and interactive TUI.

npm run cli -- --help

Key commands

beetlebot tui                              # Interactive terminal UI
beetlebot dev                              # Dev mode
beetlebot autopilot list                   # List autopilots
beetlebot autopilot run <id>               # Run an autopilot
beetlebot pack list                        # List installed packs
beetlebot pack install <slug>              # Install a community pack
beetlebot approvals list                   # Pending approvals
beetlebot memory list --bucket taste       # Inspect memory
beetlebot integrations list                # Integration status
beetlebot integrations connect telegram    # Connect Telegram
beetlebot svc restart                      # Restart beetlebot systemd service
beetlebot svc status ngrok                 # Check ngrok systemd service status
beetlebot svc endpoint                     # Print active ngrok public URL(s)

TUI commands

Launch with beetlebot tui, then use:

Command	Description
`/help`	Show all commands
`/status`	Session status
`/model set <provider/model>`	Switch AI model
`/autopilots`	List autopilots
`/packs`	Browse packs
`/runs`	Recent autopilot runs
`/approvals`	Pending approvals
`/memory [bucket]`	Inspect memory
`/connect <provider>`	Connect integration
`/new`	New conversation
`/context show`	Toggle context overlay

TUI keys: Enter submit, Ctrl+K toggle context, Ctrl+L clear, Ctrl+C quit.

Core concepts

Autopilots

Tell the beetle what you care about. It figures out the when, the how, and the follow-through.

"Plan a date night when Saturday is open and weather is good"
  → Goal:    Date night
  → Trigger: Saturday free + clear forecast
  → Action:  Generate plan, hold calendar, book restaurant
  → Result:  You wake up Saturday with a plan ready to go

Trigger classes:

Time triggers — cron-backed schedules (e.g., every Friday at noon).
Context triggers — reacts to real-world changes (calendar opens up, weather shifts, budget resets).
Event triggers — lifecycle events (booking fail, RSVP, birthday windows).

Packs

Community-curated capability bundles for life planning.

{
  "slug": "cottage-weekend-pack",
  "name": "Cottage Weekend Pack",
  "city": "Muskoka",
  "modes": ["family", "relax"],
  "budgetRange": "$120-$380",
  "description": "Plans cottage weekends with weather fallback, drive buffers, and grocery stop reminders."
}

Every city deserves a local expert. Build a pack, share it with the Colony.

Memory

Beetlebot remembers everything — your preferences, your history, what worked and what didn't. The more you use it, the better it gets. All stored locally on your machine.

Bucket	What the beetle learns
`profile_memory`	Who you are, your relationships, hard constraints
`taste_memory`	What you love, what you hate, your vibe
`logistics_memory`	How far you'll drive, your timing, budget defaults
`history_memory`	Past plans, outcomes, what landed and what flopped

You can inspect, correct, or wipe any memory at any time. Your data, your machine, your rules.

Soft-holds

The beetle proactively blocks time on your calendar when it spots an opportunity — then follows through with the full plan. No more "I should've booked that" moments.

Integrations

Google Calendar

Fully managed through the web UI — no env vars needed. Go to Settings, click Connect for Google Calendar, enter your OAuth client ID and secret, then sign in with Google. Beetlebot stores the credentials encrypted in the local database and handles token refresh automatically.

The OAuth callback URL is <your-base-url>/api/integrations/google-calendar/callback — register this in your Google Cloud Console.

# Or via CLI
beetlebot integrations connect google_calendar

Telegram

beetlebot integrations connect telegram --bot-token <TOKEN>
# Or in TUI: /connect telegram botToken=<TOKEN>

WhatsApp (Meta Cloud API)

beetlebot integrations connect whatsapp --access-token <TOKEN> --phone-number-id <ID>

API routes

Full REST API for building on top of Beetlebot.

Area	Endpoints
Chat	`POST /api/chat`
Autopilots	`GET/POST /api/autopilots`, `PATCH/DELETE /api/autopilots/:id`, `POST .../preview`, `POST .../run`
Packs	`GET/POST /api/packs`, `POST /api/packs/install`
Calendar	`GET /api/calendar/availability`, `POST/PATCH/DELETE /api/calendar/soft-holds`
Memory	`GET /api/memory`, `POST /api/memory/upsert`, `POST /api/memory/forget`
Approvals	`GET /api/approvals`, `POST /api/approvals/:id/approve\|reject`
Weather	`GET /api/weather/context`
Integrations	`GET/POST /api/integrations/:provider/connect\|disconnect\|test`
Scheduler	`GET /api/scheduler/jobs`, `POST /api/scheduler/reconcile`
Audit	`GET /api/audit`, `GET /api/debug/traces`

Stack

Layer	Tech
Framework	Next.js 16 (App Router)
Language	TypeScript
Styling	Tailwind CSS v4
Database	SQLite via Prisma
AI	OpenAI / Anthropic (configurable)
Tests	Vitest
CLI	Commander + tsx
Validation	Zod

Project structure

beetlebot/
├── app/                    # Next.js app (pages + API routes)
│   ├── (app)/              # App pages (chat, autopilots, calendar, packs, settings)
│   └── api/                # REST API routes
├── components/             # React components
├── lib/                    # Core runtime modules
│   ├── chat/               # Chat engine, safety, research loop
│   ├── runtime/            # Autopilot runner + scheduler
│   ├── repositories/       # Data access layer
│   ├── tools/              # Tool registry (weather, calendar, OpenTable)
│   ├── integrations/       # Channel adapters (Telegram, WhatsApp, Google)
│   └── weather/            # Weather service
├── packages/
│   ├── cli/                # CLI + TUI package
│   └── travel-cli/         # Travel planning CLI (Go)
├── prisma/                 # Database schema
├── docs/                   # Architecture + spec docs
└── tests/                  # Test suites

Development

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests
npm run lint         # Lint
npm run typecheck    # Type-check
npm run db:push      # Push Prisma schema

Docs

Deep reference docs live in docs/:

PRD — product requirements
Architecture — system design and phases
Autopilot Runtime — trigger classes, execution guarantees
Pack Spec — how to build a pack
Memory Model — buckets, governance, user controls
Plan Object Schema — the plan contract
API Routes — full endpoint reference
CLI — commands, TUI, integration setup

The Colony 🪲🪲🪲

Beetlebot isn't a product with a waitlist. It's a movement with a repo.

The Colony is the community building the autonomous life agent they actually want to use. No corporate roadmap. No feature gates. Just people who believe AI should handle the boring parts of life so you can live the interesting parts.

How to contribute

Build Packs — create planning skills for your city. Share local knowledge globally. Every city deserves a local expert.
Shape the roadmap — the best features come from real people with real weekends. Open issues, open PRs, open conversations.
Fork it. Own it. — open source means your agent, your rules. Self-host it, extend it, make it yours. No vendor lock-in. Ever.

See CONTRIBUTING.md for guidelines.

Community channels

Discord — join The Colony
GitHub Issues — bugs, features, ideas
GitHub Discussions — questions, show & tell

AI/vibe-coded PRs welcome.

Author

Built by Richardson Dackam (@richardsondx) while Beetlebot handled his weekends.

License

MIT — the beetle is free. Always.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.cursor		.cursor
.playwright-mcp		.playwright-mcp
app		app
components		components
docs		docs
lib		lib
packages		packages
prisma		prisma
public		public
tests		tests
.gitignore		.gitignore
.nvmrc		.nvmrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
promptfoo.eval.yaml		promptfoo.eval.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🪲 Beetlebot — Your Autonomous Life Agent

Highlights

How it works

Quickstart

Environment variables

Self-hosting (private panel + public callbacks)

Database

Encryption

CLI

Key commands

TUI commands

Core concepts

Autopilots

Packs

Memory

Soft-holds

Integrations

Google Calendar

Telegram

WhatsApp (Meta Cloud API)

API routes

Stack

Project structure

Development

Docs

The Colony 🪲🪲🪲

How to contribute

Community channels

Author

License

About

Uh oh!

Releases

Packages

Languages

License

richardsondx/beetlebot

Folders and files

Latest commit

History

Repository files navigation

🪲 Beetlebot — Your Autonomous Life Agent

Highlights

How it works

Quickstart

Environment variables

Self-hosting (private panel + public callbacks)

Database

Encryption

CLI

Key commands

TUI commands

Core concepts

Autopilots

Packs

Memory

Soft-holds

Integrations

Google Calendar

Telegram

WhatsApp (Meta Cloud API)

API routes

Stack

Project structure

Development

Docs

The Colony 🪲🪲🪲

How to contribute

Community channels

Author

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages