Artwork by Pieter Jordaan
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.
- Integrates with OpenAI for AI-generated replies and images.
- Responds to messages where the bot is mentioned and when replying to a message from the bot.
- Generate images with
/image - Generate informative responses with
/learn - Retry responses by reacting to a bot message with a specific emoji.
- Custom error messages for f 8000 ailed completions
- Fully configurable (with runtime "hot-reloading") system instructions and fallback messages via
config/*.mdfiles
Discord_jNpyZBfPt2.mp4
- Node.js (v22 or newer recommended)
- Yarn (v1.x recommended)
- A Discord bot token (guide)
- An OpenAI API key (guide)
- Clone the repository:
git clone https://github.com/fjlaubscher/rooivalk.git cd rooivalk - Install dependencies:
yarn install
- Create a
.envfile in the root directory with the following contents:DISCORD_STARTUP_CHANNEL_ID=channelidforstartup DISCORD_MOTD_CHANNEL_ID=channelidformotd DISCORD_LEARN_CHANNEL_ID=channelidforlearning DISCORD_TOKEN=discord_app_token DISCORD_GUILD_ID=discord_server_id DISCORD_APP_ID=discord_app_id OPENAI_API_KEY=openai_key OPENAI_MODEL=gpt-4.1-nano OPENAI_IMAGE_MODEL=gpt-image-1 ROOIVALK_MOTD_CRON="0 8 * * *"
- Build the project:
yarn build
- Start the bot:
yarn start
For a detailed breakdown of the project structure, please refer to AGENTS.md.
- Edit
src/services/openai/index.tsto change how prompts are sent to OpenAI. - Edit
src/services/rooivalk/index.tsto customize the bot's core logic and behavior. - Update constants in the respective
constants.tsfiles for configuration. - Test utilities are available in
src/test-utils/for mocking Discord messages in tests.
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 themainbranch.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.
- The codebase is written in modern TypeScript, using strict mode and modular architecture.
- All tests are written using Vitest, and test utilities are provided for mocking Discord interactions.
MIT
This image was generated by @rooivalk.