Clark

An all-in-one Discord bot for moderation, onboarding, engagement, and support — with an AI chatbot built in.

Source · Built with discord.py + PostgreSQL

---

What is Clark?

Clark is a general-purpose Discord bot that handles the things most servers need from a fleet of separate bots — moderation, automod, logging, welcome messages and an economy — in one place. It runs as an AutoShardedBot, so it's built to scale across many servers, and stores per-guild configuration in a PostgreSQL database.

Every feature is a self-contained cog that loads at startup, and commands are exposed as Discord slash commands. Clark also ships an AI chatbot (powered by Groq) with switchable personalities, so members can talk to him directly in chat.

This is the open-sourced code of Clark, released under the AGPL-3.0 license.

Features

• AI Chatbot — Groq-powered conversational AI with three switchable personalities (friendly, rude, strict), plus custom instructions per server or per channel.
• Moderation — Ban, kick, timeout, purge, warnings and more, all backed by persistent case tracking.
• AutoMod — Automated rule enforcement for spam, banned words and unwanted content.
• Logging — Event logging for messages, members, moderation actions and server changes.
• Welcomer & Goodbyer — Customizable join and leave messages.
• Economy — Currency, jobs, gambling and per-server tuning of every payout and cooldown.
• Fun Commands — Jokes, facts, memes, roasts and more from bundled content packs.
• Customization — Rebrand Clark's replies and behaviour per server.
• Help Menu — Interactive help, generated from the live command tree so it never goes stale.

Tech Stack

• Language: Python 3.14
• Framework: discord.py 2.6
• Database: PostgreSQL via asyncpg (connection pool)
• AI: Groq (groq async client)
• Deployment: Docker (Python 3.14 slim, runs as non-root)

Getting Started

You'll need Python 3.14+, a running PostgreSQL database, a Discord bot token, and a Groq API key.

# Clone the repo
git clone https://github.com/usekiko/Clark-open-sourced.git
cd Clark-open-sourced

# Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Create your .env file (see the Configuration section below)
cp .env.example .env             # Windows: copy .env.example .env

# Run the bot
python clark.py

On startup Clark connects to the database, loads every cog in ./cogs, and syncs its slash commands globally. Global command sync can take up to an hour to propagate the first time — this is a Discord limitation, not a bug.

On the Discord Developer Portal, enable the Server Members, Message Content, and Presence privileged intents for your bot.

Configuration

Clark is configured entirely through environment variables. Create a .env file in the project root with the following values:

• DISCORD_TOKEN — Your bot token from the Discord Developer Portal → your app → Bot → Reset Token.
• GROQ_API_KEY — API key for the AI chatbot, from the Groq Console.
• PG_HOST — PostgreSQL host (defaults to localhost).
• PG_PORT — PostgreSQL port (defaults to 5432).
• PG_USER — PostgreSQL username.
• PG_PASSWORD — PostgreSQL password.
• PG_DATABASE — Name of the database Clark should use.

Each cog creates its own tables on first run, so you only need to provide an empty, reachable database — no manual schema setup required.

Running with Docker

A Dockerfile is included. It installs the native libraries the bot needs, then runs as a non-root user.

# Build the image
docker build -t clark .

# Run it, mounting your .env read-only
docker run --env-file .env clark

Point PG_HOST at a database reachable from inside the container (for example a linked Postgres container or your host's address rather than localhost).

Project Structure

clark.py        # Entry point: bot setup, DB pool, cog loading, command sync
cogs/           # Feature modules (AI, moderation, automod, logging, economy, ...)
utils/          # Shared helpers (colours, embeds, schema repair)
json/           # Content packs for fun commands (jokes, facts, memes, roasts)
Dockerfile      # Container build
requirements.txt

License

AGPL-3.0 — You're free to use, study, and modify Clark, but any public deployment (including running it as a hosted service) must make the corresponding source code available under the same license.

---

Built by @usekiko