Discord Bot Setup

Create and configure your Discord bot with required intents and permissions

Kimaki requires a Discord bot application to connect Discord to OpenCode. This guide walks you through creating a bot, enabling required intents, and installing it in your server.

Create Discord Application

1. Navigate to Discord Developer Portal

   Go to discord.com/developers/applications and sign in with your Discord account.

2. Create New Application

   Click New Application and give your application a name (e.g., “Kimaki Bot” or your machine name).

3. Note Your Application ID

   Your Application ID is displayed at the top of the General Information page. You’ll need this later.

Configure Bot Intents

Intents control what events your bot can receive from Discord. Kimaki requires specific privileged intents to function.

1. Navigate to Bot Section

   Click Bot in the left sidebar of your application settings.

2. Enable Required Intents

   Scroll down to Privileged Gateway Intents and enable:

   • SERVER MEMBERS INTENT - Required to check user permissions
   • MESSAGE CONTENT INTENT - Required to read message content

   Both intents are required. The bot will not function without them.

3. Save Changes

   Click Save Changes at the bottom of the page.

Get Bot Token

The bot token authenticates your Kimaki instance with Discord.

1. Reset Token

   In the Bot section, click Reset Token to generate a new token.

   If this is your first time, the button may say Copy instead of Reset Token.

2. Copy Token

   Copy the token immediately. You won’t be able to see it again without resetting.

   Never share your bot token. Treat it like a password. Anyone with the token can control your bot.

3. Store Token Securely

   You’ll paste this token when running npx kimaki for the first time, or set it as the KIMAKI_BOT_TOKEN environment variable for automated deployments.

Install Bot to Server

Generate an invite URL with the correct permissions.

1. Get Install URL

   The Kimaki CLI generates an install URL with proper permissions during setup:

   https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&permissions=397552930880&scope=bot
   

   Replace YOUR_APP_ID with your Application ID, or let the CLI generate it for you.

2. Open URL in Browser

   Open the install URL in your browser. You’ll see Discord’s authorization page.

3. Select Server

   Choose the Discord server where you want to install the bot. You must have Manage Server permission.

4. Authorize Bot

   Review the permissions and click Authorize.

   The bot will appear in your server’s member list (offline until you start Kimaki).

Required Permissions

The install URL includes these permissions:

• View Channels - See channels in the server
• Send Messages - Reply to user messages
• Create Public Threads - Create threads for sessions
• Send Messages in Threads - Reply in session threads
• Manage Channels - Create project channels
• Manage Threads - Archive threads when sessions end
• Attach Files - Send file attachments in responses
• Read Message History - Resume sessions and fork from history
• Add Reactions - React to messages with status indicators
• Use External Emojis - Optional, for better status indicators
• Mention Everyone - Optional, allows the bot to mention @everyone if needed

The bot only uses permissions in channels it manages. It won’t modify other channels.

Bot Token Storage

Kimaki stores your bot token in ~/.kimaki/discord-sessions.db by default.

Environment Variable (CI/Automation):

For headless deployments, set KIMAKI_BOT_TOKEN instead:

export KIMAKI_BOT_TOKEN="your_bot_token_here"
npx kimaki

The environment variable takes precedence over the database.

Next Steps

Run Kimaki

Start the bot and create project channels

Configure Permissions

Customize tool permissions with opencode.json