Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Architecture: one bot per machine

Each Kimaki process belongs to one machine. It can only open folders on that machine.
  Discord ──> kimaki (bot process) ──> OpenCode 2 service ──> project folders
               ~/.kimaki                (shared with your TUI)   on this machine
The bot does not run its own OpenCode server. It uses your OpenCode 2 background service, the same one the OpenCode TUI uses. See Troubleshooting.

Multiple machines

To control several machines from one Discord server, run Kimaki in gateway mode on each machine and install the shared bot in the same server. Agents should follow Set up Kimaki from an agent.
  1. Run npx -y kimaki@latest --gateway on each machine
  2. Open the install URL and authorize the bot in the same Discord server
  3. Add projects with kimaki project add /path/to/repo on each machine
Each machine gets its own Discord category, Kimaki <machine name>. The default machine name is the hostname. Set another one with --machine-name:
npx -y kimaki@latest --gateway --machine-name vps
A bot only answers in the channels that its own machine added. To start a session on another machine from the CLI, kimaki send --channel <id> still works: the bot that owns the channel runs it.

Running multiple instances

To run a second bot on the same machine (for example a test install, or a bot for another team), give it a separate data directory and a free lock port:
# Instance 1: default ~/.kimaki, lock port 29988
npx -y kimaki@latest

# Instance 2: separate data directory and lock port
KIMAKI_LOCK_PORT=31001 npx -y kimaki@latest --data-dir ~/work-bot
The lock port is the single-instance lock. The default is 29988 for every data directory. If the port is busy, the second bot does not start and shows port is in use. It never stops the bot that already runs.
CLI subcommands talk to the bot through the lock port. Use the same port and data directory to reach the second bot:
KIMAKI_LOCK_PORT=31001 kimaki status --data-dir ~/work-bot
Inside a Kimaki session, the agent shell already has the right values.
Each instance has its own:
  • Database: <dataDir>/kimaki.db with bot credentials, channel mappings, and routines
  • Log: <dataDir>/kimaki.log
  • Default channel folder: <dataDir>/projects/kimaki
  • Lock port: from KIMAKI_LOCK_PORT
All instances use the same OpenCode 2 service. Session history lives there.

Multiple Discord servers

One Kimaki instance can serve several Discord servers. Install the bot in each server, then add project channels to each server.
  1. Print the install URL and open it once per server:
kimaki bot install-url
  1. Add a project to a server with --guild:
kimaki project add /path/to/repo --guild 123456789012345678
Without --guild, project add uses the server that already has Kimaki channels. When channels exist in several servers, --guild is required.
You can add the same folder in several servers. All channels point to the same folder on your machine.
When you start the bot and it is in several servers, first-run onboarding asks which server to use. Without a terminal, pass --guild <id>.

Docker on a VPS

To run Kimaki on a remote machine instead of your laptop, put it in a container with a persistent volume. The first start prints an install URL in the logs. See Deploy Kimaki on a VPS with Docker.