Documentation Index

Fetch the complete documentation index at: https://mintlify.com/remorses/kimaki/llms.txt

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

​

System Architecture

​

Core Architecture

​

One Bot Per Machine

Discord Server
├── Bot 1 (Machine A)
│   ├── Project A channels
│   └── Project B channels
└── Bot 2 (Machine B)
    ├── Project C channels
    └── Project D channels

• It spawns OpenCode servers for projects on that machine
• The bot can only access directories where it’s running
• Channel metadata stores which bot (app ID) owns each channel

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

​

Component Overview

​

Discord Bot (discord-bot.ts)

• Message routing: Routes messages from text channels and threads to OpenCode sessions
• Permission checks: Validates user permissions (Server Owner, Administrator, Manage Server, or “Kimaki” role)
• Worktree management: Creates isolated git worktrees for feature development
• Voice processing: Transcribes voice messages using Gemini API

​

Session Handler (session-handler.ts)

• Session creation/reuse: Creates new sessions or reuses existing ones per thread
• Event streaming: Subscribes to OpenCode SSE events for real-time updates
• Abort handling: Manages session interrupts when new messages arrive
• Message queue: Queues follow-up messages while AI is responding

​

OpenCode Server Manager (opencode.ts)

• Per-directory servers: One OpenCode server process per project directory
• Auto-restart: Automatically restarts crashed servers with exponential backoff
• Port allocation: Dynamically allocates ports for each server
• Health checks: Monitors server health via /api/health endpoint

​

SQLite Database (database.ts)

// Key data stored
- Channel → Directory mapping
- Thread → Session mapping
- Thread → Worktree mapping
- Session preferences (model, agent)
- Scheduled tasks

​

Channel Management (channel-management.ts)

• Creates text channels under “Kimaki” category
• Creates voice channels under “Kimaki Audio” category
• Stores channel configuration in SQLite (not in channel topic)
• Maps channels to project directories

​

Data Flow

​

Message Flow: Discord → OpenCode

1. User sends message in Discord channel
   ↓
2. discord-bot.ts validates permissions
   ↓
3. Creates/reuses thread
   ↓
4. session-handler.ts creates/gets OpenCode session
   ↓
5. Initializes OpenCode server (if not running)
   ↓
6. Sends prompt via SDK: client.session.prompt()
   ↓
7. Subscribes to SSE events: client.event.subscribe()

​

Response Flow: OpenCode → Discord

1. OpenCode emits SSE events
   ↓
2. session-handler.ts processes events:
   - message.updated → buffer parts
   - step-finish → flush buffered parts
   - permission.request → show buttons
   - question.request → show dropdowns
   ↓
3. Format parts as markdown
   ↓
4. Split long messages for Discord limits
   ↓
5. Send to thread via discord-utils.ts

​

Process Architecture

​

Bot Process

# Single Node.js process running:
- Discord gateway connection
- SQLite database
- Task runner (scheduled tasks)
- Hrana server (remote DB access)
- Voice worker thread

​

OpenCode Server Processes

# Separate process per project directory:
spawn('opencode', ['dev', '--port', dynamicPort], {
  cwd: projectDirectory,
  env: {
    KIMAKI_DATA_DIR: dataDir,
    KIMAKI_BOT_TOKEN: token,
    KIMAKI_LOCK_PORT: lockPort,
    ...(originalRepoDir && {
      OPENCODE_ORIGINAL_REPO_DIRECTORY: originalRepoDir
    })
  }
})

​

Plugin System

• Runs inside OpenCode server process (not bot process)
• Cannot access bot-side config directly
• Receives bot state via KIMAKI_* env vars
• Provides custom tools: kimaki_question, kimaki_action_buttons, kimaki_file_upload

​

Lock Port & Single Instance

// Default: derived from data directory hash
const lockPort = deriveLockPort(dataDir)

// Override for multiple instances:
KIMAKI_LOCK_PORT=31001 kimaki --data-dir ~/bot1
KIMAKI_LOCK_PORT=31002 kimaki --data-dir ~/bot2

​

Logging & Debugging

​

Log File

• Reset on every bot startup
• Contains logs from current run only
• Use for debugging session failures and internal issues

​

Heap Snapshots

# Manual snapshot trigger
kill -SIGUSR1 <PID>

# Automatic: at 85% heap usage
# Saved to: ~/.kimaki/heap-snapshots/

​

Graceful Restart

# Restart with new code without losing connections
kill -SIGUSR2 <PID>

​

Multiple Instances

# Instance 1 (default)
kimaki

# Instance 2 (separate data + port)
KIMAKI_LOCK_PORT=31001 kimaki --data-dir ~/work-bot

# Instance 3
KIMAKI_LOCK_PORT=31002 kimaki --data-dir ~/personal-bot

• Database
• Projects directory
• Lock port
• Discord bot credentials

​

Network Topology

Internet
  ↓
Discord Gateway (WebSocket)
  ↓
Kimaki Bot Process
  ↓
Localhost HTTP (dynamic ports)
  ↓
OpenCode Server Processes
  ↓
Local Filesystem

​

Security Model

• Permission checks: Every message validates Discord roles/permissions
• Tool permissions: OpenCode permission.ask events trigger Discord buttons
• No remote code execution: Users cannot run arbitrary commands without approval
• Isolated worktrees: Each thread can use a separate git worktree
• Local-only servers: OpenCode servers only bind to localhost

​

Performance Considerations

​

Connection Pool

// Increased from default to prevent SSE deadlock
setGlobalDispatcher(new Agent({ 
  connections: 500,
  headersTimeout: 0,
  bodyTimeout: 0 
}))

​

Thread Message Queue

const threadMessageQueue = new Map<string, Promise<void>>()

​

Error Handling

const result = await errore.tryAsync(() => client.session.get({...}))
if (result instanceof Error) {
  // Handle error
}
// Use result.data

• Console (with prefixes like [SESSION], [OPENCODE])
• Sentry (for production monitoring)
• Log file (kimaki.log)