☕ Caffeinator (Checkpoint Bot)#

A Discord bot for accountability and goal tracking

📖 About#

Caffeinator is a Discord bot for accountability groups. Create scheduled checkpoints, set goals, and track progress together.

✨ Features#

📅 Checkpoint Management: Create scheduled checkpoints with date/time support
🎯 Goal Tracking: Set and manage goals, mark status (completed/incomplete/failed)
⏰ Timezone Support: Automatic timezone handling per server
👥 Multi-Server Support: Works across multiple Discord servers
⚡ Lightweight: Built with Go—idles at 10-12MB RAM usage. (Unlike similar nodejs apps)
📦 Portable Binary: Database migrations are embedded—just build and run the binary anywhere, no external files needed.

🛠️ Tech Stack#

Language: Go 1.25+
Discord API: discordgo
Database: SQLite with sqlc for type-safe queries (no ORM, just SQL)
Migrations: goose
Logging: charmbracelet/log
CLI: Cobra

🚀 Hosting#

Prerequisites#

Discord bot token from Discord Developer Portal
Docker (for Docker deployment) or Go 1.25+ (for building from source)

Option 1: Docker#

Deploy using Docker for easy containerized hosting:

git clone https://github.com/metruzanca/checkpoint-bot.git
cd checkpoint-bot

docker build -t caffeinator .
docker run -d \
  --name caffeinator \
  -e TOKEN="your-bot-token" \
  -v caffeinator-data:/app/db \
  caffeinator

Option 2: Standalone Binary#

Build and run the binary directly—perfect for VPS, dedicated servers, or any Linux/Windows/macOS system:

git clone https://github.com/metruzanca/checkpoint-bot.git
cd checkpoint-bot
go mod download
go generate ./...
go build -o checkpoint-bot .

# Run the binary
./checkpoint-bot --TOKEN="your-bot-token"

Benefits of the standalone binary:

Completely self-contained—migrations are embedded, no external files needed
Portable—move the binary anywhere and run it directly
Lightweight—single executable, no runtime dependencies
Database auto-created at DB_PATH (default: ./db/checkpoint.db)

💻 For Developers#

Building from Source#

git clone https://github.com/metruzanca/checkpoint-bot.git
cd checkpoint-bot
go mod download
go generate ./..
go build .
./checkpoint-bot --TOKEN="your-bot-token" # TOKEN can also be in .env file or env variable if you prefer

Configuration Options#

TOKEN - Discord bot token (required)
CLIENT_ID - Discord application client ID (for invite links)
DB_PATH - Path to SQLite database file (default: ./db/checkpoint.db)
CHANNEL_ID - Optional channel ID for startup notifications
STARTUP_MESSAGE - Enable/disable startup messages (default: true)

📚 Usage#

Commands#

/checkpoint - Create a scheduled checkpoint
- date (required): YYYY-MM-DD format
- time (required): HH:MM or H:MM AM/PM format
- Example: /checkpoint date:2024-01-15 time:7:00 PM
/goal - Set or edit goals for upcoming checkpoint
- user (optional): User whose goals to edit (admin only)
- status (optional): completed, incomplete, or failed
/next - View next upcoming checkpoint and goals

🏗️ Project Structure#

checkpoint-bot/
├── cmd/                    # CLI commands
├── internal/
│   ├── config/            # Configuration
│   ├── database/          # Database layer (sqlc + goose migrations)
│   ├── server/            # Bot & Discord command handlers
│   └── util/              # Utilities
└── main.go                # Entry point

Key Points: SQL queries in queries.sql (generated by sqlc), commands in internal/server/commands/, migrations in internal/database/migrations/

🧪 Development#

Adding a Command#

Create file in internal/server/commands/
Define ApplicationCommand and Handler
Register in init() with registerCommand()
Use dbContext() for database ops (with defer cancel())

Adding a Database Query#

Add query to internal/database/queries/queries.sql
Use :one for Create (returns record), :exec for Update/Delete
Run go generate ./... to regenerate sqlc code
Add method to CheckpointDatabase interface and implement in SQLite

Migrations#

Create NNNNN_name.sql in internal/database/migrations/ with -- +goose Up and -- +goose Down sections. Migrations run automatically on startup.

📚 Resources#

📝 License#

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

_{Built with ☕ and ❤️ for accountability groups everywhere}

Configure Feed