Artwork by Pieter Jordaan

Rooivalk

Rooivalk is a Discord bot that leverages OpenAI's API to generate responses when mentioned in a Discord server.
It is written in TypeScript and designed for easy customization and extension.

Features

• AI-powered responses: Integrates with OpenAI for chat completions and image generation using gpt-image-1
• Smart conversation handling: Responds to mentions, replies to bot messages, and automatically creates threads
• Thread management: Automatic thread creation when users reply to bot messages, with full conversation continuity and initial context preservation
• Weather integration: Fetches weather data from Yr.no for enhanced contextual responses and daily MOTD
• Scheduled tasks: Configurable MOTD (Message of the Day) via cron jobs
• Hot-reloadable configuration: Runtime configuration updates via config/*.md files
• Robust testing: Comprehensive test suite with dedicated utilities for mocking Discord interactions and service dependencies

Rooivalk in action

Discord_jNpyZBfPt2.mp4

Setup

Prerequisites

• Node.js (v22 or newer recommended)
• pnpm (v10.x recommended)
• A Discord bot token (guide)
• An OpenAI API key (guide)

Installation

1. Clone the repository:

   git clone https://github.com/fjlaubscher/rooivalk.git
   cd rooivalk

2. Install dependencies:

   pnpm install

3. Create a .env file in the root directory with the following contents:

   DISCORD_STARTUP_CHANNEL_ID=channelidforstartup
   DISCORD_MOTD_CHANNEL_ID=channelidformotd
   DISCORD_TOKEN=discord_app_token
   DISCORD_GUILD_ID=discord_server_id
   DISCORD_APP_ID=discord_app_id
   DISCORD_ALLOWED_APPS=comma,separated,app,ids
   OPENAI_API_KEY=openai_key
   OPENAI_MODEL=gpt-4.1-mini-2025-04-14
   OPENAI_IMAGE_MODEL=gpt-image-1
   ROOIVALK_MOTD_CRON="0 8 * * *"

4. Start the bot (uses native TypeScript execution):

   pnpm start

Detailed Project Structure

For a detailed breakdown of the project structure, please refer to AGENTS.md.

Customization

The bot uses a modular service-based architecture with helper utilities. Each service has its own AGENTS.md file with specific guidance:

• DiscordService (src/services/discord/): Discord API integration and thread management
  • helpers.ts: Message parsing and formatting utilities
• OpenAIService (src/services/openai/): OpenAI API integration for chat and image generation
• RooivalkService (src/services/rooivalk/): Core business logic and message processing
  • helpers.ts: Thread detection and reply handling utilities
• YrService (src/services/yr/): Weather data integration from Yr.no
• CronService (src/services/cron/): Scheduled tasks and background jobs
• Config System (src/config/): Hot-reloadable configuration loading and watching

See AGENTS.md for comprehensive architecture and development guidelines.

Prompt & Persona Tuning

• Edit config/instructions.md to adjust Rooivalk's lore, tone, and response rules. The file is hot-reloaded, so changes take effect without redeploying.
• Available placeholders:
  • {{CURRENT_DATE}} – replaced with the current ISO date before sending prompts.
  • {{EMOJIS}} – populated with the server's allowed custom emojis (one per line).
  • {{CONVERSATION_HISTORY}} – replaced with the most recent sortie log (or a fallback line when no history exists). History is automatically truncated to keep prompts lean.
• Set LOG_LEVEL=debug to emit prompt-metric debug logs (instructions length, presence of history, attachment count) ahead of each OpenAI request.

Continuous Integration

This project uses GitHub Actions to automatically run tests and deploy the bot. The workflows are located in .github/workflows/:

• test.yml: Runs tests on every push and pull request to the main branch.
• deploy.yml: Handles deployment tasks.

No additional setup is required—tests and deployments will run automatically if you push changes or open a pull request.

---

Notes

• The codebase is written in modern TypeScript, using strict mode and modular architecture.
• All tests are written using Vitest, with comprehensive test utilities in src/test-utils/ for mocking Discord interactions, environment variables, and common configurations.

License

MIT

This image was generated by @rooivalk.