Artwork by Pieter Jordaan

Rooivalk

A Discord bot powered by OpenAI. Responds to mentions and replies, threads its own conversations, and exposes tools the model can invoke directly.

Features

• Chat & reasoning via the OpenAI Responses API. Conversation continuity is handled server-side through previous_response_id; per-conversation ids live in SQLite (conversation_responses).
• Image generation via OpenAI gpt-image-1 (or xAI grok-imagine-image-quality when configured), exposed as a slash command and as the generate_image function tool so the model can produce images inline.
• Threads: replying to a bot message auto-creates a thread; the bot responds to everything inside threads it owns.
• Per-user memory in SQLite — the model can remember, recall, and forget facts. Capped preference set is injected on every turn.
• Tools: weather (Yr.no), Steam store lookups, ad-hoc SQLite querying of the bot's own data, sandboxed run_bash for log/source inspection, server-event lookup.
• Daily MOTD with AI-generated city artwork; Peapix (Bing image of the day) as a fallback.
• Hot-reloadable config — edit config/*.md or config/tool-roles.json and changes take effect without redeploying.

Rooivalk in action

Discord_jNpyZBfPt2.mp4

Setup

Prerequisites

• Node.js v24+
• pnpm v10.x
• Discord bot token (guide)
• OpenAI API key (guide)

Installation

git clone https://github.com/fjlaubscher/rooivalk.git
cd rooivalk
pnpm install
cp .env.example .env   # fill in credentials
pnpm start

Key env vars:

Variable	Description
DISCORD_TOKEN / DISCORD_GUILD_ID / DISCORD_APP_ID	Discord bot credentials
DISCORD_STARTUP_CHANNEL_ID / DISCORD_MOTD_CHANNEL_ID	Startup announcement and MOTD post target
OPENAI_API_KEY + OPENAI_MODEL	Chat / reasoning credentials and model
OPENAI_IMAGE_MODEL	Image generation model
ROOIVALK_MOTD_CRON	Cron expression for the daily MOTD (e.g. "0 8 * * *")
ROOIVALK_DB_PATH	SQLite path (default ./data/rooivalk.db)
XAI_API_KEY / XAI_MODEL / XAI_IMAGE_MODEL	Optional; route chat and/or image generation to xAI Grok via the OpenAI SDK
STEAM_API_KEY	Required for the nightly Steam catalogue sync that backs get_game_listing

Services

Each service has its own AGENTS.md:

• src/services/openai — OpenAI chat + image generation
• src/services/xai — xAI Grok chat + image provider (OpenAI-SDK compatible)
• src/services/chat — provider + channel-routing factories (chat, image, per-channel behaviours)
• src/services/rooivalk — message processing, tool dispatch, MOTD
• src/services/discord — Discord API integration and thread handling
• src/services/memory — SQLite-backed memory + conversation-id store
• src/services/yr — Yr.no weather
• src/services/steam — Steam store + nightly app catalogue sync
• src/services/peapix — Bing image-of-the-day fallback for MOTD
• src/services/cron — scheduled jobs
• src/config — hot-reloadable markdown config

For architecture and conventions, see AGENTS.md.

Prompt tuning

• config/instructions/openai.md and config/instructions/xai.md are the live per-provider system prompts. Hot-reloaded.
• Placeholders: {{CURRENT_DATE}} (ISO date), {{EMOJIS}} (server's allowed custom emojis).
• LOG_LEVEL=debug emits per-request prompt metrics.
• Channel-specific behaviours are declared as profiles in config/profiles.json (copy config/profiles.example.json); each profile's instructions live in config/profiles/<name>.md and it may override the model/provider.

CI/CD

• .github/workflows/test.yml — Prettier + Vitest on every push/PR to main.
• .github/workflows/deploy.yml — rsync + PM2 restart on main after tests pass. PM2 runs via ecosystem.config.cjs for timestamped logs and managed restarts.

License

MIT

Generated by @rooivalk.