Kimaki

Kimaki is a Discord bot that bridges OpenCode AI coding sessions to Discord. It lets you send a message in a Discord channel and have an AI agent edit code on your machine — essentially texting your codebase. Each channel maps to a project directory, and when you send a message, Kimaki spawns an OpenCode session that can read/edit files, run terminal commands, and search your codebase.

Quick References

File	Purpose
README.md	Full documentation with setup guide, architecture, and all features
discord/src/cli.ts	CLI entry point — all commands (send, project add, session, tunnel, etc.)
discord/src/discord-bot.ts	Discord bot core — message handling, channel management
discord/src/session-handler.ts	OpenCode session lifecycle — streaming, permissions, abort
discord/package.json	Published package (kimaki on npm), version and dependencies

When to Use

• You want to control an AI coding agent from Discord instead of a terminal
• You need to trigger AI coding sessions from CI/CD pipelines (GitHub Actions, cron jobs)
• You want a team-accessible interface where multiple people can interact with a coding agent
• You need to manage AI coding sessions across multiple machines from a single Discord server
• You want voice-to-code capability — record a Discord voice message and have it transcribed into an AI coding prompt

Installation

# Run directly with npx (interactive setup on first run)
npx -y kimaki@latest

# Or install globally
npm install -g kimaki

The first run launches an interactive setup wizard that walks you through creating a Discord bot, enabling required intents, installing it to your server, and selecting project directories.

Prerequisites

• Node.js (for npx/npm)
• OpenCode — installed automatically if missing (curl -fsSL https://opencode.ai/install | bash)
• Bun — installed automatically if missing (curl -fsSL https://bun.sh/install | bash)
• A Discord bot created at discord.com/developers

Best Practices

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

2. 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. Only Server Owners, Admins, Manage Server permission holders, and Kimaki role members can interact with the bot.

3. Send long prompts as file attachments. Discord has a 2000-character message limit. Use the plus icon → "Send message as file" for longer prompts. Kimaki reads file attachments as your message content.

4. Use --data-dir to run multiple isolated bot instances on the same machine. Each instance gets its own database, project mappings, and lock port.

5. Configure tool permissions in opencode.json. Customize which tools auto-approve, prompt for approval, or are denied. By default, tools accessing paths outside the project directory prompt for approval.

6. Use --notify-only for webhook-style events. Create a thread without starting an AI session, then reply later to start a session with the notification as context.

Common Patterns

Basic Setup (Interactive):

npx -y kimaki@latest

Follow the prompts to enter your Discord Application ID, enable intents, paste your bot token, and select projects.

Start a Session from CI (GitHub Actions):

# .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 send \
            --channel "1234567890123456789" \
            --prompt "Investigate issue ${{ github.event.issue.html_url }}" \
            --name "Issue #${{ github.event.issue.number }}"

Send to an Existing Thread:

# By thread ID
npx -y kimaki send --thread 1234567890 --prompt "follow-up message"

# By session ID
npx -y kimaki send --session ses_abc123 --prompt "continue working on this"

Create a Session in a Git Worktree:

npx -y kimaki send \
  --channel 1234567890 \
  --prompt "implement feature X" \
  --worktree feature-x

Add a Project Directory Without Starting a Session:

# Current directory
npx -y kimaki project add

# Specific directory
npx -y kimaki project add /path/to/project

# With explicit guild
npx -y kimaki project add ./myproject --guild 123456789

Run Multiple Bot Instances on One Machine:

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

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

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

Configure Tool Permissions (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    },
    "external_directory": {
      "~/other-project/**": "allow"
    }
  }
}

Configure the AI Model (opencode.json):

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

Wait for Session Completion and Get Output:

npx -y kimaki send \
  --channel 1234567890 \
  --prompt "run the test suite" \
  --wait

CLI Commands Reference

