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

Set up Kimaki from an agent

Agents: read this page first when asked to install Kimaki on a machine or into a Discord server.
Do not invent a Discord bot. Do not clone the GitHub repo unless the user asks for a source checkout. Run the published CLI.
npx -y kimaki@latest --gateway
  target machine                 browser already on Discord                 Discord
 ┌──────────────────────┐       ┌───────────────────────────────┐       ┌─────────────┐
 │ kimaki --gateway     │──────>│ install_url                   │──────>│ pick server │
 │ wait for authorized  │       │ Playwriter, or send the user  │       │ Authorize   │
 │ then project add     │<──────│ the URL                       │<──────│             │
 └──────────────────────┘       └───────────────────────────────┘       └─────────────┘

1. Reach the machine

Kimaki runs on the machine that holds the code. SSH there, or open a shell on that box.
On a Mac you will control over SSH:
  1. Turn on Remote Login.
  2. Keep the Mac awake and unlocked. Ping can still work while SSH dies if the Mac slept or the lock screen is up.
  3. Disable sleep once SSH works:
sudo pmset -a sleep 0 disksleep 0 displaysleep 0
Need Node 20+ and git. Then use npx. Do not write helper scripts.
Kimaki needs OpenCode 2. It uses the OpenCode background service of the machine and does not bundle OpenCode. When no OpenCode is installed, Kimaki installs OpenCode 2 by itself. If the machine has OpenCode 1, Kimaki stops with an error. Then, after the user agrees, install OpenCode 2:
curl -fsSL https://opencode.ai/v2/install | bash
A second Kimaki on the same machine needs its own data dir and lock port. See Advanced Setup.

2. Start gateway mode

Gateway mode uses the shared Kimaki bot. No Discord Developer Portal.
npx -y kimaki@latest --gateway
Leave that process running. It is the bridge.
SSH and Docker have no TTY. Kimaki prints data: event lines on stdout. Watch for install_url:
data: {"type":"install_url","url":"https://kimaki.dev/discord-install?clientId=...&clientSecret=..."}
If the output scrolled away, print the URL again from another shell:
npx -y kimaki@latest bot install-url
That URL contains the client secret. Do not paste it in a public Discord channel. Authorization waits about 5 minutes. If it times out, run kimaki --gateway again: it reuses the same credentials and prints the same URL.

3. Install the bot in Discord

Open the install URL in a browser that is already logged into Discord. Pick the target server. Click Authorize.

Playwriter

Use Playwriter only when you can drive Chrome on a machine that is already logged into Discord. That can be the agent machine, not the Kimaki machine.
  1. Open the install URL.
  2. Select the Discord server.
  3. Click Continue, then Authorize.
  4. Wait until the page reaches kimaki.dev/install-success.
If Playwriter is missing, Discord is not logged in, or OAuth is stuck, stop. Send the user the URL in a private place and ask them to Authorize.

After Authorize

Watch the same Kimaki process:
EventMeaning
install_urlOpen this URL once
authorizedDiscord install succeeded
readyBot is connected and onboarding is done
errorRead message. Do not wipe ~/.kimaki
The bot creates its own Discord category, Kimaki <machine name>, with a #kimaki channel and an onboarding thread. Do not create categories by hand.

4. Map a project

From another shell on the same machine, while the bot is still running:
npx -y kimaki@latest project add /path/to/repo
The user can also ask in the onboarding thread: the agent there adds channels with the same command. Then run /login in Discord so the agent has a model. See Managing Projects and Models & Subscriptions.
Confirm:
npx -y kimaki@latest status
npx -y kimaki@latest project list
You want running: with "connected":true for OpenCode, and the new channel in project list. For errors, read the log:
tail -n 50 "$(npx -y kimaki@latest logs)"

5. VPS or Docker

On a VPS, prefer Docker with a persistent volume. Same gateway flow: copy install_url from docker compose logs -f, then Authorize.
Follow Deploy Kimaki on a VPS with Docker. Do not wrap that in extra scripts.
Without Docker, SSH in and run the same npx -y kimaki@latest --gateway command. Keep the process alive with the host's usual supervisor (systemd or a terminal multiplexer). Parse data: lines the same way.
Platforms that spawn Kimaki as a child process should read Programmatic Gateway.

Rules

  • Use npx -y kimaki@latest --gateway. Do not install from git.
  • Do not create a Discord application unless the user asks for self-hosted mode.
  • Do not clone this repo to run Kimaki. Source checkouts lag npm.
  • Do not share the install URL in public chat.
  • Do not stop an existing Kimaki on the machine. For a second instance, set KIMAKI_LOCK_PORT and --data-dir.
  • If the machine has OpenCode 1, ask the user before you install OpenCode 2. The install script can replace the opencode command in ~/.opencode/bin.
  • Do not rename Discord categories by API unless the user asks. Kimaki stores the category id.