GitHub - remorses/kimaki: Control opencode agents inside Discord. Each opencode project is a Discord channel. Start sessions creating threads. Supports voice channels.

Kimaki is a Discord bot that lets you control OpenCode coding sessions from Discord. Send a message in a Discord channel → an AI agent edits code on your machine.

Quick Start

That's it. The CLI guides you through everything.

What is Kimaki?

Kimaki connects Discord to OpenCode, a coding agent similar to Claude Code. Each Discord channel is linked to a project directory on your machine. When you send a message in that channel, Kimaki starts an OpenCode session that can:

• Read and edit files
• Run terminal commands
• Search your codebase
• Use any tools you've configured

Think of it as texting your codebase. You describe what you want, the AI does it.

Installation & Setup

Run the CLI and follow the interactive prompts:

The setup wizard will:

1. Create a Discord Bot - Walk you through creating a bot at discord.com/developers
2. Configure Bot Settings - Enable required intents (Message Content, Server Members, Voice States)
3. Install to Your Server - Generate an invite link with proper permissions
4. Select Projects - Choose which OpenCode projects to add as Discord channels
5. Voice Setup (Optional) - Request a Google Gemini API key for voice features

Keep the CLI running. It's the bridge between Discord and your machine.

Architecture: One Bot Per Machine

Each Discord bot you create is tied to one machine. This is by design.

When you run kimaki on a computer, it spawns OpenCode servers for projects on that machine. The bot can only access directories on the machine where it's running.

To control multiple machines:

1. Create a separate Discord bot for each machine
2. Run kimaki on each machine with its own bot token
3. Add all bots to the same Discord server

Each channel shows which bot (machine) it's connected to. You can have channels from different machines in the same server, controlled by different bots.

Running Multiple Instances

By default, Kimaki stores its data in ~/.kimaki. To run multiple bot instances on the same machine (e.g., for different teams or projects), use the --data-dir option:

# Instance 1 - uses default ~/.kimaki
npx -y kimaki@latest

# Instance 2 - separate data directory
npx -y kimaki@latest --data-dir ~/work-bot

# Instance 3 - another separate instance
npx -y kimaki@latest --data-dir ~/personal-bot

Each instance has its own:

• Database - Bot credentials, channel mappings, session history
• Projects directory - Where /create-new-project creates new folders
• Lock port - Derived from the data directory path, so instances don't conflict

This lets you run completely isolated bots on the same machine, each with their own Discord app and configuration.

Multiple Discord Servers

A single Kimaki instance can serve multiple Discord servers. Install the bot in each server using the install URL shown during setup, then add project channels to each server.

Method 1: Use /add-project command

1. Run npx kimaki once to set up the bot
2. Install the bot in both servers using the install URL
3. In Server A: run /add-project and select your project
4. In Server B: run /add-project and select your project

The /add-project command creates channels in whichever server you run it from.

Method 2: Re-run CLI with --add-channels

1. Run npx kimaki - set up bot, install in both servers, create channels in first server
2. Run npx kimaki --add-channels - select projects for the second server

The setup wizard lets you pick one server at a time.

You can even link the same project to channels in multiple servers - both will point to the same directory on your machine.

Best Practices

Create a dedicated Discord server for your agents. This keeps your coding sessions separate from other servers and gives you full control over permissions.

Add all your bots to that server. One server, multiple machines. Each channel is clearly labeled with its project directory.

Use the "Kimaki" role for team access. Create a role named "Kimaki" (case-insensitive) and assign it to users who should be able to trigger sessions.

Send long prompts as file attachments. Discord has character limits for messages. Tap the plus icon and use "Send message as file" for longer prompts. Kimaki reads file attachments as your message.

Required Permissions

Only users with these Discord permissions can interact with the bot:

• Server Owner - Full access
• Administrator - Full access
• Manage Server - Full access
• "Kimaki" role - Create a role with this name and assign to trusted users

Messages from users without these permissions are ignored.

Features

Text Messages

Send any message in a channel linked to a project. Kimaki creates a thread and starts an OpenCode session.

File Attachments

Attach images, code files, or any other files to your message. Kimaki includes them in the session context.

Voice Messages

Record a voice message in Discord. Kimaki transcribes it using Google's Gemini API and processes it as text. The transcription uses your project's file tree for accuracy, recognizing function names and file paths you mention.