Command	Description
kimaki	Start the bot (interactive setup on first run)
kimaki --restart	Re-run setup with new credentials
kimaki --add-channels	Select projects to create Discord channels
kimaki --data-dir <path>	Use a custom data directory
kimaki --use-worktrees	Auto-create git worktrees for all new sessions
kimaki --mention-mode	Bot only responds when @mentioned
kimaki --verbosity <level>	Set default output verbosity (tools-and-text, text-and-essential-tools, text-only)
kimaki --no-critique	Disable automatic diff upload to critique.work
kimaki --install-url	Print the bot install URL and exit
kimaki send	Send a message to create/continue a thread (see options below)
kimaki upload-to-discord	Upload files to a Discord thread
kimaki project add [dir]	Create Discord channels for a project
kimaki project list	List registered projects and their channels
kimaki project create <name>	Create a new project folder with git and Discord channels
kimaki project open-in-discord	Open current project's channel in Discord
kimaki session list	List OpenCode sessions
kimaki session read <id>	Read a session conversation as markdown
kimaki session archive <threadId>	Archive a thread and stop its session
kimaki tunnel -p <port>	Expose a local port via tunnel (kimaki.xyz)
kimaki worktree merge	Merge worktree branch into default branch
kimaki upgrade	Upgrade to the latest version
kimaki sqlitedb	Show the database file location

send Command Options

Option	Description
-c, --channel <id>	Discord channel ID (creates new thread)
-d, --project <path>	Project directory (alternative to --channel)
-p, --prompt <text>	Message content (required)
-n, --name <name>	Thread name (optional)
--thread <id>	Post to an existing thread
--session <id>	Post to thread mapped to session
--worktree <name>	Create git worktree for session
--notify-only	Create thread without starting AI session
--wait	Wait for completion and print output to stdout
-u, --user <name>	Add a Discord user to the thread
--agent <agent>	Agent to use for the session
--model <model>	Model override (provider/model)
-a, --app-id <id>	Bot application ID

Discord Slash Commands

Command	Description
/session <prompt>	Start a new session with a prompt
/resume <session>	Resume a previous session (autocomplete)
/abort or /stop	Stop the current running session
/add-project <project>	Create channels for an OpenCode project
/create-new-project <name>	Create new project folder and start session
/new-worktree <name>	Create git worktree and start session
/merge-worktree	Merge worktree into default branch
/toggle-worktrees	Toggle auto-worktree for new sessions
/model	Change the AI model
/agent	Change the agent
/share	Generate a public URL to share the session
/diff	Show git diff as a shareable URL
/fork	Fork session from a past message
/queue <message>	Queue message to send after current response
/clear-queue	Clear all queued messages
/queue-command <cmd>	Queue a user command after current response
/undo	Undo last assistant message (revert changes)
/redo	Redo previously undone changes
/compact	Summarize conversation to reduce context
/verbosity	Set output verbosity level
/toggle-mention-mode	Toggle @mention-only mode
/login	Authenticate with an AI provider
/run-shell-command <cmd>	Run shell command in project directory
/context-usage	Show token usage and context window percentage
/restart-opencode-server	Restart OpenCode server for this channel
/upgrade-and-restart	Upgrade kimaki and restart

Environment Variables

Variable	Description
KIMAKI_BOT_TOKEN	Discord bot token (required for send in CI environments)
OPENCODE_PATH	Custom path to the opencode binary
BUN_PATH	Custom path to the bun binary

Permissions Model

Users must have one of these to interact with the bot:

• Server Owner, Administrator, or Manage Server permission
• "Kimaki" role (case-insensitive) — auto-created by the bot

To block a user even with the above permissions, assign them a "no-kimaki" role.

Architecture Overview

• One bot per machine — each Discord bot is tied to a machine where kimaki runs
• SQLite database at ~/.kimaki/discord-sessions.db stores credentials, channel mappings, and session history
• OpenCode servers are spawned per project directory and handle the actual AI coding work
• Channel metadata is stored in channel topics as XML: <kimaki><directory>/path</directory><app>id</app></kimaki>
• Voice messages are transcribed via Google Gemini API with code-aware context
• Graceful restart via SIGUSR2 signal — restarts without losing connections
• Heap snapshots via SIGUSR1 signal — writes .heapsnapshot to ~/.kimaki/heap-snapshots/

Supported Models

Format: provider/model-name

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

Models can be set globally in opencode.json, per-channel with /model, or per-session.