Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/noskap/kojima-bot/llms.txt

Use this file to discover all available pages before exploring further.

Kojima Bot is designed to go from zero to running in under ten minutes. You need two things before starting: the Bun runtime on your host machine and a Discord application with a bot token. Follow the steps below and you’ll have a live bot taking catches before your first coffee goes cold.
1

Prerequisites

Install Bun on your machine if you haven’t already:
curl -fsSL https://bun.sh/install | bash
Then create a Discord application:
  1. Go to https://discord.com/developers/applications and click New Application.
  2. Give it a name, then navigate to the Bot tab.
  3. Click Reset Token to generate a bot token — copy it somewhere safe.
  4. Under Privileged Gateway Intents, enable Message Content Intent (required for catch-phrase detection).
  5. Note your Application ID from the General Information tab — this is your CLIENT_ID.
  6. Enable Developer Mode in Discord (User Settings → Advanced), then right-click your server and copy the Server ID — this is your GUILD_ID.
2

Clone and install

Clone the repository and install dependencies with Bun:
git clone https://github.com/noskap/kojima-bot.git && cd kojima-bot

bun install
Bun reads package.json and installs Discord.js v14, Drizzle ORM, dotenv, and the remaining dependencies into a local node_modules directory.
3

Configure environment

Copy the example environment file and open it in your editor:
cp .env.example .env
The full contents of .env.example are:
# Required (Discord Developer Portal → your app → Bot token; Application ID = CLIENT_ID)
DISCORD_TOKEN=your_token_here
CLIENT_ID=your_client_id_here
GUILD_ID=your_guild_id_here

# Re-skin the catch game label (default if unset: Cat)
ENTITY_NAME=Kojima

# Optional: phrase users type to catch (default: ENTITY_NAME lowercased)
# CATCH_TRIGGER=kojima

# Optional: mirror pasted social URLs for better Discord embeds.
# Deletes the user's message and reposts "**Name** shared:\n<fixed URLs>"
# Requires Manage Messages + Send Messages in that channel/thread.
# Enable with: true, 1, yes, or on
LINK_FIXUP_X=false
LINK_FIXUP_INSTAGRAM=false

# Optional: SQLite file path (default: bot.sqlite next to cwd)
# DB_FILE=bot.sqlite
At minimum you must fill in the three required variables:
VariableWhere to find it
DISCORD_TOKENDiscord Developer Portal → your app → Bot tab → Token
CLIENT_IDDiscord Developer Portal → your app → General Information → Application ID
GUILD_IDRight-click your Discord server (Developer Mode on) → Copy Server ID
4

Deploy slash commands

Register the bot’s slash commands to your guild:
bun run deploy
This runs src/deploy-commands.ts, which calls the Discord REST API to register all commands scoped to the GUILD_ID from your .env. Guild-scoped registration takes effect instantly — no one-hour propagation delay. Re-run this command any time you add or rename a command.
5

Start the bot

Launch Kojima Bot in production mode:
bun start
Or start in watch mode during development (the process restarts automatically on file changes):
bun run dev
You should see a ready log line in your terminal confirming the bot has connected to Discord. The SQLite database file (bot.sqlite by default) is created automatically on first run.

​
First steps in Discord

Once the bot is online, do the following in your Discord server:
  1. Invite the bot to your server with the required permissions. In the Discord Developer Portal, navigate to OAuth2 → URL Generator, select the bot and applications.commands scopes, then check the permissions listed in the next section. Open the generated URL in your browser to add the bot.
  2. Run /kojima setup in the channel where you want entities to spawn. This opts the channel in to the spawn scheduler. You need Manage Channels permission to run this command.
  3. Wait for a spawn. An embed will appear with a spawn card and a Catch button. Type the catch phrase (default: kojima, or whatever you set as CATCH_TRIGGER) or press the button — whichever comes first wins.
  4. Check the leaderboard with /kojima leaderboard to see catch counts ranked across all players in the server.

​
Required bot permissions

Grant these permissions when inviting the bot, or set them on the individual channel via a channel-specific permission override:
PermissionPurpose
Send MessagesPost spawn embeds and command responses
Attach FilesSend the generated spawn card images
Embed LinksRender rich embed cards
Read Message HistoryRead context for catch detection
Add Reactions (optional)Add a 😂 reaction on mistyped catch attempts
Manage Messages (if link fixup enabled)Delete and repost messages with fixed URLs
Run bun run dev during development — the bot restarts automatically when you edit source files. This is powered by Bun’s built-in --watch flag and requires no external tool like nodemon.

Build docs developers (and LLMs) love

Get started for freeTalk to us