Requires a Gemini API key (prompted during setup).

Voice Channels

Join a voice channel linked to a project for real-time voice interaction. Talk naturally, and Kimaki responds with voice—like having Jarvis for your codebase.

Uses Gemini's native audio model for low-latency conversation.

Session Management

• Resume sessions - Continue where you left off
• Fork sessions - Branch from any message in the conversation
• Share sessions - Generate public URLs to share your session

Message Queue

Use /queue <message> to queue a follow-up message while the AI is still responding. The queued message sends automatically when the current response finishes. If no response is in progress, it sends immediately. Useful for chaining tasks without waiting.

Commands Reference

Text Interaction

Just send a message in any channel linked to a project. Kimaki handles the rest.

Slash Commands

CLI Commands

# Start the bot (interactive setup on first run)
npx -y kimaki@latest

# Upload files to a Discord thread
npx -y kimaki upload-to-discord --session <session-id> <file1> [file2...]

# Start a session programmatically (useful for CI/automation)
npx -y kimaki start-session --channel <channel-id> --prompt "your prompt"

Programmatically Start Sessions

You can start Kimaki sessions from CI pipelines, cron jobs, or any automation. The start-session command creates a Discord thread, and the running bot on your machine picks it up.

Environment Variables

CLI Options

npx -y kimaki start-session \
  --channel <channel-id>  # Required: Discord channel ID
  --prompt <prompt>       # Required: Initial prompt for the session
  --name <name>           # Optional: Thread name (defaults to prompt preview)
  --app-id <app-id>       # Optional: Bot application ID for validation

Example: GitHub Actions on New Issues

This workflow starts a Kimaki session whenever a new issue is opened:

# .github/workflows/investigate-issues.yml
name: Investigate New Issues

on:
  issues:
    types: [opened]

jobs:
  investigate:
    runs-on: ubuntu-latest
    steps:
      - name: Start Kimaki Session
        env:
          KIMAKI_BOT_TOKEN: ${{ secrets.KIMAKI_BOT_TOKEN }}
        run: |
          npx -y kimaki start-session \
            --channel "1234567890123456789" \
            --prompt "Investigate issue ${{ github.event.issue.html_url }} using gh cli. Try fixing it in a new worktree ./${{ github.event.issue.number }}" \
            --name "Issue #${{ github.event.issue.number }}"

Setup:

1. Add KIMAKI_BOT_TOKEN to your repository secrets (Settings → Secrets → Actions)
2. Replace 1234567890123456789 with your Discord channel ID (right-click channel → Copy Channel ID)
3. Make sure the Kimaki bot is running on your machine

How It Works

1. CI runs start-session → Creates a Discord thread with magic prefix
2. Running bot detects thread → Recognizes the 🤖 **Bot-initiated session** prefix
3. Bot starts OpenCode session → Uses the prompt from the thread
4. AI investigates → Runs on your machine with full codebase access

How It Works

SQLite Database - Kimaki stores state in <data-dir>/discord-sessions.db (default: ~/.kimaki/discord-sessions.db). This maps Discord threads to OpenCode sessions, channels to directories, and stores your bot credentials. Use --data-dir to change the location.

OpenCode Servers - When you message a channel, Kimaki spawns (or reuses) an OpenCode server for that project directory. The server handles the actual AI coding session.

Channel Metadata - Each channel's topic contains XML metadata linking it to a directory and bot:

<kimaki><directory>/path/to/project</directory><app>bot_id</app></kimaki>

Voice Processing - Voice features run in a worker thread. Audio flows: Discord Opus → Decoder → Downsample (48kHz→16kHz) → Gemini API → Response → Upsample → Opus → Discord.

Graceful Restart - Send SIGUSR2 to restart the bot with new code without losing connections.

Model & Agent Configuration

Set the AI model in your project's opencode.json:

{
  "model": "anthropic/claude-sonnet-4-20250514"
}

Format: provider/model-name

Examples:

• anthropic/claude-sonnet-4-20250514 - Claude Sonnet 4
• anthropic/claude-opus-4-20250514 - Claude Opus 4
• openai/gpt-4o - GPT-4o
• google/gemini-2.5-pro - Gemini 2.5 Pro

Or use these Discord commands to change settings per channel/session:

• /model - Select a different AI model
• /agent - Select a different agent (if you have multiple agents configured in your project)